ThinkPHPAPI接口开发_统一返回格式与RESTful规范【说明】-ThinkPHP-PHP中文网

thinkphp api 必须统一返回格式并规范路由：用封装方法或 json() 返回含 code/message/data 的 json；api 路由用 route::apiresource() 避免冗余路径；版本放 url 前缀如 /v1/；http 状态码表通信层，业务 code 表领域逻辑，二者不可混用。

thinkphpapi接口开发_统一返回格式与restful规范【说明】

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

编写健壮的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 区分。