版本控制核心是路由分流与接口隔离：优先用URL路径（如/api/v1/users）区分版本，辅以Header灰度；各版本需独立handler、隔离DTO、统一错误码前缀及独立OpenAPI文档。
版本控制的核心思路：路由分流 + 接口隔离
微服务中接口版本控制不是给每个接口加个 v1 或 v2 前缀就完事。关键是让新老版本逻辑解耦、可独立部署、互不影响，同时避免客户端频繁升级。Golang 本身不内置版本管理，需靠设计模式和路由机制实现。
用 Gin/Chi 等路由器按路径或 Header 区分版本
推荐以 URL 路径为第一优先级（如 /api/v1/users 和 /api/v2/users），语义清晰、调试方便、网关友好。也可结合 HTTP Header（如 X-API-Version: v2）做灰度或内部切换，但不建议单独依赖 Header——它对 CDN、日志、监控都不友好。
- Gin 示例：注册不同版本的路由组
r := gin.Default()
v1 := r.Group("/api/v1")
v1.GET("/users", handlerV1ListUsers)
v1.POST("/users", handlerV1CreateUser)
v2 := r.Group("/api/v2")
v2.GET("/users", handlerV2ListUsers) // 可能返回新增字段、分页结构变化
v2.POST("/users", handlerV2CreateUser) // 可能校验更严格、支持 JSON Schema
- 每个版本路由绑定独立 handler，背后可复用领域模型，但 DTO（Data Transfer Object）必须隔离
- 禁止 v2 handler 直接调 v1 的函数——容易埋下隐式依赖，破坏版本边界
DTO 分离 + 自动转换（可选）提升兼容性
老接口返回 UserV1 结构，新接口返回 UserV2，字段增减、嵌套变更都可能。硬编码 map 转换易出错，建议：
- 定义明确的版本化 DTO（如
user_v1.go,user_v2.go），不共用 struct - 用 mapstructure 或 copier 做字段级映射（适合轻量差异）
- 复杂场景（如字段语义重定义）写显式转换函数，例如
func ToV2(u *model.User) *UserV2，便于单元测试和审计 - 若需反向兼容（v2 请求接受 v1 格式 body），可用中间件解析并预转换，而非在 handler 里 if-else
统一错误码 + 版本文档驱动演进
不同版本的错误响应格式也应保持一致（如统一用 {"code": 40001, "message": "xxx"}），但错误码含义可随版本升级扩展。关键点：
立即学习“go语言免费学习笔记（深入）”；
- 错误码前缀按版本隔离（如 v1 错误码 1xxxx，v2 用 2xxxx），避免旧客户端误解新错误
- 用 Swagger 2.0 / OpenAPI 3.0 为每个版本生成独立文档（如
/docs/v1/openapi.json），配合 swaggo 自动生成 - 上线前强制校验：新版本接口是否覆盖了老版本所有业务路径？是否有废弃接口的明确下线时间表？
