本文介绍在 Go 语言中，通过自定义 json.Unmarshaler 接口实现对 JSON 字段（如 "data"）既支持数组又支持单个对象的灵活反序列化，避免类型重复、反射滥用和手动类型判断。
本文介绍在 go 语言中，通过自定义 `json.unmarshaler` 接口实现对 json 字段（如 `"data"`）既支持数组又支持单个对象的灵活反序列化，避免类型重复、反射滥用和手动类型判断。
在实际开发中，尤其是对接 RESTful API（如 JSON:API 规范）时，常遇到同一字段（如 "data"）在不同响应场景下返回结构不一致的问题：有时是对象 { "data": { ... } }，有时是数组 { "data": [ {...}, {...} ] }。Go 的标准 json.Unmarshal 默认要求结构体字段类型严格匹配，无法自动适配这种动态性。若为每种情况单独定义结构体（如 Resource 和 ResourceSingle），不仅破坏类型统一性，还会导致方法复用困难、嵌套关系（如 relationships 中的 data）需递归处理，显著增加维护成本。
最简洁、可扩展且符合 Go 惯例的解决方案是：实现 json.Unmarshaler 接口，在 UnmarshalJSON 方法中尝试多种解码路径，并统一归一化为内部切片表示。
以下是一个完整、健壮的实现示例：
package main
import (
"encoding/json"
"fmt"
"log"
)
type Resource struct {
Data []ResourceData `json:"-"` // 不直接参与默认 JSON 解析
}
// ResourceData 表示单个资源项
type ResourceData struct {
ID string `json:"id"`
Type string `json:"type"`
Attributes map[string]interface{} `json:"attributes"`
Relationships map[string]Resource `json:"relationships"`
}
// UnmarshalJSON 实现自定义反序列化逻辑
func (r *Resource) UnmarshalJSON(b []byte) error {
// 定义两个匿名结构体，分别匹配 data 为数组或对象的情形
var (
asSlice struct {
Data []ResourceData `json:"data"`
}
asObject struct {
Data ResourceData `json:"data"`
}
)
// 首先尝试按数组解析
if err := json.Unmarshal(b, &asSlice); err == nil {
r.Data = asSlice.Data
return nil
}
// 若失败且错误类型为 *json.UnmarshalTypeError，说明可能是对象格式
// （其他错误如语法错误应直接返回）
if err := json.Unmarshal(b, &asObject); err == nil {
r.Data = []ResourceData{asObject.Data}
return nil
}
// 两种方式均失败，返回原始错误（保留原始上下文）
return fmt.Errorf("failed to unmarshal 'data' as either array or object: %w",
json.Unmarshal(b, &struct{ Data json.RawMessage }{}))
}
// 示例用法
func main() {
// 场景1：data 是数组
body1 := `{"data":[{"id":"1","type":"user","attributes":{"name":"Alice"}}]}`
var res1 Resource
if err := json.Unmarshal([]byte(body1), &res1); err != nil {
log.Fatal("body1:", err)
}
fmt.Printf("Array case → %d items\n", len(res1.Data)) // 输出：1 items
// 场景2：data 是单个对象
body2 := `{"data":{"id":"2","type":"post","attributes":{"title":"Hello"}}}`
var res2 Resource
if err := json.Unmarshal([]byte(body2), &res2); err != nil {
log.Fatal("body2:", err)
}
fmt.Printf("Object case → %d items\n", len(res2.Data)) // 输出：1 items
}
✅ 关键优势说明：
- 零侵入性：外部调用仍使用标准 json.Unmarshal，无需修改业务代码；
- 统一接口：Resource.Data 始终为 []ResourceData，所有方法（如遍历、过滤、关联处理）可复用；
- 嵌套兼容：ResourceData.Relationships 中的每个 Resource 同样可实现相同 UnmarshalJSON，形成递归适配能力；
- 错误友好：仅在真正无法解析时才返回错误，且保留原始 JSON 上下文便于调试；
- 性能可控：仅做两次轻量级解析（利用 json.RawMessage 可进一步优化为单次预检，但本方案已足够清晰高效）。
⚠️ 注意事项：
- 避免在 UnmarshalJSON 中进行复杂计算或 I/O；
- 若 ResourceData 自身也含动态 data 字段（如 Relationships 中嵌套），需为其 Relationships 的值类型（即 Resource）同样实现 UnmarshalJSON；
- 生产环境建议添加日志或指标监控异常解析频率，及时发现上游 API 行为变更。
通过该模式，你将获得一个语义清晰、易于测试、长期可维护的 JSON 兼容层——让 Go 的强类型特性服务于灵活性，而非成为障碍。
