必须优先从路径提取版本号，用正则^/api/(vd+)/匹配并存入c.set("api_version", "v1")；禁止strings.hasprefix手动判断；需按path>header>query顺序覆盖；版本中间件须绑定独立group，不可混用；struct、文档、监控均需按版本物理隔离。
中间件里解析版本号必须优先从路径提取
URL 路径是版本信息最可靠来源，/api/v1/users 这种结构能被 Echo 的 trie 路由器直接匹配，不触发正则、不依赖运行时字符串判断。中间件里别用 strings.HasPrefix(c.Request().URL.Path, "/v2/") 这类手动扫描——它漏掉带查询参数的路径（如 /api/v2/users?id=1），也绕过路由树优化。
正确做法是用正则一次性提取：匹配 ^/api/(v\d+)/，捕获组取版本号，再存入上下文：c.Set("api_version", "v1")。注意锚点 ^ 和结尾 /，避免把 /api/v100/assets/logo.png 误判成 v1。
- 正则必须在所有路由注册前挂载为全局中间件，否则
c.Param()尚未初始化，c.Request().URL.Path是唯一稳定字段 - 若同时支持
X-API-Versionheader，按「Path > Header > Query」顺序覆盖，避免客户端伪造 header 绕过路径约束 - 非法版本（如
v999）在此中间件中直接c.AbortWithStatusJSON(http.StatusBadRequest, ...)，不交给后续 handler
版本中间件必须绑定到 Group，不能全局共享
一个中间件实例不能既处理 v1 又处理 v2——v1 可能需要宽松校验、兼容空字段，v2 要强校验、注入新 scope，混用会导致行为错乱。必须用 e.Group("/api/v1") 和 e.Group("/api/v2") 分开声明，各自 .Use() 专属中间件。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
- 禁止嵌套写法：
e.Group("/api").Group("/v1")会导致中间件链断裂，调试时路径前缀难追踪 - JWT 认证这类前置中间件应挂载在 Group 外层（即全局或
/apiGroup），保证所有版本都鉴权后再分流 - 版本中间件内部可读取
c.Get("api_version")做轻量逻辑分支，但核心 handler 仍要物理隔离
响应结构体必须按版本拆包，中间件无法掩盖 struct 复用风险
中间件能分流请求、统一错误格式，但拦不住 json.Marshal() 时字段变更破坏旧版兼容性。比如 v1 的 User struct 里 json:"name" 改成 json:"full_name"，如果 v2 handler 错误引用了 v1 的 struct，v1 客户端收到的就是空 name。
- struct 必须分别定义在
handlers/v1/user.go和handlers/v2/user.go，包名不同、路径隔离 - 中间件里做
c.Set("api_version", "v2")后，handler 仍要显式 import 对应版本的 struct 包，不能靠中间件“自动切换” - OpenAPI 文档生成工具（如 swag）会按 struct 路径扫描，复用 struct 会导致 v1/v2 文档字段混在一起，前端 SDK 生成出错
灰度场景下中间件分流要与静态路由共存
真要对部分用户放行 v2（比如按 X-User-ID 哈希），中间件可以读 header 决定是否覆盖 api_version，但前提是主路由仍注册 /api/v1/users 和 /api/v2/users 两条静态路径——否则 CDN、网关、日志系统全失效。
- 灰度中间件应放在版本识别中间件之后、路由分发之前，仅修改上下文值，不改变实际请求路径
- 不要用
c.Redirect()或重写c.Request().URL.Path，这会让 Echo 的路由匹配失效，且破坏 HTTP 语义 - 灰度比例需在中间件里记录指标（如 Prometheus counter），方便观察 v2 流量占比，而不是靠日志 grep
c.Set("api_version", "v2") 就自动按版本切片。路径前缀 + Group 分离 + 包隔离，三者缺一不可。
