Go中适配老版本API的核心是用新结构体包装旧数据、按需转换字段，而非直接修改struct；直接改会导致JSON解析失败或空指针错误，应通过wrapper struct嵌入+指针字段或函数做轻量转换，并路由层物理隔离v1/v2。
Go 里适配老版本 API 数据，核心不是“改旧代码”，而是用新结构体包装旧数据、按需转换字段——只要 JSON 解析层和业务逻辑解耦，就能零改动复用老 handler。
为什么直接修改 struct 会导致老客户端解析失败
常见错误现象：json: cannot unmarshal string into Go struct field User.Age of type int 或老客户端收不到新增字段却报错空指针。这是因为：
- 旧客户端发的是
{"name": "Alice", "age": "25"}（字符串），而新 struct 定义Age int，json.Unmarshal直接 panic - 你给 v1 结构体加了
Email string字段，没加omitempty，结果老客户端收到{"email": ""}，前端 JS 认为这是有效值 - 用
type UserV1 = UserV2这种类型别名，不会继承 JSON 标签，也不会改变字段行为，纯属无效操作
用嵌入 + 指针字段做数据层适配器
适用场景：v1 接口还在跑，但 DB 层或内部服务已升级到 v2 结构，你需要把 v2 数据“降级”成 v1 响应，或把 v1 请求“升格”进 v2 流程。
正确做法是定义一个 wrapper struct，嵌入原始类型，并只覆盖需要转换的字段：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
type UserV1 struct {
ID int `json:"id"`
Name string `json:"name"`
Age int `json:"age"`
}
type UserV2 struct {
ID int `json:"id"`
Name string `json:"name"`
Age string `json:"age"` // v2 改成字符串
Email *string `json:"email,omitempty"`
}
// 适配器：把 v2 数据转成 v1 响应
type UserV1Adapter struct {
v2 *UserV2
}
func (a UserV1Adapter) ID() int { return a.v2.ID }
func (a UserV1Adapter) Name() string { return a.v2.Name }
func (a UserV1Adapter) Age() int {
if a.v2.Age == "" {
return 0
}
age, _ := strconv.Atoi(a.v2.Age)
return age
}
// 使用时：
// v1Handler(w, r) → 从 DB 查出 *UserV2 → 构造 UserV1Adapter{v2: user2} → json.NewEncoder(w).Encode(adapter)
函数适配器处理单字段类型不一致
当只有个别字段类型冲突（如 time.Time vs string），又不想定义完整 struct，可用函数封装转换逻辑：
- 定义转换函数：
func v2TimeToV1String(t time.Time) string { return t.Format("2006-01-02") } - 在 handler 里手动映射：
v1Resp.BirthDate = v2TimeToV1String(v2.User.BirthDate) - 避免在 struct 方法里做耗时操作（如网络请求、DB 查询），适配器只做字段级转换
- 如果字段转换逻辑复杂且复用多处，再抽成独立 adapter struct；简单 case 函数更轻量
路由层必须物理隔离 v1/v2，别靠中间件猜版本
关键点容易被忽略：适配器只管数据，不管路由。如果你在同一个 r.Get("/users", handler) 里根据 r.Header.Get("X-API-Version") 动态切换逻辑，会带来三个隐性问题：
- CDN 和 Nginx 缓存失效——同一 URL 返回不同结构，缓存污染
- OpenAPI 文档无法准确描述两个版本的请求/响应差异
- handler 内部混杂 if v1 { ... } else { ... }，字段校验、日志、metrics 全部耦合，后续加 v3 更难拆
正确方式是路径前缀强制隔离：r.Mount("/v1", v1Router) 和 r.Mount("/v2", v2Router)，每个 router 内部用各自适配器，互不感知。
