ThinkPHP API接口版本化目录结构_v1与v2版本共存方案

ThinkPHP 路由如何匹配 _v1 和 _v2 目录下的控制器

ThinkPHP 默认不识别下划线开头的目录名作为路由层级，_v1 这类目录会被直接忽略或触发 404。关键在绕过框架对“非法目录名”的过滤逻辑。

实操建议：

不要把版本目录放在 app/controller/ 下——TP6+ 会扫描该路径并自动注册控制器，但下划线前缀导致类名解析失败（如 _v1.UserController 不合法）改用「模块化」方式：在 app/ 下新建 v1 和 v2 模块（不带下划线），再通过路由绑定强制指向对应模块在 route/app.php 中显式注册版本路由：Route::group(‘api/v1’, function () { Route::rule(‘:any’, ‘v1/:controller/:action’);})->ext(‘json’);Route::group(‘api/v2’, function () { Route::rule(‘:any’, ‘v2/:controller/:action’);})->ext(‘json’);

为什么不能直接用 _v1 命名目录

TP6 的 think\Container 在反射加载控制器类时，会将路径转为类名（如 app/controller/_v1/User.php → app\controller\_v1\User），而 PHP 不允许命名空间以数字或下划线开头，直接报 ParseError: syntax error, unexpected ‘_v1’。

常见错误现象：

立即学习“PHP免费学习笔记（深入）”；

访问 /api/v1/user 返回 404，但日志里没报错（路由未注册）手动在 app/controller/_v1/ 下建控制器，启动时直接抛出 Compile Error用 Route::import() 加载配置，发现 _v1 路径被跳过

共存时中间件和验证器怎么隔离 v1/v2

版本差异常体现在参数校验、返回格式、鉴权逻辑上，混用同一套中间件极易引发兼容问题。

实操建议：

中间件按版本拆分：建 app/middleware/v1/ 和 app/middleware/v2/，在各自模块的 middleware.php 中定义验证器类名必须唯一，避免 v1.UserValidate 和 v2.UserValidate 冲突——TP 自动加载时只认类名，不看路径在控制器基类里做运行时判断：class BaseController extends Controller{ protected $version = ‘v1’; // 子类覆写 public function initialize() { if (‘v2’ === $this->version) { $this->assign(‘timestamp_key’, ‘updated_at’); } }}

API 版本升级后旧接口怎么平滑下线

不是删代码，而是控制暴露面。直接删 v1 模块会导致线上调用瞬间中断，且无法统计哪些客户端还在用 v1。

实操建议：

加全局响应头提示：header(‘X-API-Version-Deprecated: true’);header(‘X-API-Version-Deprecated-Until: 2025-06-30’);让调用方感知在 v1 模块的基控制器里埋点记录请求来源（User-Agent、IP、请求路径），导出后推动客户端升级用 Nginx 层做灰度：先对内网 IP 放行 v2，外网仍走 v1，确认无误后再切全量禁止在 v1 中新增字段或修改结构——哪怕只是加个默认值，都可能破坏老客户端解析

最麻烦的其实是文档同步和 header 处理。比如 v2 要求必须传 Accept: application/vnd.myapp.v2+json，但很多前端 SDK 是硬编码的，这时候光改后端没用，得配合运营侧推动升级。