必须将版本号写入URL路径前缀，如/api/v1/users和/api/v2/users，以实现缓存隔离、路由精准匹配、灰度可控及中间件/业务逻辑彻底分离。
必须把版本号写进 URL 路径前缀，别用 Accept 头或 query 参数
缓存层（Nginx、Cloudflare、移动端 SDK）基本不认 Accept 或 version=2 这类请求头或查询参数。实测中，proxy_cache_key 默认不含 header，Vary: Accept-Version 在多数 CDN 上形同虚设——结果就是 v1 和 v2 响应被混存在同一个缓存键下，灰度流量错乱、日志无法归因、前端调试还得手动构造 header。
正确做法只有一条：/api/v1/users 和 /api/v2/users 必须是两条完全独立的路径。这样：
- 路由匹配走 Radix Tree 前缀查找，O(1) 性能，无正则开销
- Nginx access log 里直接 grep
"v1"或"v2"就能算出流量占比 - 前端改个 URL 就能切版本，不用动 Postman 或代码
用 e.Group() 按版本+业务域扁平化分组，禁止嵌套
别写 e.Group("/api").Group("/v1").Group("/users") —— 这会让中间件挂载错层、日志路径和实际匹配路径不一致（比如日志记 /api/v1/users/123，但路由树收到的是 /v1/users/123），而且路径拼接容易出错。
应该一级声明清楚，每个分组只管一个语义单元：
v1Users := e.Group("/api/v1/users")
v2Users := e.Group("/api/v2/users")
v1Posts := e.Group("/api/v1/posts")
v2Posts := e.Group("/api/v2/posts")
-
v1Users.Use(jwtAuth())，v2Users.Use(oauth2Scope("users:read"))，中间件可彻底独立 - 两个
GET("/:id"handler 可以用不同结构体、不同 DB 查询字段、不同校验规则 - 灰度时只需在网关层开关
/api/v2/*流量，代码不动
强隔离场景下启动独立 echo.Echo 实例
当 v1 和 v2 不只是 handler 不同，而是中间件栈、错误处理逻辑、DB 连接池、日志采样率都需彻底分离时，共用一个 echo.Echo 实例会埋坑：比如 v2 引入新中间件导致 v1 日志格式突变，或 v1 的 panic recover 拦截了 v2 的业务错误。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
这时该拆就拆：
- 各自监听不同端口（如
:8081和:8082），由反向代理做路由分发 - DB 连接池、Redis 客户端、HTTP 客户端实例完全隔离
- 错误中间件、日志 hook、指标上报配置互不影响
代价是运维多一个进程，换来的是真正的运行时隔离。
c.Bind() 和 c.Validate() 不负责业务逻辑校验
很多人以为给 v2 的 handler 加个 validate:"required,email" 就算完成版本升级，其实这只是结构校验。v1 到 v2 的关键差异往往在业务层：比如 v2 新增手机号唯一性检查、v2 禁止修改已发布的文章状态、v2 的用户角色字段从字符串改为枚举值。
这些不能靠 c.Bind() 或 c.Validate() 解决：
-
c.Bind()静默跳过未传字段，除非加json:"name,required"，但这也只校验存在性 -
c.Validate()不支持跨字段校验（如 password 和 confirm_password 是否一致） - 真正业务规则必须下沉到 service 层，且 v1/v2 应该使用各自独立的 service 实现
路径分开了，handler 分开了，但最容易被忽略的，是业务校验逻辑是否也跟着版本走了——漏掉这点，API 版本就只是 URL 上的幻觉。
