最简且生产可用的API版本控制方式是将版本号写入路径前缀（如/v1/users），通过Party分组实现路由隔离与中间件按需挂载，避免query或header方式导致日志、文档混乱及调试语义丢失。
直接用路由前缀是最稳的版本控制方式
在 Iris 里，app.Get、app.Post 等方法不支持自动识别 Accept 头或 query 参数做版本分流，强行用这些方式会导致日志难追踪、OpenAPI 文档生成混乱、调试时路径语义丢失。最简且生产可用的做法，就是把版本号写进路径——比如 /v1/users、/api/v2/orders。
这不是“偷懒”，而是 Iris 的设计哲学：路由分组（Party）天然适配这种结构，能隔离中间件、独立挂载验证逻辑，后期删旧版也只需删整个分组。
- 别写
/users?version=v2：Iris 不会自动按 query 分支，你得自己解析、判断、跳转，白费力气还易出错 - 避免依赖
Accept: application/vnd.myapi.v2+json：HTTP 内容协商在 Iris 中需手动解析ctx.GetHeader("Accept")，无法参与路由匹配，中间件和日志都得额外适配 - 路径前缀必须统一层级：比如全用
/v1/...，不要混用/v1/users和/api/v2/orders，否则文档工具（如 Swagger）可能无法正确归类
用 Party 分组管理不同版本的路由和中间件
Party 是 Iris 提供的路由分组机制，它返回一个子应用实例，自带独立的 Use、Get、Post 等方法，是实现版本隔离的核心工具。
例如 v1 版本需要 JWT 验证，而 v2 改用 OAuth2，就可以分别挂载不同中间件，互不影响：
apiV1 := app.Party("/v1")
apiV1.Use(JWTMiddlewareV1)
apiV1.Get("/users", getUsersV1)
apiV2 := app.Party("/v2")
apiV2.Use(OAuth2MiddlewareV2)
apiV2.Get("/users", getUsersV2)
-
Party返回的子路由对象不共享父级中间件，除非显式调用UseGlobal—— 这意味着你可以安全地为每个版本定制鉴权、日志、限流逻辑 - 分组路径必须以
/开头，否则会被当作相对路径拼接，导致app.Party("v1")实际注册成/v1而不是预期的/v1（注意斜杠） - 如果想让所有版本共用某个中间件（如统一请求 ID 注入），用
app.UseGlobal(commonMiddleware)，它对所有子分组生效
版本路由冲突常见于参数类型约束不一致
当多个版本共用相似路径但参数规则不同（比如 v1 允许字符串 ID，v2 强制整数），Iris 的路由匹配器会按字面量 > 类型约束 > 通配符优先级排序，容易误匹配。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
例如：
v1.Get("/users/{id}", handlerV1) // 匹配 /users/abc
v2.Get("/users/{id:int}", handlerV2) // 匹配 /users/123
此时访问 /users/123 会进入 v2，没问题；但访问 /users/abc 会 fallback 到 v1 —— 表面看合理，实际隐患在于：v1 的 handler 可能没做输入校验，而 v2 的 {id:int} 约束又不会主动拦截非法值并返回 404，容易掩盖数据层错误。
- 建议所有版本路径参数都加显式约束，比如
{id:string min(1) max(32)}或{id:int min(1)}，避免模糊匹配 - 不要依赖 “v1 路由更宽泛所以兜底” 的想法：Iris 不保证 fallback 行为，尤其在启用
StrictSlash或自定义Router时，行为可能变化 - 测试时务必覆盖边界值：比如
/v1/users/（空 ID）、/v2/users/abc（非数字），确认返回的是明确的 404 而非 500 或静默失败
别忽略版本路由的文档与测试同步成本
路径前缀看似简单，但每个新增版本都要同步更新三处：路由注册、Swagger 注解（如果用 iris-swagger）、集成测试用例。漏掉任何一处，线上就可能出问题。
比如用 swagger.New 生成文档时，若没给 v2 接口加上 @Version "2.0" 注释，生成的 OpenAPI JSON 里就不会标记版本字段，前端 SDK 自动生成工具可能直接忽略该接口。
- 推荐在每个
Party初始化后，立即注册对应版本的文档中间件，而不是集中到主应用注册 - CI 流程中加入检查：用
go list -f '{{.Deps}}' ./... | grep iris确保所有版本路由都 import 了对应中间件包，防止因未引用导致编译通过但运行时报nil pointer - 版本切换不是只改路径：数据库 schema、缓存 key 前缀、事件消息 topic 名称，往往也要随路由版本升级，这些地方比路由本身更容易被遗忘
