必须用指针字段+自定义UnmarshalJSON区分“未提供”与“显式传零”：指针nil表示未提供，非nil才解析；对null也统一置nil，并记录日志监控废弃字段，确保兼容可追溯。
旧客户端发来的 JSON 请求里缺字段，json.Unmarshal 不报错但字段为零值，业务逻辑误判“用户传了 0”而不是“根本没传”——这会导致注册时把 Age 当成 0 存库、状态字段被清空等线上事故。必须用自定义解码逻辑区分“未提供”和“显式传零”。
用指针字段 + 自定义 UnmarshalJSON 捕获缺失语义
Go 标准库对缺失字段完全静默，int 字段没传就是 0，string 就是 ""，无法区分意图。指针是唯一能表达“未提供”的原生方式，但仅靠指针还不够：如果旧客户端突然开始传 null，*int 会变成 nil，而你可能仍想把它当“未提供”处理。
实操建议：
- 所有新增或需兼容的字段统一用指针类型：
Age *int `json:"age,omitempty"` - 对关键字段（如状态、开关类）额外实现
UnmarshalJSON方法，在里面判断nil和"null"都归为“未提供” - 避免在
UnmarshalJSON里做复杂校验或调用外部服务——它只负责解析，不负责业务逻辑
示例：
type UserRequest struct {
Name *string `json:"name,omitempty"`
Age *int `json:"age,omitempty"`
}
func (u *UserRequest) UnmarshalJSON(data []byte) error {
type Alias UserRequest // 防止递归调用
aux := &struct {
Age *json.RawMessage `json:"age"`
*Alias
}{
Alias: (*Alias)(u),
}
if err := json.Unmarshal(data, &aux); err != nil {
return err
}
if aux.Age != nil {
if bytes.Equal(*aux.Age, []byte("null")) {
u.Age = nil // 显式 null → 视为未提供
} else {
// 正常解析
if err := json.Unmarshal(*aux.Age, &u.Age); err != nil {
return err
}
}
}
return nil
}
旧字段废弃但客户端仍在传，怎么既接收又不污染新逻辑
直接删字段或加 json:"-" 会让服务端彻底收不到该字段，失去监控和灰度能力；但保留原字段又怕新逻辑误用。核心是“收得到、看得见、用不上”。
实操建议：
- 废弃字段保留在 struct 中，去掉
json:tag 或改用json:"old_field,omitempty"，确保能反序列化进来 - 加注释说明：
// Deprecated: use CreatedAt instead. Logged for migration tracking. - 在 handler 开头统一扫描请求 body，用
json.RawMessage提取所有字段名，记录是否含废弃字段（如log.Printf("deprecated field 'user_id' received from %s", r.RemoteAddr)） - 绝不把废弃字段赋值给新业务变量；如有必要映射，只在明确标注的转换函数里做，且加
if oldField != nil { ... }判断
第三方 API 响应结构突变导致的类型不匹配，如何弹性兜底
比如你定义的 Status string，对方某天开始返回 "status": true，json.Unmarshal 直接 panic 报 cannot unmarshal bool into Go value of type string。标准库不支持容错解析，必须自己挡在前面。
实操建议：
- 对所有第三方响应，先用
json.RawMessage接收原始字节，再分路径解析 - 写一个通用的“宽松字符串解析器”：遇到
bool就转"true"/"false"，遇到number就fmt.Sprintf("%v")，再交给json.Unmarshal - 不要全局替换
encoding/json—— 只对高风险第三方接口启用，避免影响内部服务性能 - 日志中必须记录原始响应片段（截断前 200 字符）和转换动作，否则排查时无从下手
最易被忽略的一点：兼容逻辑本身要有可观测性。字段是否被传、null 是否被归一、类型转换是否触发——这些都不能只靠代码注释，得有日志、指标、甚至链路追踪里的 tag。否则上线后没人知道旧客户端到底还活没活着。
