ThinkPHP API接口版本化管理实现_升级后的路由路由策略-ThinkPHP-PHP中文网

thinkphp版本路由应使用route::group()统一声明前缀，避免中间件分发和路径硬编码；版本差异应在控制器层协议适配，中间件需按分组绑定；注解路由须配置多controller_path并确保命名空间规范。

thinkphp api接口版本化管理实现_升级后的路由路由策略

直接在 route/app.php 里用分组加前缀是最稳的，别碰中间件做版本路由分发——那会绕过路由缓存，也容易和跨域、鉴权等中间件顺序冲突。

常见错误是把版本号写死在每个接口路由里，比如 api/v1/user 和 api/v2/user 分开注册，结果维护时漏改一个就出问题。

用 Route::group() 统一声明前缀：

Route::group('api/v1', function () { Route::get('user', 'v1.User/get'); });

多个版本共用同一控制器方法？可以传参数：v1.User/get?version=v1，但不推荐——语义不清，也不利于文档生成和网关识别
注意：TP6.1+ 支持 prefix 参数自动注入到闭包或类方法，但需开启 route_annotation 且控制器命名空间要匹配，否则 __invoke 不触发

不是靠路由转发，而是靠控制器层做「协议适配」。版本差异本质是输入/输出契约变化，路由只负责分发，不该承担转换逻辑。

典型坑是用中间件统一拦截 v2 请求然后改 input() 数组——这会污染原始请求，导致日志、审计、重放校验全乱套。

在 v2.User 控制器里调用 v1.User 的业务方法，再包装响应：$data = (new v1\User())->get(); return json(['code'=>0, 'data'=>$data, 'v2_extra'=>'ok']);
如果字段名冲突（比如 v1 返回 user_name，v2 要 name），用数组映射比硬编码 if-else 更易维护：Arr::only($data, ['id', 'user_name']) → ['id','name']
TP 自带的 think\facade\Request 在不同版本控制器中行为一致，但注意 input('page/d', 1) 这类默认值定义必须显式保留，v2 不该隐式覆盖 v1 的默认逻辑

能，但必须按路由分组绑定，不能全局注册。TP 的中间件绑定粒度是「路由规则」，不是「URL 前缀字符串」。

有人试过在 middleware.php 里写 ['api/v1'=>[JwtAuth::class]]，结果发现没生效——因为 TP 不解析路径字符串做中间件匹配，只认路由定义时的规则名或分组名。

正确做法：在分组内链式绑定：

Route::group('api/v1', function () { /* ... */ })->middleware(JwtAuth::class);

如果 v1 不需要鉴权而 v2 需要，就分开写：Route::group('api/v2')->middleware(JwtAuth::class)，别试图用条件判断动态挂载
注意中间件执行顺序：TP 是先跑路由绑定的中间件，再跑全局中间件。如果你在全局写了 CORS，又在 v2 分组里写了 JWT，那预检请求（OPTIONS）可能被 CORS 拦截前就卡在 JWT 的 token 解析上

大概率是路由缓存没刷全，或者注解路由扫描路径没包含 v2 对应的控制器目录。

TP6 默认只扫描 app/controller，如果你把 v2 控制器放在 app/v2/controller，又没在 config/route.php 里配 controller_path，那注解路由根本不会读它。

运行 php think route:clear 后，立刻跟一句 php think route:list 看 v2 路由是否在列表里
检查 config/route.php 中 annotation 配置项：'controller_path' => [app_path('controller'), app_path('v2/controller')]
别信 IDE 的文件索引——TP 注解扫描依赖 ReflectionClass，如果 v2 控制器类名没按 PSR-4 命名（比如少了 v2\ 命名空间），route:list 就看不到它