路径前缀式分组（如/v1、/v2）是Go API版本管理唯一推荐方式，需用gin.Group()、chi.Mount()或mux.PathPrefix()显式隔离路由树，配合独立结构体、中间件和文档生成。
直接用路径前缀（如 /v1、/v2）注册路由分组，是 Go API 版本管理唯一推荐的配置方式——它不依赖运行时解析、不破坏缓存语义、能被 Nginx/CDN/API 网关直接识别，且所有主流框架都原生支持。
用 Group 或 Mount 隔离版本路由树
别手动拼接路径或在 handler 里 if version == "v1" 分流。每个版本必须有独立的路由容器，确保路径注册后可被 router.Walk() 扫描、Prometheus 按 path 标签打点、OpenAPI 工具按前缀分组生成文档。
-
gin：用r.Group("/v1")和r.Group("/v2")，子路由自动继承前缀 -
chi：用r.Mount("/v1", v1Router)，其中v1Router是全新chi.Router -
gorilla/mux：用r.PathPrefix("/v1").Subrouter()，避免用{version}正则变量（性能下降 15–20%）
错误示范：r.Get("/v1/users", handler) 这种写法会让路由树扁平化，丢失分组语义；更糟的是 r.HandleFunc("/users", func(c *gin.Context) { if c.Param("version") == "v2" {...} })，这等于把路由逻辑塞进业务代码。
结构体和序列化契约必须物理隔离
哪怕 v1 和 v2 的 User 字段目前完全一致，也必须声明为两个独立 struct，比如 UserRespV1 和 UserRespV2。Go 的 JSON 序列化不认“逻辑等价”，只看字段名、tag 和嵌套结构。
立即学习“go语言免费学习笔记（深入）”；
- 新增字段（如
v2加了CreatedAt）不会意外出现在v1响应里 - 删除或重命名字段（如
v2把full_name改成name）不会导致v1客户端解析失败 - 避免用
omitempty隐式控制输出——v1的零值字段可能因v2新增字段而被跳过
转换逻辑应下沉：domain 层返回统一 userDomain，再由 toUserRespV1(userDomain) 和 toUserRespV2(userDomain) 分别映射，而不是传 domain struct 直接 json.Marshal。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
中间件挂载范围必须与版本对齐
通用中间件（日志、panic 恢复、CORS）挂到根路由器；版本专属中间件（如 v2 强制 JWT、v1 兼容 session）只能挂到对应 Group 或 Mount 的子路由器上。
- 错误：只在
v2.Group()里加鉴权中间件 →/v1/请求绕过校验 - 错误：在根
r.Use()里挂了某个 v2 专用中间件 →/v1/也会执行，可能 panic - 正确：根
r.Use(logger, recovery)+v1.Use(sessionAuth)+v2.Use(jwtAuth)
调试时用 curl -v http://localhost:8080/v1/users 能清晰看到请求是否经过预期中间件链，而 header 或 query 方案无法提供这种确定性。
废弃旧版本不能只靠文档，得靠响应头和监控联动
下线 v1 前至少提前 6 个月开始标记，否则客户端会静默失效。必须在每个 v1 handler 开头显式注入响应头：
c.Header("X-API-Deprecated", "true")c.Header("X-API-Deprecation-Date", "2027-04-01")
同时在 Prometheus 中配置告警规则：当 http_request_total{path=~"/v1/.*"} 的 QPS 连续 7 天低于阈值，触发通知；真正停用时返回 410 Gone，而非 404 —— 这是告诉客户端“不是找错地方，是这里已永久移除”。
最常被忽略的一点：路径前缀必须全小写、无斜杠歧义（/v1 ✅，/api/v1 ❌，/V1 ❌），否则 Nginx rewrite、CDN 缓存策略、前端 SDK 自动拼接都可能出错。
