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 失效。
