ThinkPHP6路由前缀不自动映射多级命名空间，需手动配置namespace参数并更新composer autoload；多版本控制器须独立命名空间隔离，中间件按分组绑定，上线前需日志验证旧版本调用。
ThinkPHP 路由前缀怎么映射到多级控制器目录
TP6 默认不支持 apppi 1UserController 这种带版本号的多级命名空间直接通过路由前缀自动绑定。你写 Route::prefix('v1')->group(...)，它不会自动把 v1 映射进控制器命名空间——这是最常被误解的一点。
必须手动配置命名空间映射，否则请求 /api/v1/user 会报 ClassNotFoundException，因为框架仍按默认 appcontroller 去找类。
- 在
route/app.php中定义分组时，显式指定namespace参数：Route::prefix('v1', ['namespace' => 'app\api\v1'])->group(function () { Route::get('user', 'UserController@index'); }); - 注意反斜杠要双写（PHP 字符串转义），且末尾不加
Controller—— TP 自动补全 - 若用闭包定义路由，
namespace必须写在分组参数数组里，不能写在闭包内
多版本共存时控制器方法名冲突怎么处理
不同版本的 UserContoller 可能有同名方法（比如都叫 index），但参数、返回结构、校验逻辑已变化。TP 不会帮你做方法级兼容，靠命名空间隔离是唯一可靠方式。
别试图在同一个控制器里用 if (version == 'v1') 分支——这会让测试、维护和 IDE 跳转全部失效。
立即学习“PHP免费学习笔记（深入）”；
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 每个版本对应独立命名空间：
apppi 1UserController、apppi 2UserController - 路由分组严格绑定各自 namespace，避免跨版本混用
- 如果 v2 新增了字段，v1 保持原样，就不要在 v1 控制器里调 v2 的 service —— service 层也建议按版本拆分或加 version 参数隔离
API 版本升级后老客户端 404 怎么快速定位
不是路由没配对，大概率是 PSR-4 自动加载没生效。TP6 依赖 composer.json 的 autoload 配置识别新命名空间。
改完控制器路径和路由后，漏掉这一步，就会一直 404，且错误日志里只显示“class not found”，不提示加载路径问题。
- 检查
composer.json的autoload.psr-4是否包含："app\api\v1\": "app/api/v1/", "app\api\v2\": "app/api/v2/"
- 改完立即运行
composer dump-autoload，别依赖开发环境自动重载 - 用
php think route:list确认路由是否真被注册（注意看 Action 列是否显示完整类名）
中间件如何按 API 版本差异化启用
比如 v1 用 JWT，v2 改用 OAuth2，但路由前缀都是 /api/v*。不能全局注册中间件，否则 v1 会被 v2 的鉴权规则拦截。
TP 的中间件绑定粒度足够细，关键在于绑定位置：必须在 prefix 分组内部，而不是全局或控制器构造方法里。
- 在 v1 分组里单独加中间件：
Route::prefix('v1', ['namespace' => 'app\api\v1']) ->middleware(['jwt.auth']) ->group(function () { ... }); - v2 分组用另一套：
Route::prefix('v2', ['namespace' => 'app\api\v2']) ->middleware(['oauth.check']) ->group(function () { ... }); - 中间件类本身不要硬编码版本逻辑，保持单一职责
版本过渡最难的不是写新代码，而是旧路由是否还在被文档、SDK、第三方系统悄悄调用。上线前务必用 Nginx 日志或数据库慢查日志反向抓出真实 v1 请求路径，而不是只测自己写的 demo URL。
