URL路径嵌入版本号（如/v1/users）是Go微服务中最优选择，因其支持CDN缓存、Nginx路由、OpenAPI生成及前端感知；Header方案需手动解析且易出错；query参数不可缓存且不语义。
API 版本号该放在 URL 还是 Header？
Go 微服务中，URL 路径嵌入版本号（如 /v1/users）是最常见且最易调试的选择。它天然支持 CDN 缓存、Nginx 路由分发、OpenAPI 文档生成，也方便前端直接感知变更。而用 Accept 或自定义 Header（如 X-API-Version: v2）虽更“RESTful”，但在 Go 的 HTTP 路由层（gorilla/mux、chi、net/http.ServeMux）中需手动解析、路由分发，容易漏判或覆盖错误。
实际项目中，URL 路径版本的可维护性远高于 Header 方案——尤其当多个团队并行开发 v1/v2 接口时，路径隔离能避免 handler 混杂和中间件错配。
- 别用
query 参数（如?version=v2），它不可缓存、不语义、不支持路由树匹配 - 如果必须用 Header（例如遗留系统强约束），请在中间件中统一提取并注入到
context.Context，后续 handler 通过ctx.Value()获取，而非重复解析请求头 - 版本前缀统一用小写
v1、v2，避免api/v1和v1/api混用导致路由歧义
用 chi 或 gorilla/mux 实现多版本路由隔离
以 chi 为例，它支持嵌套路由器，天然适合按版本切分：
func main() {
r := chi.NewRouter()
// 公共中间件（日志、recover、CORS）
r.Use(middleware.Logger, middleware.Recoverer)
// v1 路由组
v1 := chi.NewRouter()
v1.Get("/users", v1GetUsersHandler)
v1.Post("/users", v1CreateUserHandler)
r.Mount("/v1", v1)
// v2 路由组（字段校验、响应结构、DB 查询逻辑可能不同）
v2 := chi.NewRouter()
v2.Get("/users", v2GetUsersHandler) // 返回带 avatar_url 字段
v2.Post("/users", v2CreateUserHandler) // 新增 nickname 校验
r.Mount("/v2", v2)
http.ListenAndServe(":8080", r)
}
关键点：
立即学习“go语言免费学习笔记（深入）”；
- 每个版本用独立
chi.Router，避免 handler 互相污染 - 不要在同一个路由组里写
r.Get("/v1/users", ...)和r.Get("/v2/users", ...)—— 这会丢失路由树结构，也不利于中间件按版本启用（比如 v2 需要额外鉴权） - 若用
gorilla/mux，等价做法是：先subr := r.PathPrefix("/v1").Subrouter()，再注册子路由
如何复用结构体又保持 v1/v2 响应兼容？
硬编码两个完全独立的 struct（UserV1、UserV2）会导致重复逻辑和序列化冗余。更实用的做法是：一个基础 struct + tag 控制序列化行为 + 构造函数封装差异。
例如：
type User struct {
ID int `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
AvatarURL string `json:"avatar_url,omitempty"` // v1 不设值，自动忽略
CreatedAt time.Time `json:"created_at"`
}
func (u *User) ToV1() map[string]interface{} {
return map[string]interface{}{
"id": u.ID,
"name": u.Name,
"email": u.Email,
"created_at": u.CreatedAt.Format("2006-01-02"),
}
}
func (u *User) ToV2() map[string]interface{} {
return map[string]interface{}{
"id": u.ID,
"name": u.Name,
"email": u.Email,
"avatar_url": u.AvatarURL,
"created_at": u.CreatedAt.UTC().Format(time.RFC3339),
}
}
这样既复用核心字段，又明确区分输出契约。比用 json:",omitempty" 动态控制更可控——因为 v1/v2 的字段语义、格式、是否必填都可能不同，靠 tag 很难覆盖全部场景。
- 别依赖
json.Marshal直出 struct，尤其当 v1 需字符串时间、v2 需 ISO8601 时，struct tag 无法表达格式差异 - 如果 v2 新增了非空字段（如
status），v1 的 handler 必须显式赋默认值或跳过，否则前端可能收空值引发崩溃 - 数据库模型（
UserModel）建议与 API struct 完全分离，用mapstructure或手写ToAPI()方法转换，避免 ORM struct 泄露到接口层
如何安全下线旧版本 API？
下线不是删代码，而是分三步走：监控 → 告警 → 拒绝。Go 服务中，可在版本路由入口加一层守卫中间件：
func versionGuard(version string) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if version == "v1" && isV1Deprecated() {
http.Error(w, "API version v1 is deprecated. Please upgrade to v2.", http.StatusGone)
return
}
next.ServeHTTP(w, r)
})
}
}
// 在路由注册时启用
v1 := chi.NewRouter()
v1.Use(versionGuard("v1"))
v1.Get("/users", v1GetUsersHandler)
r.Mount("/v1", v1)
其中 isV1Deprecated() 可读配置文件、环境变量或远程配置中心（如 Consul）。关键是：下线前至少保留 30 天 410 Gone 状态码返回，并记录所有 v1 请求的 User-Agent 和 IP，用于识别未升级客户端。
- 别用
404下线旧版——它掩盖真实意图，也让客户端误以为是路径写错 - 别直接 panic 或 log.Fatal —— 这会让整个服务重启，影响其他版本
- 如果用了 gRPC，对应的是
codes.Unimplemented，但 HTTP 场景下410是标准且最清晰的选择
版本管理最难的从来不是技术实现，而是跨团队对齐下线窗口、文档更新节奏、以及是否真敢把 v1 的测试用例从 CI 流水线里删掉——这些往往比写几个 router 更耗精力。
