应将API版本号放在URL路径中，因其简单直观、调试友好且便于反向代理和日志分析；若选用Header方式（如Accept头），需在外层中间件统一解析并分发，避免漏判OPTIONS或静态路由。
API 版本号该放在 URL 还是 Header？
Go 服务中，Accept 头带版本（如 application/vnd.myapi.v2+json）比把版本塞进 URL（如 /v2/users）更符合 REST 原则，也利于路由复用和缓存。但现实里绝大多数团队选 URL 路径版本——因为简单、直观、调试友好、反向代理和日志分析都省事。
关键不是“对错”，而是统一。一旦选了 /v1/...，就别在中间混入 Accept: application/vnd...；否则 Gin 或 chi 的中间件会漏判、OpenAPI 文档生成混乱、前端 SDK 难维护。
- URL 版本：用
chi.Router按前缀分组，比如r.Group("/v1", v1Middleware)，每个 group 绑定独立的 handler 和 validator - Header 版本：必须在最外层中间件解析
Accept，提取v1/v2后动态 dispatch 到不同 handler，容易漏掉 OPTIONS 预检或静态文件路由 - Gin 用户注意：
c.Param("version")在/v1/users下拿不到值，得用c.FullPath()或正则匹配路径前缀
如何让 v1 和 v2 共享结构体但不互相污染？
直接复用同一个 struct User 给 v1/v2 用，看似省事，实则埋雷：v2 加个字段，v1 的 JSON 序列化可能多出字段（如果没关 json.OmitEmpty），或者 v1 客户端收到未知字段后解析失败。
正确做法是按版本定义独立 DTO（Data Transfer Object），哪怕字段名和类型完全一样。用 Go 的嵌入 + 字段标签控制序列化行为：
立即学习“go语言免费学习笔记（深入）”；
type UserV1 struct {
ID int `json:"id"`
Name string `json:"name"`
}
type UserV2 struct {
UserV1
CreatedAt time.Time `json:"created_at,omitempty"`
}
这样既复用了逻辑，又隔离了序列化契约。别用指针嵌入（*UserV1），会导致零值问题；也别依赖 map[string]interface{}，它会让编译期类型检查失效、IDE 跳转失灵。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
- v1 handler 只接收/返回
UserV1，v2 handler 只处理UserV2 - 数据库模型（如
db.User）应与 API 层完全隔离，用显式转换函数（如toUserV1()）桥接，避免反射或通用 mapper - 字段重命名（如 v2 把
name改成full_name）必须新建字段，不能靠json:"full_name"` 标签覆盖旧名——老客户端仍发 <code>name，服务端要能兼容接收
如何安全下线 v1 接口而不炸掉线上调用方？
没有“静默下线”。只要还有请求打到 v1，就不能删代码。真正的策略是三步走：监控 → 告警 → 降级。
在 v1 handler 开头加一行日志埋点 + Prometheus counter，例如：metrics.APIVersionRequests.WithLabelValues("v1").Inc()。持续观察 2 周，确认 v1 QPS 稳定低于阈值（比如
- 先返回
426 Upgrade Required或自定义X-Deprecated: true响应头，并在 body 里写清迁移截止时间和新 endpoint - 别直接
http.Error(c.Writer, "...", http.StatusGone)—— 很多老客户端不处理 410，会无限重试 - 最后阶段可加开关（如从
config.VersionDisableV1控制），灰度关闭部分 region 或 user_id 段，而不是全量 kill
Swagger/OpenAPI 文档怎么同步多个版本？
swag CLI 默认只扫当前代码，不会识别版本分支。如果 v1 和 v2 的 handler 分散在不同文件或包，swag init 会漏掉旧版接口，导致文档缺失或混淆。
解决方案是强制按版本组织注释入口：每个版本建一个 docs/v1/docs.go，里面只 import 本版本涉及的 handler 包，并用 // @title MyAPI v1 显式声明标题。运行时分别执行：
swag init -g docs/v1/docs.go -o docs/v1/swagger swag init -g docs/v2/docs.go -o docs/v2/swagger
然后 Nginx 或 Gin 中间件根据请求路径（/v1/swagger / /v2/swagger）返回对应静态目录。别指望一个 swagger.json 里塞所有版本——components.schemas 会冲突，UI 渲染也会错乱。
- 所有
// @Param和// @Success注释里的schema必须引用本版本 DTO，比如""UserV1""，不能写""User"" - 升级 swag 工具前务必验证：新版本是否仍支持多入口生成？某些 v1.8+ 版本会忽略未被 main 包 import 的注释
- CI 流程里加校验步骤：diff 新旧 swagger.json，确保 v1 文档没意外变更
版本演进最难的不是写代码，是让所有人（前端、测试、运维、第三方）在同一时间窗口内完成切换。留足缓冲期，比设计多一层抽象更重要。
