最直接可靠的 API 版本控制方式是使用 URL 路径前缀（如 /v1/users、/v2/users），因其路由天然支持、调试直观、网关无侵入路由，且应避免冗余 /api/v1/ 前缀和 Accept Header 主版本控制。

用 URL 路径区分版本最直接可靠

绝大多数 Golang 微服务选择 /v1/users、/v2/users 这类路径前缀做版本隔离，因为 HTTP 路由天然支持、调试直观、反向代理（如 Nginx、Envoy）和 API 网关（如 Kong、APISIX）都可无侵入地路由到不同服务实例或 handler 分支。

Go 标准库 net/http 或主流框架（如 Gin、Echo）都通过注册不同路径实现：

router.GET("/v1/users", v1.GetUserHandler)
router.GET("/v2/users", v2.GetUserHandler)

注意：不要用 /api/v1/users 这种冗余前缀——/v1/ 本身已是语义化版本标识，额外加 api 只会增加维护成本且无实际收益。

常见错误是把版本号写死在 handler 内部逻辑里，导致无法复用中间件或统一日志打点。正确做法是让路由层明确分发，handler 只处理本版本的业务逻辑。

避免用 Accept Header 做主版本控制

虽然 RFC 7231 允许用 Accept: application/vnd.myapp.v2+json 携带版本信息，但实践中问题很多：

• 前端（尤其是浏览器、curl、Postman 默认行为）几乎不主动设这个 header，调试时容易漏掉
• gRPC-Web、OpenAPI 工具链对自定义 media type 支持弱，生成 client 代码易出错
• 网关或 CDN 缓存策略通常不识别自定义 Accept，导致缓存污染（v1 请求被缓存后，v2 请求可能返回 v1 响应）
• Gin/Echo 等框架需手动解析 r.Header.Get("Accept")，路由分支逻辑分散，可读性差

如果已有历史接口用此方式，建议只作为兼容层存在，新接口一律回归路径版本。

如何安全地废弃旧版接口

版本下线不是删代码，而是分阶段降级：

• 上线新版后，在旧版 handler 中添加 X-API-Deprecated: true 和 Deprecation: Thu, 01 Jan 2025 00:00:00 GMT 响应头
• 配合 Prometheus + Grafana 监控旧版调用量下降趋势，确认客户端已迁移完毕
• 删除路由注册前，先注释掉 router.GET("/v1/xxx", ...) 并部署，观察日志中是否还有未识别的 /v1/ 请求（说明有遗漏客户端）
• 真正删除代码前，确保 CI 流水线中所有集成测试、契约测试（Pact）都不再覆盖该路径

结构体字段变更必须向后兼容

版本升级时最容易踩坑的是 struct 定义。比如 v1 返回：

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

v2 新增字段但不能破坏 v1 客户端：

• 新增字段必须设为指针或使用 omitempty（如 Age *int `json:"age,omitempty"`），否则 v1 客户端收到未知字段会解析失败（尤其强类型语言 client）
• 禁止修改已有字段类型（int → string）、重命名（name → full_name）、删除字段
• 若必须改语义，新增字段（DisplayName），保留旧字段并标记为 deprecated（可通过 Swagger 注释或 godoc 提示）

字段级兼容比接口路径更难察觉问题，建议用 vacuum 或 vacuum 做 OpenAPI spec 自动比对。

真正的难点不在怎么写两个版本，而在于如何让 v1 客户端完全感知不到 v2 的存在——字段兼容性、错误码一致性、分页参数行为、空值处理，这些细节比路由多写几行代码更耗精力。