ThinkPHP6.x路由基础：优雅定义RESTful API接口

如果你在 ThinkPHP 6.x 中尝试构建标准的 RESTful API，却发现路由死活映射不到控制器方法、请求体取不到参数、或者返回格式总是不对劲——那八成是资源路由的定义与框架的约定没对齐。别担心，以下五步优化流程能帮你一次性彻底解决这些常见问题。

一、使用 Route::resource() 并显式限定动作

一条声明即可生成语义清晰的 REST 路由，但务必排除掉 create 和 edit 这两个非 API 场景的动作，否则会暴露无意义的 HTML 表单路径，还可能引发路由冲突与安全扫描风险。

打开 app/route/app.php，在路由注册区域添加以下代码，并用 only() 明确指定仅启用 API 必需的动作：

（此处演示代码省略，实际按项目结构写）

还需留意三点：控制器命名空间必须与路由声明一致——比如 Route::resource('users', 'api.User') 对应 app/controller/api/User.php 中的 User 类；控制器必须继承 think\Controller（而不是 think\BaseController），否则资源方法调用会因 __call() 拦截失效而报错 “method not exists”。

二、手动拆解注册精简 REST 路由

此方法完全绕过 Route::resource() 默认的七动作绑定，采用显式方式逐条定义 GET/POST/PUT/DELETE 路径。路径语义更纯粹，中间件可自由附加，并且不依赖任何隐式约定。

具体做法：先删除或注释掉所有 Route::resource() 调用，然后按标准 API 动作顺序注册。注意 PUT 和 PATCH 需要共用同一处理方法，必须分别注册两条路由。每条路由都能独立绑定中间件，例如统一添加 api 中间件用于鉴权与 JSON 响应封装。

三、配置 API 前缀并确保控制器解析正确

当需要版本化路径（如 /api/v1/users）时，如果直接将前缀写进资源路由字符串里，会导致控制器命名空间解析失败（比如误把 v1 当作应用名）。正确做法是通过分组隔离前缀逻辑。

在 app/route/app.php 中使用 Route::prefix() 包裹资源路由定义，并确保资源路由注册在 prefix 分组内部，而不是外部拼接路径字符串。同时验证控制器类是否位于 app/controller/api/User.php，类名与命名空间必须一致。若启用多应用模式，检查 app/multi.php 中是否已声明 api 为合法应用名，否则 api.User 无法正确解析。

四、修正控制器方法签名与参数绑定

资源路由能否正确分发请求，高度依赖控制器方法名、参数名及类型提示是否与框架内建规则严格匹配——任何一个偏差都可能导致 404 或参数为空。

• 方法名必须是 ThinkPHP 约定的七个之一：index、read、save、update、delete（严禁使用 show、store、destroy 这种 Laravel 风格命名）。
• read($id) 和 delete($id) 的参数名必须为 $id；想加入类型安全可写成 read(int $id)，否则路由无法完成参数绑定。
• update(Request $request, $id) 必须将 Request 对象作为第一个参数，否则 PUT/PATCH 请求体内容无法获取。只写 update($id) 的话，$this->request->param() 永远是空的。
• save() 是唯一不带 ID 参数的方法，且框架不会自动调用 input() 或 param()，必须手动取参：$this->request->post()（表单）或 $this->request->param()（JSON）。

五、强制 JSON 响应并规避常见格式陷阱

ThinkPHP 默认响应类型是 HTML，即便请求来自 AJAX 或携带了 application/json 头，如果不显式干预，返回值可能被模板引擎渲染或输出成未格式化的数组，前端解析会直接出错。

• 每个控制器方法末尾必须显式调用 json() 并传入结构化数据。
• 禁用视图渲染：在控制器构造函数中设置 $this->view = null;，或者直接继承 think\Controller（它的构造函数已内置此操作）。
• 当 app_debug = false 时，如果未配置 default_ajax_return，JSON 请求会被静默丢弃——务必在 config/app.php 中加入相关设置。
• ThinkPHP 6+ 默认会对字符串参数执行 trim()。若业务需要保留首尾空格字段，应在验证器或中间件中关闭此行为，否则 input('content') 会丢失原始空白字符。

核心要点就是这五步，逐一检查对位，你的 RESTful API 就能流畅运行。记住那句口诀：Route::resource() 声明位置、控制器命名空间、方法名（index/read/save/update/delete）、参数名（$id）、继承 think\Controller、手动取参、显式 json() 响应——缺一不可，否则就会出现 404 或参数为空的问题。