新增控制器方法必须显式配置路由、使用框架json()输出、显式声明模型完整命名空间，并统一API结构。否则将引发权限、格式、404、Class not found四类问题。
直接在控制器里加新方法就行，但必须走框架的输出通道、遵守路由映射规则、避开模型自动加载陷阱——否则接口能跑通，上线后会出权限、格式、404、Class not found 四类高频问题。
新增控制器方法前先配好路由
ThinkPHP5 不是“写了方法就能访问”，必须显式声明路由，否则 404。别依赖默认的「模块/控制器/方法」隐式规则，尤其在 API 场景下容易错位。
- 推荐写在
route/api.php（单独 API 路由文件），避免和前台路由混在一起 - 用分组方式统一前缀：Route::group(['prefix' => 'api'], function () { Route::get('video/list', 'VideoApi/getList'); });
- 路径名用小写+下划线（如
video/list），控制器方法名用驼峰（getList），框架会自动转换 - 如果用了版本控制（如
v1/video/list），路由要带参数：Route::rule('api/:version/video/list', 'api/VideoApi/getList');
控制器里 return json() 是最简方案，但有坑
直接 echo json_encode() 或 return json_encode() 会跳过框架 Response 层，导致 Content-Type 错、状态码固定为 200、异常不拦截、日志无上下文。
- 全局配置更稳妥：在
config/app.php中设'default_return_type' => 'json'，之后所有return ['code'=>0, 'data'=>[]]自动转 JSON - 局部强制用
return json(['code'=>0, 'msg'=>'ok'])，它内部已设好Content-Type: application/json; charset=utf-8 - 别在控制器里手动
header()，TP5 的json()函数已封装完整 - 若需统一结构（如固定含
status、msg、data），建议在app/common.php定义api_response($data, $code = 1, $msg = 'ok')，再return api_response($list)
调用模型时命名空间必须显式写全
常见错误：model('Vod') 找不到类，不是模型文件放错，而是 TP5 默认只在当前模块目录（如 app/api/model/）下找——而你的模型实际在 app/common/model/Vod.php。
- 正确写法是
model('common/Vod')，斜杠表示子命名空间路径 - 确保模型文件名与类名严格一致：
Vod.php→class Vod extends \think\Model - 命名空间声明必须匹配物理路径：
app\common\model\Vod对应app/common/model/Vod.php - 控制器里别用
use app\common\model\Vod;后再new Vod()，会绕过框架模型实例管理（如自动读取数据库配置、事件钩子）
函数级扩展别塞进模板，要进控制器或服务类
苹果CMS V10 等基于 TP5 的系统里，有人把 API 逻辑写在模板里（{php}...{/php}），这看似快，但不可调试、无法复用、权限校验失效、JSON 输出易被模板 HTML 截断。
- 所有业务逻辑必须收口到控制器方法中，哪怕只是简单转发
- 重复逻辑（如 token 解析、参数过滤）抽成
app/service/ApiHelper.php，用Loader::import()或app('service.ApiHelper')调用 - 需要快速验证时，可在控制器里临时加个
public function debug(){ ... return json($result); }，上线前删掉 - 别在控制器里拼 SQL 字符串，哪怕只是
"SELECT * FROM vod WHERE vod_id = {$id}"—— 必须用 Query 类或模型的where()防注入
最常被忽略的是模型路径和路由分组的耦合关系：改了路由前缀却没同步更新控制器命名空间，或者把 app\api\controller\v1\User 的命名空间写成 app\api\controller\V1\User（大小写错），IDE 不报错但运行时报 ClassNotFoundException。这类问题只能靠路径+命名空间+路由三者对齐来规避，没有捷径。
