路径前缀式分组注册是Go实现API版本路由的唯一可靠方式，需用gin.Group("/v1")或mux.PathPrefix("/v1").Subrouter()隔离路由树，DTO结构体按版本严格分离，中间件独立挂载，禁用query或header主路由。
路径前缀式分组注册是 Go 实现 API 版本路由的唯一可靠方式，其他方案（query、header）会在缓存、监控、调试和文档生成上持续制造麻烦。
用 gin.Group() 或 mux.PathPrefix().Subrouter() 隔离版本路由树
别在 handler 里拼接路径或手动解析 r.URL.Path 提取版本——这会让路由表不可见、OpenAPI 工具无法识别、Prometheus 指标无法按版本聚合。
-
gin下必须用v1 := router.Group("/v1")，而不是router.GET("/v1/users", ...) -
gorilla/mux下对应v1 := r.PathPrefix("/v1").Subrouter()，不是r.HandleFunc("/v1/users", ...) - 每个版本子路由器应独立挂载中间件：比如
v1.Use(jwtV1Middleware)和v2.Use(oauth2Middleware)不能混用 - 路径必须严格对齐：如果
v2.GET("/users/:id", ...)存在，v1组里也得显式注册v1.GET("/users/:id", ...)，否则/v1/users/123直接 404
DTO 结构体必须按版本声明，哪怕字段完全一致
共用一个 User struct 是最隐蔽的兼容性炸弹。Go 的 JSON 序列化不校验 schema，v2 新增字段会直接泄漏到 v1 响应中，导致客户端解析 panic。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- 为每个版本定义独立结构体：
V1User、V2User，即使字段名和类型都一样 - handler 中必须显式转换：
c.JSON(200, V1User{...})，不能传 domain model 直接 encode - 避免用
json:",omitempty"控制字段输出——v2 新增字段设为零值时，v1 响应可能意外漏掉旧字段 - 字段语义变更（如
status从"active"改为"published"）需在 DTO 层做兼容映射，不能指望客户端同步改逻辑
不要用 Accept header 或查询参数做主版本路由
看似 RESTful，实则破坏可观测性和运维链路：curl 测试要加 header、浏览器直访失效、CDN 缓存策略难配置、Nginx 日志无法按路径过滤。
立即学习“go语言免费学习笔记（深入）”；
-
Accept: application/vnd.myapi.v2+json需手动解析r.Header.Get("Accept")，还要处理q=权重、多 type 混合等边界，gin 默认不支持 -
?version=v2不参与路由匹配，中间件无法拦截，同一 URL 下不同参数值会打穿 CDN 缓存 - 若强合规要求必须走 header，只应在最外层中间件统一提取并写入
c.Set("api_version", "v2")，后续 handler 通过c.GetString("api_version")读取，绝不重复解析 - 版本号只用
v1、v2，不用v1.2.3或v1.2——API 版本是契约变更，不是软件发布版本
真正容易被忽略的是 DTO 隔离和中间件按组注册这两点：前者常被当成“过度设计”跳过，结果上线后 v1 客户端突然报 JSON 解析错误；后者一旦遗漏，v2 新增的鉴权逻辑就会漏进 v1 流量，安全边界瞬间失效。
