ThinkPHP5 API开发关键在于规范路由配置、统一JSON输出和模型层隔离，避免手动拼接JSON、硬编码版本号及命名空间错误，确保Swagger文档可生成且符合OpenAPI标准。
ThinkPHP5 的 API 接口开发，核心不是“能不能做”，而是“要不要绕开框架默认行为”。直接用 return json() 能跑通，但上线后会踩权限、版本、错误格式、调试盲区这四类坑。关键在路由配置、输出控制和模型层隔离这三处下手。
如何让控制器返回标准 JSON 而不手动拼字符串
TP5 不推荐在控制器里用 echo json_encode()，因为会跳过 Response 类的统一处理（如 Content-Type、状态码、异常拦截）。必须走框架的输出通道：
- 全局配置
'default_return_type' => 'json'在config/app.php中，之后所有控制器return ['code'=>0, 'data'=>[]]自动转为 JSON 响应 - 局部覆盖用
return json(['code'=>0])，适用于某个接口需强制 JSON，而其他接口仍走 HTML 或 XML - 注意：如果同时设置了
default_ajax_return但没发 AJAX 请求，该配置不生效；json()函数内部会自动设置Content-Type: application/json; charset=utf-8，无需手写 header
为什么路由里带 v1、v2 的路径不能直接写死在控制器命名空间里
硬编码版本号到类名或路径（比如把控制器放在 app\api\controller\v1\User）看似清晰，实则破坏了 PSR-4 自动加载规则——一旦路由规则稍作调整，class not found 错误频发，且 IDE 无法正确跳转。
- 正确做法是在
route/route.php用动态分组：return ['api/:version/:controller'=>'api/:version.:controller/index']; - 对应控制器按版本分目录，但命名空间必须与物理路径严格一致：
app\api\controller\v1\User对应namespace app\api\controller\v1; - 关键点：路由解析时，
:version参数会被注入到模块名中，最终调用的是app\api\controller\v1\User->index()，而非app\api\controller\User - 漏掉命名空间声明或大小写不一致（如
v1写成V1），就会触发ClassNotFoundException
模型层报 Class not found 的真实原因和解法
常见错误是模型文件放错位置或命名空间写错，但更隐蔽的问题出在模型调用方式上。比如在 app\api\controller\User.php 中写 model('AdminUser')，却把模型放在 app\base\model\AdminUser.php，这时 TP5 默认只在 app\api\model 下找。
立即学习“PHP免费学习笔记（深入）”；
- 显式指定完整命名空间：用
model('base/AdminUser')，而不是依赖自动推导 - 确保模型类继承
think\Model，且文件名与类名完全一致（AdminUser.php→class AdminUser） - 若模型需复用，不要复制文件，而应在
config/model.php中配置'namespace' => 'app\base\model'，再通过use app\base\model\AdminUser;引入 - TP5 的
model()辅助函数本质是容器对象查找，路径错误时不会报“文件不存在”，而是静默返回空对象，导致后续find()报错或查不到数据
Swagger 文档生成失败时最先检查的三个地方
用 Swagger-php 注释生成文档，最常卡在注释未被扫描到、命名空间错位、或 @OA\Info 缺失。它不依赖运行时，纯静态分析，所以代码能跑通不代表注释有效。
-
@OA\Info必须存在且位于控制器文件顶部，否则openapi.json生成为空或报错 “Missing required field info” - 注释块必须紧贴类或方法定义上方，中间不能有空行；
/** */不能写成/* */ - 确认命令行执行路径在项目根目录，且运行的是
php vendor/bin/openapi app/ --output public/swagger.json，而非在app/子目录下执行 - 常见现象：浏览器访问
/swagger页面空白，但控制台无报错——大概率是生成的swagger.json格式非法，用 JSONLint 验证即可定位缺失字段
真正难的不是写出第一个接口，而是让每个新成员接手时，不用翻三遍文档才能搞懂路由怎么映射、错误怎么统一、模型从哪来。这些细节藏在配置、命名空间和注释格式里，改一处，漏三处。
