必须用Group()而非拼字符串硬编码，因为拼接会破坏路由结构可见性、中间件版本隔离和反向代理匹配；各框架均要求显式分组（如Gin的r.Group("/v1")、Chi的r.With、Mux的PathPrefix.Subrouter），且版本段须为路径第一级，DTO需按版本严格隔离。
直接用 /v1、/v2 这样的路径前缀注册分组路由，是唯一能同时保证调试、监控、网关和文档可用的方案。
为什么必须用 Group() 或 Subrouter() 而不是拼字符串
硬编码 r.GET("/v1/users", handler) 看似省事，但实际会破坏三件事：
- 路由结构不可见：OpenAPI 工具、Prometheus metrics、
router.Walk()都无法识别“这是一个 v1 分组”，日志聚合失效 - 中间件无法按版本隔离：比如 v2 要加新鉴权逻辑，你没法只给 v2 挂中间件，只能在每个 handler 里重复判断
- 反向代理规则错位：Nginx 的
location /v1/匹配不到/users/v1这种路径，前缀不一致导致分流失败
不同框架的分组写法差异（Gin / Chi / Gorilla Mux）
所有主流框架都支持显式分组，但 API 名称和作用域细节不同：
- Gin：
v1 := r.Group("/v1")，v1.Use(authV1Middleware)只影响该分组；注意r.Use()是全局的，不会自动继承到子 group - Chi：
v1 := r.With(VersionMiddleware("v1"))，推荐新建独立chi.NewRouter()封装成版本模块，避免中间件污染 - Gorilla Mux：
v1 := router.PathPrefix("/v1").Subrouter()，子路由天然隔离，v1和v2的中间件完全不共享
别用 r.HandleFunc("/v1/users", ...) 直接注册——它绕过了分组机制，等于放弃版本边界。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
路径结构的两个硬约束
版本段必须是路径第一级，且不能冗余嵌套：
- ✅ 推荐：
/v1/users、/v2/users/:id/orders（嵌套资源走子 Group，不是拼字符串） - ❌ 错误：
/api/v1/users（除非你有/health、/metrics等非 API 路由，否则/api是多余前缀） - ❌ 错误：
/v1/api/users或/users/v1（破坏 REST 资源语义，/users应该稳定，版本是访问维度） - ❌ 错误：
/v1/users?version=v2（query 不参与路由匹配，CDN 缓存会把 v1/v2 响应混在一起）
DTO 必须按版本隔离，哪怕字段一模一样
复用同一个 struct（比如 User）做多个版本的 request/response 是高危操作：
- v2 新增字段
UpdatedAt time.Time，v1 客户端可能因 JSON 解析失败而崩溃 - v2 把
Status从 string 改成 enum，v1 客户端收到未知值会 panic - 正确做法：定义
V1User、V2User，即使字段名和类型相同也分开声明 - handler 内部做显式转换：
c.JSON(200, V1User{...})，而不是传 domain model 直接 encode
字段语义变更比结构变更更危险，这点容易被忽略——v1 的 status: "act" 和 v2 的 status: "active" 在客户端看来就是两个协议。
