Golang怎么做RESTful API的多版本共存-Golang-PHP中文网

必须使用 r.group("/v1") 分组管理版本路由，避免硬编码路径、确保中间件隔离与反向代理兼容；dto 必须按版本独立定义并显式转换，禁止复用结构体或依赖 accept 头做主版本控制。

golang怎么做restful api的多版本共存

必须用 `r.Group("/v1")` 分组，别拼字符串路径

硬编码 r.GET("/v1/users", handler) 看似简单，但会导致路由表膨胀、中间件无法按版本隔离、反向代理配置重复。Gin/Echo/Chi 都提供 Group() 方法，它是唯一能天然绑定前缀、作用域和中间件的机制。

常见错误包括：r.Group("/users/v1")（把版本塞进资源后）或 r.Group("/api/v1")（加冗余前缀），前者破坏资源语义，后者除非你同时暴露 /health 等非 API 路由，否则纯属多此一举。

v1 := r.Group("/v1") 和 v2 := r.Group("/v2") 必须是两个独立变量，不能复用同一个 group 实例
嵌套资源走子 Group：比如 orders := v1.Group("/users/:user_id/orders")，而不是拼 /v1/users/:user_id/orders
所有路径必须显式注册：哪怕逻辑一样，v1.GET("/users/:id", getV1User) 和 v2.GET("/users/:id", getV2User) 都得写全，缺一个就 404

`V1User` 和 `V2User` 必须是两个 struct，哪怕字段名一模一样

共用 User struct 是最隐蔽的兼容性雷——v2 加个 Nickname string 字段，v1 handler 一不小心用了 User{} 返回，v1 客户端解析 JSON 就 panic。Go 没有运行时 schema 校验，JSON 序列化只认字段标签和类型。

DTO 必须按版本声明，哪怕只是复制粘贴：

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

type V1User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}
type V2User struct {
    ID       int    `json:"id"`
    Name     string `json:"name"`
    Nickname string `json:"nickname"`
}

禁止用指针模拟可选字段来“凑合”老版本：v1 的 Name string 是必填契约，就不能在 v1 DTO 里改成 Name *string
handler 内必须显式转换：c.JSON(200, toV1User(dbUser))，绝不裸传 GORM 模型或 domain struct
数据库模型（如 GORMUser）保持稳定，只负责存；API 层响应永远走转换函数

别用 `version=v2` 查询参数做主路由

/users?version=v2 看起来 URL 干净，但实际会让 CDN 缓存失效、Prometheus 指标混杂、Swagger 文档错乱、Postman 调试反复失败。CDN 只看路径，不解析 query；http_request_duration_seconds{path="/users"} 会把 v1/v2 全塞进同一个 metric。

Accept 头方案（如 Accept: application/vnd.myapp.v2+json）仅适合内部灰度场景，调试成本高，且前端库默认不发该 header，容易漏测。

路径前缀是唯一能被反向代理、CDN、日志系统、监控平台无歧义识别的方案
如果真要用 Accept 做灰度，必须在中间件里统一拦截校验，非法版本（如 v999）立刻返回 400 Bad Request
绝对不要同时启用路径 + Accept 双版本路由，优先级没定义清楚，上线就逻辑串包

数据库变更必须兜底，字段语义变更比结构变更更危险

v2 新增 NOT NULL 字段，v1 接口不能因此崩出 500 Internal Server Error。service 层要主动降级或补默认值，比如查不到 nickname 就设空字符串，而不是让 ORM 报错穿透到 API 层。

更隐蔽的是字段语义变化：v1 的 status 是 "active"/"inactive"，v2 改成 "published"/"draft"。v1 客户端 if 判断直接失效，必须在 DTO 转换层做映射：

func toV1User(u *GORMUser) V1User {
    status := "inactive"
    switch u.Status {
    case "published":
        status = "active"
    case "draft":
        status = "inactive"
    }
    return V1User{Status: status}
}