Go API版本管理应采用URL路径前缀（如/v1/users），通过路由组隔离、handler分版本适配、service层复用、DTO独立定义及文档/生命周期管控实现。
在 Go 语言中实现 API 版本管理，核心思路是将版本信息融入路由设计，并配合清晰的代码组织结构，避免逻辑混杂、维护困难。不建议用 query 参数（如 ?v=2）或请求头（如 Accept: application/vnd.myapi.v2+json）作为主要版本控制手段——它们不利于文档生成、调试、缓存和网关识别。推荐使用 URL 路径前缀（如 /v1/users、/v2/users）方式，直观、可读性强、兼容性好。
路由层按版本分离
使用标准 net/http 或主流框架（如 Gin、Echo、Chi）时，为每个版本注册独立的路由组。以 Gin 为例：
r := gin.Default()
// v1 路由
v1 := r.Group("/v1")
{
v1.GET("/users", handlers.GetUserV1)
v1.POST("/users", handlers.CreateUserV1)
}
// v2 路由（字段校验、响应结构调整）
v2 := r.Group("/v2")
{
v2.GET("/users", handlers.GetUserV2)
v2.POST("/users", handlers.CreateUserV2)
v2.PUT("/users/:id", handlers.UpdateUserV2) // 新增接口
}
这样能天然隔离不同版本的中间件、认证策略、限流规则。例如 v2 可单独启用更严格的 JWT 校验或 OpenAPI 验证中间件。
Handler 与业务逻辑分层解耦
避免在 handler 中写重复业务逻辑。推荐按“版本 → 接口 → 服务”三级组织：
-
handler/v1/user.go：只做参数解析、错误包装、响应格式化（如统一
{data: ..., code: 0}） -
handler/v2/user.go：适配新字段、新状态码（如 v2 返回
201 Created而非200 OK），复用底层 service -
service/user.go：提供无版本语义的核心方法（
userSvc.GetByID(ctx, id)），v1/v2 handler 共享
当 v2 新增「软删除」字段时，仅需在 v2 handler 中补全字段映射，service 层无需改动；若底层数据模型变更（如用户表加字段），也只需更新 service 的 DAO 层，不影响已有版本接口行为。
共享模型 + 版本专属 DTO
不要让 v1 和 v2 共用同一个 struct 做 HTTP 响应。定义明确的 DTO（Data Transfer Object）：
// dto/v1/user.go
type UserResponseV1 struct {
ID uint `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
// dto/v2/user.go
type UserResponseV2 struct {
ID uint `json:"id"`
FullName string `json:"full_name"` // 字段名变更
Email string `json:"email"`
Status string `json:"status"` // 新增字段
CreatedAt time.Time `json:"created_at"`
}
在 handler 中完成 domain model 到对应 DTO 的转换。可用 mapstructure 或轻量映射库（如 transform），也可手写转换函数确保可控性和性能。
文档与生命周期管理
使用 swaggo/swag 生成 Swagger 文档时，为每个版本单独生成
docs 包并挂载到不同路径（如 /v1/docs、/v2/docs）。同时在启动时打印支持的版本列表：
log.Printf("✅ API versions enabled: v1 (deprecated), v2 (current), v3 (beta)")
对已废弃版本（如 v1），添加中间件自动返回 301 Moved Permanently 或 410 Gone，并在响应头中提示迁移路径：
ctx.Header("X-API-Deprecated", "true")
ctx.Header("X-API-Redirect", "/v2/users")
ctx.JSON(410, gin.H{"error": "v1 is deprecated, please use v2"})
配合监控（如 Prometheus 记录各版本调用量），可量化下线节奏，避免突然中断老客户端。
