最稳妥的API版本管理是将版本号作为固定字符串路径前缀写死在Route::group()中，如Route::group('api/v1', ...)；目录名、文件名、命名空间须全小写且严格对齐，禁止使用变量或配置动态生成前缀，避免路由缓存失效和自动加载失败。
最稳妥的 API 版本管理，是把版本号作为固定路径前缀写死在 Route::group() 里，而不是靠中间件、请求头或动态正则去“猜”版本——后者容易漏校验、难调试、上线后莫名 404。
Route::group() 必须用字符串字面量写版本前缀
TP 的路由缓存机制要求分组前缀必须是确定的字符串，不能是变量、常量或配置读取值。否则开发环境能跑，上线清缓存后全部 404。
-
Route::group('v1', function () { ... })✅ 安全，缓存可生成 -
Route::group(config('api.version'), function () { ... })❌ 开发时看似正常，上线后路由不命中 -
Route::group('api/' . $version, function () { ... })❌ 同样触发缓存失效，且 PHP 语法报错
如果你的 API 统一走 /api 前缀，就直接写 Route::group('api/v1', ...)，别拆成两层 group。
控制器命名空间和目录结构必须严格对齐
路由指向 api/v1.User/read，框架就会按 PSR-4 去找 app\api\v1\User 类。任何偏差都会导致 Class app\api\v1\User does not exist 错误——不是类真没了，而是自动加载器根本没进对目录。
立即学习“PHP免费学习笔记（深入）”；
- 目录名必须小写：
app/api/v1/，不能是V1或ApiV1（Linux 下直接 500） - 文件名必须和类名一致：
User.php对应class User，不是UserController.php - 命名空间首行必须是
namespace app\api\v1;，末尾不能多空格或换行 - Windows 开发完要手动检查 Linux 部署机上的大小写，别依赖本地“不区分”的假象
别在中间件里做版本路由分发
有人想统一拦截 /api/*，再根据 header 或 query 参数跳转到不同控制器。这绕过了路由匹配和缓存，也破坏了中间件执行顺序——比如 JWT 鉴权中间件可能还没跑，请求就被重定向了。
- 中间件无法改变当前请求已匹配的路由规则，
$request->action()已锁定 - 用
redirect()或invoke()手动调控制器，会丢失原始Request对象上下文，日志、审计、限流全乱 - 若真需 header 支持（如
X-API-Version: v2），只应在中间件里提取并存入$request->version = 'v2'，后续控制器自己判断，不改路由流向
版本差异尽量下沉到服务层，别堆在控制器里
一个 v2.User 控制器里塞满 if ($version === 'v2') { ... }，半年后没人敢动。版本的本质是契约变化，不是 if 分支。
- 用命名空间隔离服务：例如
app\service\v1\UserService和app\service\v2\UserService实现同一接口 - 控制器里只做简单加载：
$service = new $serviceClass(); return $service->list(); - 字段增减优先走 Resource 层（如 TP6 的
think\facade\Response或自定义组装器），而不是在控制器里Arr::except($data, ['old_field']) - 务必加
class_exists($serviceClass)校验，非法版本直接 400，别让错误穿透到模型层
最易被忽略的是：路由缓存与命名空间大小写的耦合性。哪怕只是把 v1 目录名手误打成 V1，Linux 上所有该版本接口都会静默失败，连日志都不报错——因为自动加载器压根没尝试加载。
