API版本升级时DTO必须物理隔离，UserV1与UserV2需分包定义、显式转换和手动序列化，共用struct会导致字段泄漏、丢失或语义错乱。
API 版本升级时的类型转换问题，本质不是“怎么转”，而是“在哪转、谁负责转、转完能不能被正确序列化”——UserV1 和 UserV2 必须物理隔离，DTO 层强制拆分，任何跨版本共用 struct 或靠中间件动态 cast 的做法，上线后必出 JSON 字段泄漏或字段消失。
为什么不能共用 struct 做版本 DTO
共用一个 User struct 看似省事，但会导致 v1 客户端收到 v2 新增字段（如 Nickname），或 v1 必填字段因 v2 的 json:"name,omitempty" tag 被忽略而丢失。Go 的 JSON 序列化是全局生效的，tag 一改，所有引用该 struct 的 handler 都受影响。
- 字段语义变化：v1 的
Name string是必填；v2 改成Name *string表示可选，指针和非指针无法兼容 - JSON tag 冲突：
omitempty在 v1 不该出现，但若共用 struct 就没法单独控制 - 编译期无感知：结构体定义没变，但运行时序列化行为已不同，日志和监控都查不到根源
DTO 层必须显式定义 + 显式 Marshal
每个版本的 handler 结尾必须手动调用 json.Marshal(UserV1{}) 或 c.JSON(200, UserV1{})，绝不能传 domain model（如 user.User）直出。domain model 是业务内核，DTO 才是契约出口。
-
UserV1和UserV2应放在各自版本包下，例如dto/v1和dto/v2，避免 import 混淆 - 字段映射逻辑写在 handler 内或专用
ConvertToV1()函数里，不依赖反射或通用 cast 库——cast 会绕过字段语义，把nil自动转成空字符串，破坏 v1 的非空约束 - 测试重点不是“能转”，而是“v1 响应里没有
nickname字段，且name永远不为 null”
别用 cast 包做跨版本字段适配
github.com/spf13/cast 适合处理配置解析、CLI 参数等弱类型输入，不适合 API 契约层。它把 "true" 转 int 得 1、把 nil 转 string 得 ""，这种“智能”在 DTO 层是灾难。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- v2 返回
{"name": null, "nickname": "a"}，cast.ToXXX 可能把它塞进UserV1导致 panic 或静默丢字段 - cast.ToStringSlice(
[]interface{}{nil, "b"}) 得["", "b"]，但 v1 要求 name 非空，这个空字符串就是 bug - 真正需要的是确定性：v1 的
Name字段必须从 domain model 显式赋值，if u.Name == "" { return err }这类校验必须存在
升级时 domain model 到 DTO 的转换最容易漏掉的点
最常被忽略的是嵌套结构和 slice 元素的版本对齐。比如 UserV1 里 Orders []OrderV1，但 handler 里写了 u.Orders = domainUser.Orders，而 domainUser.Orders 是 []*domain.Order，直接赋值会跳过所有 v1 字段校验和 tag 控制。
- 嵌套字段必须逐层转换：
OrderV1.FromDomain(order)，不能靠 struct 字段名相同就直接复制 - slice 要用
make([]OrderV1, len(domainOrders))+ for 循环，避免浅拷贝指针导致后续修改污染 - time.Time 字段注意时区：v1 可能要求 UTC 字符串，v2 改成带时区偏移，
time.Format格式必须按版本硬编码，不能复用同一常量
版本升级中类型转换的复杂性不在语法，而在契约边界的显式声明——只要 DTO 不独立、Marshal 不显式、字段映射不逐层控制，就一定会在灰度期暴露为前端解析失败或监控指标错乱。路径前缀 /v1 只是入口，真正的隔离发生在每一行 json.Marshal 调用之前。
