用URL路径做版本标识最稳妥，因在反向代理、API网关、缓存、日志追踪中零歧义；Header或Query方式易被中间件丢弃、调试困难、测试不便。
用 URL 路径做版本标识最稳妥
绝大多数 Go 微服务选择 /v1/users、/v2/users 这种路径前缀方式，不是因为多酷，而是它在反向代理（Nginx / Envoy）、API 网关（Kong / APISIX）、客户端缓存、日志追踪上都零歧义。Header 或 Query 参数方式容易被中间件吞掉、日志里不显、调试时看不见。
使用 gorilla/mux 或 gin 时，直接按路径分组注册路由即可：
router := gin.Default()
v1 := router.Group("/v1")
{
v1.GET("/users", getUsersV1)
v1.POST("/users", createUserV1)
}
v2 := router.Group("/v2")
{
v2.GET("/users", getUsersV2) // 可能返回带 ID 字段的结构体
v2.POST("/users", createUserV2) // 可能校验邮箱格式更严格
}
- 别把版本号写死在 handler 名里（比如
getUsersV1Handler），而应在路由层隔离，handler 只管业务逻辑 - 同一资源不同版本的 handler 必须独立实现，禁止用
if version == "v2"混写，否则无法单独部署、灰度或回滚 - Swagger 文档生成工具（如
swaggo/swag）需为每个Group单独打标签，否则@version注释会失效
用 HTTP Header 做版本协商要格外小心
如果团队坚持用 Accept: application/json; version=v2 或自定义头 X-API-Version: v2，Go 服务端必须在每个 handler 开头做解析和校验，且不能依赖中间件统一处理——因为不同 endpoint 可能支持的版本范围不同（比如 /health 只有 v1，/orders 已上线 v3）。
常见错误是只检查 header 存在与否，忽略值是否合法：
立即学习“go语言免费学习笔记（深入）”；
func getVersionFromHeader(c *gin.Context) (string, error) {
v := c.GetHeader("X-API-Version")
switch v {
case "v1", "v2", "v3":
return v, nil
default:
return "", fmt.Errorf("unsupported version: %s", v)
}
}
- HTTP/2 下某些代理可能丢弃自定义 header，务必在 ingress 层显式透传
X-API-Version -
Accept头方案与 content negotiation 语义冲突，浏览器、curl 默认不带，测试极不方便 - 所有 client SDK 必须强制封装 header 设置逻辑，否则调用方极易漏传导致 fallback 到默认版本（往往不是预期行为）
版本兼容性必须靠 contract test 保障
接口版本升级不是改完代码、重启服务就完事。Go 项目中，光靠单元测试覆盖 handler 入参出参远远不够——你得验证 v2 的 JSON 结构是否真的能被旧版客户端（只认 v1 schema）安全忽略新增字段，以及 v1 客户端发来的请求 body 是否仍被 v2 handler 正确解析（比如 v2 新增了非空字段但 v1 不传，是否 panic？）。
推荐用 gojsonschema + YAML fixture 做契约测试：
func TestV2UserCreateContract(t *testing.T) {
schema := loadSchema("v2_user_create_request.json")
for _, fixture := range []string{"v1_client_payload.json", "v2_client_payload.json"} {
data := loadFixture(fixture)
result := schema.Validate(data)
if !result.Valid() {
t.Errorf("contract broken for %s: %v", fixture, result.Errors())
}
}
}
- 每个版本的 OpenAPI spec（
swagger.yaml）必须由 CI 自动校验是否向后兼容：新增字段设nullable: true，不删字段，不改类型 - 数据库迁移脚本（如
golang-migrate）必须与 API 版本发布节奏对齐；v2 接口依赖的新字段，其 DB column 必须在 v2 上线前完成ADD COLUMN ... DEFAULT NULL - 禁止在 handler 里用
json.RawMessage吞掉未知字段——这会让 contract test 彻底失效
不要让版本控制逻辑污染业务代码
版本判断必须收口在 transport 层（HTTP handler 或 gRPC gateway），业务 service 层函数签名应完全无版本痕迹。例如：
❌ 错误做法：service 层暴露 CreateUserV2(req UserV2Req) error
✅ 正确做法：transport 层把 v1 和 v2 请求分别转成统一的 domain model，再调同一个 userSvc.Create(ctx, userDomain)
- domain model 字段应取各版本交集，并用嵌套 struct 表达可选扩展（如
Metadata map[string]interface{}），避免每升一个版本就改 service 接口 - DTO（Data Transfer Object）必须按版本严格分离，
v1.UserResponse和v2.UserResponse是两个独立 struct，不可共用或 embed - 日志打点必须包含
api_version=v2字段，否则线上排查时根本分不清是哪个版本的逻辑出了问题
版本控制真正的复杂点不在怎么写路由，而在于如何让不同版本的 DTO、domain model、DB schema、client SDK、文档、监控指标全部对齐。任何一环脱节，都会让“平滑升级”变成线上事故的温床。
