优先选 mergo.merge（结构稳定时），但须显式指定 mergo.withoverride 等策略；字段动态或版本变更需预转换或手写递归；c.shouldbindjson 不可重复调用，应统一结构或缓存复用；json 兼容需 omitempty、双字段桥接、零值初始化；合并后必须校验完整性。
字段冲突时 merge 函数选 mergo.Merge 还是手写递归？
取决于结构是否已知、规则是否固定。如果 struct 字段稳定且合并策略简单（如“overlay 覆盖 base”），mergo.Merge 是最快路径；但默认行为是 mergo.WithOverride，会把 nil 覆盖非空字段——这在版本升级中极易导致数据丢失。
常见错误现象：base.User{Name: "Alice", Email: "a@example.com"} 与 overlay.User{Name: "Bob", Email: nil} 合并后 Email 变成空字符串或 ""，而非保留原值。
- 必须显式传
mergo.WithOverride或mergo.WithAppendSlice，不加参数的调用不可靠 - 若字段含义随版本变化（如 v1 的
phone在 v2 拆成mobile和landline），mergo无法处理，得先做预转换再 merge - 动态字段（如用户自定义扩展字段
extra map[string]interface{}）建议放弃mergo，直接解析为map[string]interface{}+ 手写递归合并，对nil、slice、map分支做判断
c.ShouldBindJSON 读两次 body 导致 invalid character '}' after top-level value
这是 Gin 中最常被忽略的底层限制：HTTP body 是单次流式读取，c.ShouldBindJSON 内部调用 c.Request.Body，第二次调用就会读到空或报错。
典型使用场景：前端分两次提交 base 数据和 overlay 数据，后端想分别 bind 到两个 struct。
- 正确做法是约定统一请求体格式，例如
{"base": {}, "overlay": {}}，一次解到两个变量 - 若必须分步（如多页表单），改用 query 参数（
?step=2&ref_id=abc123）或 header（X-Ref-ID: abc123）传标识，后端从缓存（sync.Map或 Redis）查前序数据再合并 - 万不得已复用 body：用
io.ReadAll(c.Request.Body)提前读出字节，再用bytes.NewReader重建Body，但注意这会让日志中间件看不到原始 body
版本字段变更导致 JSON 解析失败的兼容写法
struct 字段增删改不是“加个 tag 就完事”，旧客户端仍会发来不含新字段的请求，新客户端也可能发来含废弃字段的 payload。Go 的 json 包默认拒绝未知字段，但更危险的是字段类型不一致（如 v1 返回 int 的 status，v2 改成 string）。
- 新增字段必须加
json:",omitempty"，并设零值（string默认""，int默认0），否则旧客户端解析会 panic - 废弃字段不能删，改为未导出字段并加注释：
oldStatus int `json:"status,omitempty"` // deprecated: use status_v2 - 重命名字段需双写：
Status int `json:"status"`和StatusV2 string `json:"status_v2,omitempty"`，并在UnmarshalJSON中手动桥接逻辑
合并后返回前必须校验结构完整性
c.JSON(200, result) 不检查字段是否缺失、类型是否错位、必填字段是否为空。尤其在跨版本合并时，容易出现 v1 客户端收到 v2 结构（多了字段）还能勉强解析，但 v2 客户端收到 v1 数据（缺字段）直接 panic。
- 校验应在 handler 最后一步做，不是靠中间件兜底——因为合并逻辑本身可能出错
- 对关键字段（如
ID、CreatedAt）做非空检查，用reflect或validator库辅助 - 若服务暴露给外部，建议在网关层加 OpenAPI Schema 校验，避免错误结构透传到底层
真正麻烦的不是怎么合并，而是合并后没人看返回值长什么样。线上跑着的 v1 接口，某天突然开始返回带 status_v2 字段的响应，前端没改代码，就靠 JS 的宽容性硬扛——这种“能用就行”的状态，才是版本冲突最顽固的温床。
