用 Accept Header 做 API 版本路由，比 URL 路径更干净
Go 的 HTTP 路由器（比如 gorilla/mux 或 chi）本身不强制版本位置，但用 Accept 头做版本标识，能避免路径污染、保留资源语义，也方便客户端缓存同一 URL 的不同版本响应。
常见错误是把 v1 硬编码进路径，结果导致 /api/v1/users 和 /api/v2/users 本质是同一资源的两个端点，后期难统一鉴权、日志、监控。
- 客户端发请求时带
Accept: application/vnd.myapp.v2+json，服务端解析Accept头提取版本号 - 用
http.Header.Get("Accept")提取后，正则匹配v(\d+)，别依赖字符串切分——application/json; version=2这类写法也得兼容 -
chi可用中间件提前解析并塞入context：r.Use(versionMiddleware)，后续 handler 直接从r.Context().Value(versionKey)拿版本 - 注意：浏览器直接访问会发默认
Accept: text/html,*/*，测试时务必用curl -H "Accept: application/vnd.myapp.v1+json"，否则容易误判为“没版本”
net/http 中间件里怎么安全提取和校验版本
版本不是可选参数，而是影响数据结构、字段含义甚至业务逻辑的关键开关。中间件里不能只“读”，还得“拦”——无效版本必须拒绝，且返回明确错误（比如 406 Not Acceptable），而不是降级到 v1 或静默兜底。
- 校验逻辑建议放在中间件最前：先检查
Accept是否含有效 vendor MIME 类型，再抽版本号，再查是否在白名单里（如map[string]bool{"v1": true, "v2": true}） - 别用
strconv.Atoi直接转——万一正则没匹配到，会 panic；应先判断匹配结果非空，再转 - 版本号比较别手写逻辑，用
semver库（如github.com/Masterminds/semver/v3）处理v1.2.0这类格式，但注意：HTTP header 里一般只用v1、v2，语义化版本更适合 OpenAPI 文档或内部服务通信 - 如果同时支持 URL 和 Header 版本，优先级要明确定义（例如 Header > URL > default），并在文档里写死，否则不同客户端行为不一致
JSON 序列化时怎么按版本动态控制字段
版本差异常体现在字段增删、嵌套结构调整、甚至类型变更（比如 created_at 从 string 改为 RFC3339 timestamp）。硬写 if-else 易出错，也不利于维护。
立即学习“go语言免费学习笔记（深入）”；
- 推荐用结构体标签 + 自定义
MarshalJSON方法：给字段加version:"v1,v2"标签，序列化时反射读取当前版本，跳过不匹配的字段 - 别用
json:",omitempty"靠零值隐藏——v2 新增字段可能非零但 v1 不该返回，得显式控制 - 如果版本间字段名相同但含义不同（如 v1 的
status是字符串，v2 改成对象），必须用不同结构体，别共用一个struct—— 否则反序列化会混乱，且 IDE 无法提示字段可用性 - 性能敏感场景下，避免每次序列化都反射；可预生成各版本对应的
json.Marshaler实现，或用代码生成工具（如go:generate+easyjson）提前编译好
Header 版本控制在反向代理和网关层容易漏掉什么
很多团队在 Go 服务里做了完整版本路由，却忘了上游 Nginx、Kong 或 Istio 的配置——它们可能直接透传或覆盖 Accept，导致版本控制形同虚设。
- Nginx 默认不转发原始
Accept，需显式配置proxy_pass_request_headers on;，且确认没用proxy_set_header Accept ...覆盖 - Kong 的
request-transformer插件若启用了remove或add，可能误删Accept；检查插件配置中是否包含"accept"字段操作 - Go 服务作为反向代理（比如用
httputil.NewSingleHostReverseProxy）时，默认会清除部分 header，包括Accept；必须重写Director并手动复制：req.Header.Set("Accept", r.Header.Get("Accept")) - 测试时别只跑单元测试——用真实 curl 或 Postman 绕过网关直连 Go 服务，确认 header 正常传递；再加一层网关调用，对比输出是否一致
版本控制最难的不是写代码，而是让所有中间件、网关、客户端对“版本”有同一份理解。Header 方案看似轻量，一旦链路里任何一环忽略或改写它，整个版本隔离就失效了。
