Route::group()是最稳妥的API版本控制起点，需为v1、v2等静态前缀独立定义分组，明确指向对应命名空间（如api/v1.User），并清空路由缓存；禁用变量路由、header或参数驱动版本，避免逻辑耦合与缓存失效。
Route::group() 是最稳妥的接口版本控制起点，直接写死 v1、v2 前缀，不依赖参数解析或中间件跳转——它让路由匹配可预测、IDE 能跳转、Swagger 可自动归类，且上线后不会因缓存或大小写问题突然 404。
用 Route::group() 配静态版本前缀
ThinkPHP 不会自动把 /v1/user 和 /v2/user 当成同一逻辑的不同版本，它只认路径字面量。所以别试图用变量路由 :version 拼接，那会导致 v10 匹配到 v1 规则、路由缓存失效、IDE 无法识别控制器跳转。
- 每个版本必须独立定义分组：
Route::group('v1', function () { ... })和Route::group('v2', function () { ... }) - 分组内路由指向明确的命名空间：
api/v1.User/read对应app\api\v1\User类，不能少v1，也不能写成V1或v1user - Linux 下目录名和命名空间大小写敏感，
app/api/v1/必须全小写，User.php文件里必须是namespace app\api\v1; - 改完路由后必须执行
php think route:clear，否则旧缓存还在，新路由不生效
控制器里别写 if ($version === 'v2')
拿到版本号后硬塞 if-else 到控制器方法里，等于把业务差异耦合进路由分发层。v2 加个字段、v1 少个校验，下次 v3 再加个开关，控制器就变成嵌套判断黑洞。
- 按版本拆服务类：比如
app\service\v1\UserService和app\service\v2\UserService，都实现UserInterface - 在控制器中动态加载：
$service = new $serviceClass();，但务必先class_exists($serviceClass)，非法版本直接返回 400 - 如果只是输出字段不同，优先用 Resource 层（如
v1\UserResource/v2\UserResource）组装数据，而不是在控制器里Arr::only($data, [...])硬过滤 - 别在基类
initialize()里统一加载所有版本的服务实例——v1 请求不该初始化 v2 的类
X-API-Version 头怎么接入才不踩坑
TP 原生不解析自定义 header 做路由分发，所谓 “支持 header 版本” 实际是靠中间件提取 + 手动传参，不是路由自动匹配。这就意味着 URL 还是 /api/user，但逻辑要靠你手动分叉。
- 中间件里取头：
$request->header('x-api-version', 'v1')，别用Accept解析，因为application/vnd.myapp.v2+json的格式不统一，容易出错 - 把版本写入 request 属性：
$request->version = $version，后续控制器用$this->request->version拿，别重复解析 - 不能靠中间件重定向或转发请求到
/v2/user—— 这会丢失原始 header、污染日志、让网关统计失真 - 如果同时支持 URL 路径和 header 两种方式，优先以 URL 为准（显式 > 隐式），避免客户端传了
v2头却访问/v1/user导致行为不一致
查询参数 ?version=v2 适合什么场景
它实现成本最低，但破坏 RESTful 语义、干扰缓存、不利于监控。只建议用于灰度发布、临时兼容或内部测试，别作为正式版本策略。
立即学习“PHP免费学习笔记（深入）”；
- 别在路由里写
Route::get('user', ...)然后靠控制器判断input('version')—— 同一 URL 下不同参数被 CDN 当作同一资源缓存，v1 用户可能拿到 v2 响应 - 如果真要用，必须在响应头中强制禁用缓存：
Cache-Control: no-store，否则前端永远收不到更新 - OpenAPI 文档无法按参数自动分组，得手动为每个接口标注
v1/v2分支，维护成本高 - 日志里查错误率时，所有
/user请求混在一起，没法快速定位是 v1 还是 v2 的问题
