Golang微服务接口版本控制方法

URL路径版本控制最直接可靠，/v1/users比Header方式更易调试监控；应将版本耦合进路由，因运维、网关、日志、指标均依赖路径可识别性；需按版本分组注册handler并隔离实现，避免内部if分支。

用 URL 路径做版本标识最直接可靠

微服务中接口版本控制，/v1/users 比 Accept: application/vnd.myapi.v1+json 更易调试、更易监控、更少出错。Golang 的 HTTP 路由器（如 gorilla/mux、gin、原生 http.ServeMux）都天然支持路径前缀匹配，无需解析 Header 或自定义中间件做路由分发。

关键不是“能不能”，而是“要不要把版本耦合进路由”。答案是：要——因为运维、网关、日志、指标都依赖路径可识别性。

• GET /v1/orders 和 GET /v2/orders 可以绑定到不同 handler，互不干扰
• API 网关（如 Kong、Traefik）能基于路径前缀做路由、限流、降级
• Prometheus metrics 中 http_request_duration_seconds{path="/v1/orders"} 天然可区分版本
• 避免因客户端漏传 Accept 或 X-API-Version 导致静默 fallback 到旧版

gin 框架下按 v1/v2 分组注册 handler

使用 gin.Group() 是最清晰的组织方式，每个版本一个子 router，逻辑隔离，中间件可差异化配置。

func setupRouter() *gin.Engine {
	r := gin.Default()

	// v1 版本：启用旧版 auth 和日志格式
	v1 := r.Group("/v1")
	v1.Use(authMiddlewareV1(), loggingMiddlewareV1())
	{
		v1.GET("/users", getUsersV1)
		v1.POST("/orders", createOrderV1)
	}

	// v2 版本：启用 JWT + 新字段校验
	v2 := r.Group("/v2")
	v2.Use(authMiddlewareV2(), loggingMiddlewareV2())
	{
		v2.GET("/users", getUsersV2)
		v2.POST("/orders", createOrderV2)
	}

	return r
}

注意：getUsersV1 和 getUsersV2 必须是独立函数，不能共用同一 handler 里靠参数判断版本——否则业务逻辑混杂、测试难覆盖、无法单独灰度发布。

避免在 handler 内部用 if version == "v2" 做分支

这是最常见也最危险的反模式。表面省事，实际埋下长期维护雷：

• 单元测试需 mock 版本上下文，覆盖率难保障
• 无法对 v2 单独加熔断或限流（中间件已绑定到 group）
• Swagger 文档生成时无法自动区分请求/响应结构，swag init 会把 v1/v2 字段全塞进同一个 schema
• 某天删 v1 时，容易遗漏 if version == "v1" 分支里的副作用（如调用旧版下游、写旧表）

正确做法：v2 接口从 handler、service、DTO、repo 层全新建包，例如：

├── handler/
│   ├── v1/
│   │   └── user.go     // UserRequestV1, handleUserListV1
│   └── v2/
│       └── user.go     // UserRequestV2 (含 new_field *string), handleUserListV2
├── service/
│   ├── v1/
│   └── v2/             // 不复用 v1.service.UserSrv

数据库兼容性比接口更难处理

接口版本化只是表象，真正的复杂点在数据层。v2 接口返回新字段，往往意味着：

• 新增 DB 列（需加 ADD COLUMN，注意 MySQL 5.7+ 支持 online DDL，但仍有锁表风险）
• 字段语义变更（如 status 从 string → int enum，旧数据需迁移）
• v1 接口仍要读旧结构，v2 接口要读/写新结构 —— 不能只靠 ORM tag 切换

推荐方案：在 repo 层按版本提供不同 mapper，例如：

type UserRepo interface {
	GetByIDV1(ctx context.Context, id int64) (*UserV1, error)
	GetByIDV2(ctx context.Context, id int64) (*UserV2, error)
}

// UserV1 和 UserV2 是两个 struct，字段、Scan 方法、SQL 查询语句均独立
// 这样即使未来 v1 下线，v1 的 SQL 和映射逻辑仍可保留用于审计或导出

别指望靠 sql.NullString 或 map[string]interface{} 一劳永逸——它们只会把类型问题拖到运行时，且让 IDE 和 linter 失效。