不推荐在url路径硬编码版本号，应通过accept头或x-api-version头实现版本控制，配合dto隔离、契约演进、灰度路由及废弃策略。
go 微服务的 API 版本控制，**不推荐在 URL 路径里硬编码 v1、v2 这类字段**——它会污染路由语义、破坏资源标识性，且让版本升级/灰度/兼容性测试变得笨重。真正可维护的做法是把版本决策下沉到请求头或内容协商层，并配合接口契约演进策略。
用 Accept 请求头做内容协商式版本控制
这是最符合 REST 原则的方式：同一资源（如 /users）通过 Accept: application/vnd.myapi.v1+json 或 Accept: application/vnd.myapi.v2+json 区分响应格式与行为逻辑。gin 或 chi 等框架都支持按 Accept 头匹配路由或中间件分支。
- 定义清晰的 media type，例如
application/vnd.example.users+json; version=1，比简单拼接v1更易扩展参数 - 在中间件中解析
r.Header.Get("Accept")，提取version参数并写入c.Set("api_version", "1") - 后续 handler 里统一读取
c.GetString("api_version")，决定调用哪套 DTO 转换逻辑或领域服务分支 - 避免在每个 handler 里重复解析；也不要依赖正则提取 version，应使用标准库
mime.ParseMediaType
用自定义 Header（如 X-API-Version）快速落地但需谨慎
当客户端无法修改 Accept 头（比如某些旧 SDK 或前端 fetch 默认行为），可用 X-API-Version: 2 作为兜底方案。但它属于“非标准但实用”的折中，必须配合同步的文档和客户端约束。
- 务必在 gateway 层或入口 middleware 统一校验该 header 是否合法（只允许
"1","2"等白名单值），拒绝非法值返回400 Bad Request - 禁止在业务 handler 中直接读取
r.Header.Get("X-API-Version")—— 应由中间件解析并注入上下文，例如ctx = context.WithValue(ctx, keyVersion, ver) - 若同时支持
Accept和X-API-Version，需明确定义优先级（建议Accept> header），并在文档中写死 - 注意 gRPC-Gateway 场景下，http header 会透传到 gRPC 方法的
metadata.MD，需在 gateway 配置中显式声明转发
DTO 与 domain 分离：版本差异只体现在序列化层
真正的兼容性难点不在路由分发，而在数据结构变更。不要让 v2 handler 直接操作 v1 的 Struct，而是为每版 API 定义独立的 DTO（data transfer Object），再通过 domain model 做中心映射。
立即学习“go语言免费学习笔记（深入）”；
- 例如
user_v1.go和user_v2.go各自定义 JSON tag 和验证规则，互不影响 - domain 层保持稳定（如
domain.User），所有版本 DTO 都通过ToDomain()/FromDomain()转换 - 新增字段默认设为指针或带
omitempty，删除字段保留在 DTO 中但忽略反序列化（用json.RawMessage或自定义UnmarshalJSON拦截） - 避免用
Interface{}或map[string]interface{}做通用响应体 —— 它会让 OpenAPI 文档失效，也失去编译期检查
别忘了测试与可观测性配套
版本控制不是加个 header 就完事。没有对应测试覆盖和指标追踪，线上出问题时根本分不清是 v1 bug 还是 v2 兼容逻辑漏了。
- 每个版本的 endpoint 必须有独立的 HTTP 测试用例，包括边界 case（如 v1 client 访问 v2-only 字段是否静默忽略）
- 在日志和 metrics 中打上
api_versionlabel，prometheus 的http_requests_total{version="2"}能快速定位某版流量异常 - OpenAPI spec 按版本拆成多个文件（
openapi-v1.yaml,openapi-v2.yaml），用swag生成时通过// @version 2注释控制归属 - 灰度发布时，别只切流量比例 —— 要结合 header 值做精准路由，例如 istio VirtualService 中 match
headers["x-api-version"] == "2"
版本控制最容易被忽略的点，其实是“废弃策略”：v1 接口什么时候下线？有没有给客户端留够迁移窗口？有没有自动告警未升级的调用方？这些不写进 release checklist，光靠代码层面的隔离只是拖延问题。