必须将版本号固化在路径前缀中（如/api/v1、/api/v2），因CDN、反向代理及浏览器缓存键默认不含Header或Query，否则会导致缓存污染、CORS预检失败、监控指标混淆；应使用扁平化e.Group("/api/v1")分组，禁用嵌套，必要时启用独立Echo实例隔离。
必须把版本号固化在路径前缀里，比如 /api/v1 和 /api/v2，否则灰度、CDN 缓存、反向代理都会出问题——这不是设计偏好，是 HTTP 缓存语义决定的硬约束。
为什么不能用 Header 或 Query 参数做版本路由
浏览器、CDN、Nginx 的缓存键（cache key）默认只包含 Method + Host + Path + Query（部分支持），但几乎都不包含请求头。如果你用 Accept-Version: v2 或 ?version=v2 路由，同一 URL 可能被缓存为 v1 响应，却返回 v2 数据，或反过来。
常见错误现象：
- 前端发
GET /api/users/123，第一次命中 v1 缓存，第二次被 Nginx 转给 v2 handler，但响应仍走原缓存通道，状态码/内容不一致 - CORS 预检请求（
OPTIONS）因无版本标识，无法正确匹配到对应中间件链，导致鉴权失败 - 日志和监控系统按路径聚合指标，
/api/users/123的 QPS、延迟、错误率全部混在一起，无法区分版本健康度
用 Group 实现扁平化多版本路由
每个版本用独立 e.Group() 声明，避免嵌套分组造成路径错位或中间件漏挂。
正确写法：
v1 := e.Group("/api/v1")
v2 := e.Group("/api/v2")
v1.Use(middleware.JWT()) // v1 专用鉴权
v2.Use(auth.OAuth2WithScope("users:read")) // v2 专用鉴权
v1.GET("/users/:id", v1UserHandler)
v2.GET("/users/:id", v2UserHandler)
关键点：
Echo框架 5.1.0
下载
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 不要写
e.Group("/api").Group("/v1")——外层空分组会导致中间件注册失效，且调试时路径匹配行为与预期不符 - 两个 handler 函数签名必须一致（
func(echo.Context) error），但内部可完全重构：字段校验规则、DTO 结构体、DB 查询逻辑、返回字段都可不同 - 如果 v2 新增了必填 header（如
X-Client-ID），就在v2.Use()里加校验中间件，v1 不受影响
强隔离场景：启动独立 Echo 实例
当 v1 和 v2 需要完全不同的 DB 连接池、错误处理策略、甚至日志格式时，共用一个 echo.Echo 实例会相互污染。
推荐做法：
- 分别初始化
v1Server := echo.New()和v2Server := echo.New() - 各自配置
Recover中间件的 panic 捕获行为（v1 返回 JSON，v2 返回 Problem+JSON） - 用 Nginx 或 Cloudflare 按路径前缀分流：
location ^~ /api/v1/ { proxy_pass http://v1_backend; } - 注意：两个实例监听不同端口（如
:8081和:8082），避免端口冲突
v5.3.1 升级对平滑升级的影响
如果你正在用 Echo v5.3.0 并依赖静态资源服务 + 分组路由 + 自定义 404 处理，必须升级到 v5.3.1。
这个小版本修复了两个关键问题：
-
Static处理器现在会保留已匹配 handler 的 404 状态，不再错误覆盖成 200；否则 v2 的/api/v2/static/logo.png找不到时可能返回 v1 的 fallback 页面 - Group 内隐式注册的默认路由（如
e.Any("/*", fallbackHandler)）现在能被子分组的同路径路由正确覆盖，避免 v2 路由意外命中 v1 的兜底逻辑
真正容易被忽略的是：v5.3.x 系列没有兼容性承诺。即使只是小版本升级，也要用你线上实际的路由表、中间件组合、静态目录结构跑完整回归测试——尤其是 GET /api/v1/users/123 和 GET /api/v2/users/123 是否始终返回各自版本的字段和状态码。
