iris 用 party 实现 api 版本路由，本质是路径前缀隔离；它提供独立上下文的子路由器，支持嵌套、中间件隔离与类型安全参数解析，需避免手动拼接路径、混用版本前缀及共享结构体导致的 json 序列化冲突。
用 iris.Party 分组管理不同 API 版本
版本路由本质是路径前缀隔离，Iris 用 Party 最自然——它不是装饰器或中间件，而是带独立上下文的子路由器。直接调用 app.Party("/v1") 返回一个新路由组，后续所有注册都自动挂载到该前缀下。
常见错误是手动拼接路径（比如写 app.Get("/v1/users", ...)），这会导致维护困难、无法统一加中间件、丢失子路由复用能力。
-
app.Party("/v1")和app.Party("/api/v1")都合法，选哪个取决于你的 API 设计规范，但一旦选定就别混用 - 每个
Party可单独启用日志、鉴权、CORS：比如v1.Use(verifyToken) - 嵌套
Party也支持：v1.Party("/users").Get(...)会注册为/v1/users
在 Party 中注册 handler 要注意接收参数类型
Iris 的 Context 是强类型的，版本路由本身不改变参数解析逻辑，但容易忽略路径参数与查询参数的绑定方式差异。
例如 v1.Get("/users/{id:uint64}", handler) 中 {id:uint64} 是路径参数，必须用 ctx.Params().GetUint64("id") 获取；而 ?page=1 这类查询参数得用 ctx.URLParam("page") 或 ctx.FormValue("page")。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 路径参数类型声明（如
{id:int}）仅用于校验，失败时自动返回 404，不会进 handler - 不要在
Party外层用ctx.Request().URL.Path手动截取版本号——绕过路由机制，失去Party提供的上下文隔离优势 - 如果需要透传版本信息给 handler，推荐通过
ctx.Values().Set("version", "v1")注入，而非从路径字符串里 parse
多个版本共用结构体时，避免 JSON tag 冲突
同一业务模型（如 User）在 v1 和 v2 中字段可能不同，硬编码 json:"name" 会导致 v2 新增字段无法序列化，或 v1 不兼容字段被误输出。
正确做法是为各版本定义专属 DTO 结构体，哪怕字段名一致，也分开声明：
type UserV1 struct {
ID uint64 `json:"id"`
Name string `json:"name"`
}
type UserV2 struct {
ID uint64 `json:"id"`
Name string `json:"name"`
Nickname string `json:"nickname,omitempty"`
CreatedAt int64 `json:"created_at"`
}
- 不要用
map[string]interface{}应对多版本——失去编译检查，字段错拼难发现 - 如果 v2 是 v1 的超集，可用嵌入 + 匿名结构体简化定义，但 JSON tag 仍需显式重写
- 用
ctx.JSON(200, userV1)显式传入对应版本结构体，别依赖全局模型
上线新版本时，旧版路由不能静默失效
真实场景中，v1 不会立刻下线，客户端升级有延迟。Iris 默认不会拦截未注册的路径，所以 /v1/xxx 一旦没定义 handler，就会 404；但更危险的是，有人误删了整个 v1.Party 块却没发现。
- 上线 v2 前，确保 v1 的路由注册代码仍在 main 函数或初始化逻辑中，且未被条件编译屏蔽
- 加一个兜底
NotFoundhandler 到根路由，打印请求路径和时间，能快速暴露“本该存在却 404”的版本接口 - 用
app.Get("/{v:alpha}/health", healthHandler)这类泛匹配路由做版本探活时要谨慎——它会覆盖所有字面量路由，优先级高于Party
版本路由真正的复杂点不在注册语法，而在于生命周期管理：v1 的中间件要不要同步更新？v2 的数据库查询是否引入 N+1？这些没法靠 Party 自动解决，得靠明确的版本迭代 checklist 和灰度发布策略。
