API版本号应放在URL路径（如/v1/users），因其调试直观、网关路由简单、日志可读性强；Header方案仅适用于URL必须稳定且所有中间件显式透传校验的例外场景。
API 版本号该放在 URL 还是 Header？
绝大多数 Go 微服务选择 URL 路径嵌入版本号（如 /v1/users），不是因为“标准”，而是因为调试直观、网关路由简单、客户端日志可读性强。用 Accept 或自定义 header（如 X-API-Version: v2）在 Go 中需手动解析、易被中间件忽略、且无法被 OpenAPI 工具直接识别。
例外场景：当必须保持 URL 完全稳定（如嵌入第三方 SDK 的固定回调地址），才考虑 header 方案，但需确保所有中间件（包括反向代理、API 网关、Go 的 http.Handler 链）都显式透传并校验该 header。
用 Gorilla Mux 还是 Gin 实现多版本路由？
两者都能做，但关键区别在路由匹配优先级和中间件作用域。Gorilla Mux 的子路由（subrouter）天然支持按前缀隔离，比如：
router := mux.NewRouter()
v1 := router.PathPrefix("/v1").Subrouter()
v1.HandleFunc("/users", userHandlerV1).Methods("GET")
v2 := router.PathPrefix("/v2").Subrouter()
v2.HandleFunc("/users", userHandlerV2).Methods("GET")
Gin 则依赖 Group，但要注意：Gin 的 gin.Group 本质是路径前缀 + 共享中间件，若在 v1 group 中注册了全局 panic 恢复中间件，它不会自动作用于 v2 group —— 必须分别注册或用 Use() 显式挂载。
立即学习“go语言免费学习笔记（深入）”；
IMCart是目前国内首家最为完善的开源b2c商城系统。同时也是PAYPAL官方认证建站系统的金牌合作伙伴。系统支持多语言，多站点，移动端， 本地国际化，API对接等，丰富的营销功能跟完善的商品体系，优良的下单体验，更为符合SEO优化，完善的插件支持/模板中心更是让IMCART更加无法 替代。而IMCART全新的技术架构、全新的UI设计、丰富的促销体系、官方各项服务支持能从根源上解决了目前市面上一
- 避免混用
router.GET("/v1/users")和v1 := router.Group("/v1")，会导致重复前缀 - 版本 group 内不要直接写死
/v1，否则迁移成本高 - 若用 Gin，推荐统一用
engine.Group("/v{version}")+ 正则约束，再由 handler 解析version参数分发
如何让 v1 和 v2 共享 DTO 结构体又不互相污染？
别用继承或嵌套结构体模拟“兼容性”——Go 没有字段级版本控制。正确做法是为每个版本定义独立的请求/响应 struct，并用工具同步字段变更：
-
v1.UserCreateRequest和v2.UserCreateRequest字段名、类型、tag 可不同 - 用
mapstructure或copier在 handler 内做显式转换，而非靠 JSON tag 自动映射 - 共享的业务逻辑（如密码加密、权限校验）抽成纯函数，接收 interface{} 或具体版本 struct，不依赖字段名一致
- 禁止在
v1struct 上加json:",omitempty"试图“兼容未来字段”——v2 新增字段若未显式声明，JSON 解码会静默丢弃
Swagger 文档怎么按版本生成且不冲突？
swag CLI 默认只生成一份 docs，要支持多版本文档，必须拆开生成：
- 为每个版本维护独立的
docs目录，如docs/v1,docs/v2 - 在注释中用
// @BasePath /v1和// @title User API v1明确标识版本上下文 - 启动时按版本加载对应 docs 包：
http.Handle("/v1/swagger/", http.StripPrefix("/v1/swagger/", swaggerFiles.Handler)) - 注意：
swag init -g ./v1/main.go必须指定入口文件所在目录，否则扫描不到该版本的 handler 注释
最易被忽略的是错误响应结构——v1.ErrorResponse 和 v2.ErrorResponse 的 code 字段类型（int vs string）、details 字段是否嵌套，都会导致前端解析失败。版本升级时，连错误格式都要当成契约来管理。
