Hyperf API 版本管理须适配协程常驻内存特性，禁用全局/静态变量；推荐路由前缀+独立命名空间或Header+Context::set/get方式，严禁混用逻辑混乱，所有判断应统一收口至VersionMiddleware中间件。
Hyperf 中 API 版本管理必须与协程常驻内存特性对齐——不能靠全局变量或静态属性存版本标识，否则会跨请求污染；路由前缀和 Header 两种方式都能用，但选错实现路径会导致中间件逻辑混乱、控制器复用困难、文档生成失效。
用路由前缀实现版本隔离时，必须绑定独立命名空间
Hyperf 的 Router::addGroup 或注解 #[AutoController(prefix: 'v1')] 只是路径控制，若不配合命名空间隔离，v1/v2 控制器方法实际共享同一个类实例（单例），协程间会互相覆盖状态。
- 正确做法：每个版本使用独立命名空间，如
App\Controller\V1\UserController和App\Controller\V2\UserController，并在routes.php中显式分组 - 错误写法：
#[AutoController(prefix: 'v1')]和#[AutoController(prefix: 'v2')]指向同一个类，仅靠方法内 if 判断版本 - 注意：Swagger 文档生成工具（如
overtrue/laravel-swagger）默认不识别 prefix 变化，需手动按版本分批扫描路由，否则 v1/v2 接口会混在一份文档里
Header 版本控制需在中间件中完成协程上下文注入
不能在中间件里把版本号塞进 $request 属性或静态变量，因为 $request 是协程安全的，但它的属性不是自动隔离的；更不能用 static $version，那会彻底崩掉并发。
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 推荐方式：用
Context::set('api_version', $version)将版本写入当前协程上下文 - 后续控制器或服务中通过
Context::get('api_version')获取，确保严格隔离 - 常见坑：在中间件里调用
$next($request)前没 set，或在子协程里忘记从父协程 inherit context，导致子协程读不到版本
混合使用时，路由前缀优先级必须高于 Header
当同时支持 /api/v2/users 和 Accept: application/vnd.example.v2+json 时，如果 v2 路由未定义却收到 v2 Header，应明确拒绝而非 fallback 到 v1 —— 否则语义混乱，客户端无法感知接口是否真实存在。
- 建议策略：先匹配路由前缀，命中则直接执行对应版本逻辑；未命中再解析 Header，且只允许 Header 版本在已启用范围内（如配置项
allowed_versions = ['v1', 'v2']） - 废弃旧版时，对 v1 路由返回
410 Gone，Header 方式则统一返回406 Not Acceptable，避免状态码误用 - 所有版本判断逻辑必须收口到一个中间件（如
VersionMiddleware），禁止在多个控制器里重复解析
最易被忽略的是协程上下文生命周期与版本标识的绑定时机——set 必须在中间件早期完成，get 必须在真正需要分支逻辑前调用；一旦延迟到数据库查询之后再判断版本，就可能因复用连接池或缓存 key 导致数据错乱。
