ThinkPHP 中应通过路由正则提取并校验 API 版本号，如 Route::rule('api/^v[1-9]d*$/user', 'api.v1.User/index')，确保版本格式合法且路由可缓存；权限控制须由中间件统一拦截，按启用状态与用户角色返回 410 或 403；业务逻辑差异宜用策略模式隔离，避免模型耦合版本；请求头版本不可用于路由匹配，因破坏缓存与网关兼容性。
ThinkPHP 路由中如何提取并校验 API 版本号
版本号必须从 URL 路径中明确提取，不能依赖请求头或参数——这是保障路由可缓存、可调试、可文档化的前提。ThinkPHP 6 的 Route::rule() 支持正则分组捕获，直接在路由定义里把 v1、v2 当作变量抓出来最稳妥。
常见错误是写成 api/:version/user 却不约束 :version 格式，导致 api/abc/user 也能匹配，后续权限校验失效。正确做法是用正则限定：
Route::rule('api/^v[1-9]d*$/user', 'api.v1.User/index');
这样 v0、v100、v1 都能匹配，但 vx、version1 会被路由层直接 404，不进控制器。
-
^v[1-9]d*$是关键正则：必须以v开头，后跟非零开头的数字（避免v01这类歧义） - 不要用
[:version]这种模糊占位符，它不校验格式，等于放行所有字符串 - 如果项目用多级子域名（如
v1.api.example.com），那就该用Route::domain()分离，而非塞进路径
如何在中间件里统一拦截未授权的版本访问
权限控制不能散落在每个控制器里，得靠中间件做前置拦截。ThinkPHP 的 thinkMiddleware 支持闭包或类方式注册，推荐用类中间件，方便复用和测试。
立即学习“PHP免费学习笔记（深入）”；
核心逻辑是：拿到路由解析出的 $version，查配置表或常量数组，判断该版本是否“已启用”且“当前用户有权限”。注意别漏掉两个边界：
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 版本存在但已废弃（比如
v1已停用，只保留v2）→ 应返回410 Gone，不是404 - 版本存在且启用，但当前 token 对应角色没开白名单（如管理员能调
v1和v2，普通用户只允许v2）→ 返回403 Forbidden - 中间件里别直接 throw 异常，用
return json(['code'=>403, 'msg'=>'version forbidden'], 403)显式响应，避免被全局异常处理器吞掉状态码
不同版本接口共用模型但行为要隔离怎么办
模型本身不该感知版本，但业务逻辑可能随版本变化（比如 v1 返回字段 user_name，v2 改成 nickname）。硬编码 if-else 不可维护，推荐用策略模式轻量实现。
在 app/common/strategy/ 下建 UserOutputStrategy.php，按版本名自动加载对应策略类：
class UserOutputStrategy
{
public static function make(string $version): OutputInterface
{
$class = 'app\strategy\' . ucfirst($version) . '\UserOutput';
return class_exists($class) ? new $class() : new V1UserOutput();
}
}
然后控制器里：$data = UserOutputStrategy::make($version)->format($user);。这样新增 v3 只需加个新策略类，不碰老代码。
- 别在模型的
toArray()里写版本判断——模型职责是数据结构，不是协议适配 - 如果只是字段增减，用
hidden/visible属性配合版本中间件注入更轻量 - 数据库字段命名保持稳定（如始终用
nickname），避免因版本切换改表结构
为什么不能把版本号塞进请求头做路由判断
因为 ThinkPHP 的路由匹配发生在请求头解析之前，Accept: application/vnd.myapp.v2+json 这类自定义头根本进不了路由调度器。你写的 Route::rule('api/user', ...)->header('Accept', 'v2') 实际上只是个过滤条件，不是路由规则的一部分。
更实际的问题是：这种写法会让 Nginx 缓存、CDN、API 网关全部失效——它们无法基于请求头做精准缓存键，同一 URL + 不同头会反复穿透到后端。
- 路径版本（
/api/v2/user）天然支持 CDN 缓存、日志分析、OpenAPI 文档生成 - 请求头版本只适合灰度发布场景（比如内部系统用头切流），不适合对外公开 API
- 如果真要兼容头版本，只能在中间件里读
$request->header('accept')做二次分发，但此时路由已固定，容易和实际 URL 版本冲突，调试成本高
版本号写在路径里不是约定俗成，是 HTTP 缓存语义和网关基础设施决定的刚性要求。绕开它，后面每个环节都会补丁叠补丁。
