ThinkPHP API 必须统一返回格式并规范路由：用封装方法或 json() 返回含 code/message/data 的 JSON；API 路由用 Route::apiResource() 避免冗余路径；版本放 URL 前缀如 /v1/；HTTP 状态码表通信层，业务 code 表领域逻辑，二者不可混用。
ThinkPHP API 接口必须强制统一返回格式，否则前端联调会反复出错；RESTful 路由不能靠手写一堆 Route::rule()，否则后期维护成本爆炸。
为什么不能用 return json() 直接返回
直接调用 PHP 原生 json() 或 ThinkPHP 的 return json($data) 会导致：状态码固定为 200、缺少业务码字段、无时间戳、无错误提示结构，前端无法区分「请求成功但业务失败」和「网络异常」。比如登录失败时返回 {"error": "密码错误"}，前端得额外判断 key 是否为 error，而统一格式应始终有 code 和 message 字段。
正确做法是封装一个基础响应方法，或直接使用框架内置的 think\Response\Json 类：
- 在控制器中写
return json(['code' => 200, 'message' => 'success', 'data' => $user]);是最低限度的合规写法 - 更推荐继承
think\Controller后，在基类控制器里定义success()/fail()方法，避免每个接口重复拼数组 - 注意：不要在
message里塞 HTML 或换行符，日志解析和前端 toast 显示都会出问题
Route::resource() 和 Route::apiResource() 的区别
ThinkPHP 6.0+ 支持 Route::apiResource()，它比 Route::resource() 更严格：自动禁用 create 和 edit 这两个非 RESTful 动词对应的路由（因为 API 不需要返回 HTML 表单页）。如果你用了 Route::resource('users', 'api/Users')，会多出 GET /users/create 这类无意义路径，被扫描工具扫到可能误判为信息泄露。
立即学习“PHP免费学习笔记（深入）”；
实操建议：
- API 模块一律用
Route::apiResource('users', 'api/Users') - 需要自定义某条路由（比如把
POST /users改成POST /v1/users/register），用->only(['store'])+ 单独Route::post()覆盖，别删默认路由再重写 - ThinkPHP 8 中
Route::apiResource()默认开启except过滤，create和edit已不生成 —— 但老项目升级后要检查路由缓存是否清除：php think route:clear
版本号怎么加进 URL 才不踩坑
把版本放在 URL 最前面（如 /v1/users）是唯一靠谱的做法。别用请求头 Accept: application/vnd.myapp.v1+json，PHP 框架层解析麻烦，Nginx 日志和网关策略也难匹配；也别用参数 ?version=v1，缓存、CDN、代理都可能丢掉它。
具体配置方式：
- 在
route/api.php里写Route::domain('api.example.com')->group(function () { Route::group('v1', function () { Route::apiResource('users', 'api/Users'); }); }); - 如果不用子域，就用前缀：
Route::group('api/v1', function () { Route::apiResource('users', 'api/Users'); }); - 注意：版本分组后，控制器里的
$this->request->url()返回的仍是相对路径，别依赖它拼完整 URL 给前端跳转
HTTP 状态码和业务 code 到底谁说了算
HTTP 状态码表达通信层结果（如 404=资源不存在，401=未认证，422=参数校验失败），业务 code（如 code: 1001）表达领域逻辑结果（如「余额不足」「活动已结束」）。两者必须同时存在，且不能混用。
常见错误：
- 登录失败返回 HTTP 200 +
code: 401—— 这会让 axios 默认不进catch，前端拿不到错误响应 - 用 500 代替所有业务异常 —— Nginx 日志里全是 500，根本分不清是代码崩了还是用户输错了手机号
- ThinkPHP 的
Validate失败默认抛ValidateException，会返回 HTTP 400，但 message 是中文数组，需在全局异常处理里 catch 并转成标准 JSON 格式
真正关键的细节是：前端 fetch 的 response.ok 只看 HTTP 状态码是否在 200–299，所以 4xx/5xx 必须由服务端明确返回，不能全压成 200 再靠业务 code 区分。
