最直接可靠的 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-We
b、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）都不再覆盖该路径
别依赖文档或邮件通知下游——总有团队没看。强制 header + 日志告警才是有效手段。
结构体字段变更必须向后兼容
版本升级时最容易踩坑的是 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 的存在——字段兼容性、错误码一致性、分页参数行为、空值处理，这些细节比路由多写几行代码更耗精力。
