ThinkPHP 6.x 的 make:controller 命令不支持 --api 参数，运行 php think make:controller User --api 会报错“Unknown option --api”；正确方式是使用 php think make:controller api/User 命名控制器，再手动配置资源路由、方法命名（如 index/read/save/update/delete）及显式返回 json() 响应。
thinkphp make:controller 不支持 --api 参数
直接运行 php think make:controller User --api 会报错：Unknown option --api。这不是你配置错了，是 ThinkPHP 6.x 的 make:controller 命令压根没实现这个参数——它只负责建文件和类壳，不生成 REST 方法体，也不自动注册路由。
真正能用的只有命名约定：php think make:controller api/User。这会在 app/controller/api/ 下生成控制器，路径自动对应 /api/user 类似前缀，但后续所有 REST 行为都得靠手动补全。
- 类名要改，比如
UserController extends BaseController -
BaseController中必须禁用视图（$this->view = null;或继承think\Controller） - 别指望命令帮你写
index()、save()这些方法，空文件就是空文件
Route::resource() 是 RESTful 路由的核心，但容易配错
资源路由不是“开了就灵”，它依赖三要素对齐：路由声明位置、控制器命名空间、方法名严格匹配。最常漏掉的是注册位置——必须在 app/route/app.php（非 api.php 或其他分组文件）中显式写：
Route::resource('user', 'api.User');
这条语句才会把 GET /user 映射到 api\UserController::index()，POST /user 映射到 save()，依此类推。
立即学习“PHP免费学习笔记（深入）”；
- 方法名必须是 ThinkPHP 约定的七个：
index、read、save、update、delete（注意不是show或list） - 如果用了多应用模式，确认
api是合法应用名（app/multi.php中已启用），否则api.User会解析失败 - 别把
Route::resource()套在中间件分组或子域名路由里，它不支持嵌套生效
返回 JSON 必须手动处理，不能依赖框架自动
ThinkPHP 默认响应类型是 HTML，哪怕你走的是 API 路由，return ['data' => $x] 也会输出未格式化的数组甚至触发模板渲染。必须显式调用 json()：
return json(['code' => 0, 'data' => $data]);
这是最容易被忽略的一环，尤其在调试时看到空白响应或 500 错误，八成是这里漏了。
- 不要用
echo json_encode(...)+exit，破坏框架生命周期 - 如果统一处理，可在
BaseController的initialize()中设header('Content-Type: application/json; charset=utf-8')，但仍需配合json()返回 - 业务状态码（如
code: 1001）和 HTTP 状态码（如 404、422）要分开设计，json()只管前者；后者用response()->code(404)
客户端发 PUT/DELETE 请求需要额外兼容
浏览器表单和多数前端请求库（如 axios 默认）不原生支持 PUT/DELETE，直接发过去会被当成 GET 或 405。服务端不会自动识别 X-HTTP-Method-Override，得自己解析：
在控制器里加一层判断：
$method = request()->server('REQUEST_METHOD');
if (request()->has('X-HTTP-Method-Override')) {
$method = strtoupper(request()->header('X-HTTP-Method-Override'));
}
if ($method === 'PUT') {
return $this->update($id);
}
或者更简单：统一用 POST，靠参数区分动作（如 _method=put），再在中间件里重写请求方法——但这就偏离纯 REST 了。
- Apifox、Postman 测试时记得手动设置 Method 和 Header
- uni-app 等前端框架发请求时，务必显式指定
method: 'PUT'并确保后端 Nginx/Apache 允许该方法 - 别在路由里写
Route::put(...)单独映射，和Route::resource()混用会导致冲突
RESTful 接口在 ThinkPHP 6 里不是开关式功能，而是命名、路由、方法、响应四者咬合的结果。少一个环节，请求就卡在 404 或返回 HTML；多一个随意改动（比如改方法名、漏 json()），前端就收不到可用数据。实际开发中，建议先复制一个已验证的 API 控制器模板，再替换命名空间和类名，比从头手敲更稳。
