路径前缀式分组注册是Go实现API版本路由的唯一可靠方式，需用gin.Group("/v1")或mux.PathPrefix("/v1")隔离路由树，独立挂载中间件、严格对齐路径、按版本声明DTO结构体，并禁用query/header版本路由。
路径前缀式分组注册是 Go 实现 API 版本路由的唯一可靠方式，其他方案（query、header）会在缓存、监控、调试和文档生成上持续制造麻烦。
用 gin.Group("/v1") 或 mux.PathPrefix("/v1").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 - 避免嵌套路由污染：比如
v1.Group("/admin").GET("/users", )会生成/v1/admin/users，但权限逻辑该抽成中间件复用，而非靠嵌套
DTO 结构体必须按版本声明，哪怕字段完全一致
共用一个 User struct 是最隐蔽的兼容性炸弹。Go 的 JSON 序列化不校验 schema，v2 新增字段会直接泄漏到 v1 响应中，导致客户端解析 panic。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 为每个版本定义独立结构体：
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 日志无法按路径过滤。
-
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 版本是契约变更，不是软件发布版本。写成 v1.2 会误导团队以为可以做向后兼容的小修小补，但实际只要字段删改、状态码调整、必填变可选，就该升 v2。
-
OpenAPI工具（如 swag）无法稳定识别v1.2这类字符串，生成的 tag 易乱序或丢失 - 反向代理配置时若写
/v1.*，可能把/v1.999误转到 v1 服务，引发未定义行为 - 数据库模型（如 GORM
UserModel）保持稳定，只负责存储；所有 API 层响应都走显式转换，例如userV1 := toUserV1(dbUser)，绝不裸露底层模型
真正需要“智能”的地方不在路由匹配，而在 DTO 转换与中间件隔离——路径前缀让路由本身变成静态、可预测、可观测的基础设施，所有动态逻辑（字段映射、权限差异、错误格式）都收束到版本明确的 handler 和结构体里。忽略这点，任何 header 或 query 的“灵活性”都会在三个月后变成线上故障的温床。
