如何优雅处理 JSON 中同一字段时而为对象、时而为数组的 Go 解析难题

如何优雅处理 JSON 中同一字段时而为对象、时而为数组的 Go 解析难题

在调用不规范 REST API 时，常遇到同一 JSON 字段（如 “line”）在不同响应中动态表现为单个对象或对象数组，导致标准结构体反序列化失败；本文介绍通过 json.RawMessage + 类型断言或自定义 UnmarshalJSON 实现稳健、零冗余的兼容解析方案。

对接第三方服务时，最让人头疼的情况之一，莫过于接口返回的 JSON 结构“飘忽不定”。同一个字段，比如 net.comment.line，这次返回一个对象，下次可能就变成了一个数组。这种不一致性，对于 Go 这种强类型语言来说，简直就是编译器的噩梦——json.Unmarshal 会直接抛出错误：json: cannot unmarshal object/array into Go struct field ...。

面对这种局面，常见的应对策略往往各有短板。硬着头皮定义两套结构体分别解析？代码立刻变得冗余且难以维护。退而求其次，使用 map[string]interface{} 来接收？虽然绕过了类型检查，但代价是彻底丧失了编译期的安全保障和清晰的字段语义，后续还得写一大堆运行时类型断言，得不偿失。

推荐方案：使用 json.RawMessage 延迟解析 + 自定义反序列化逻辑

有没有一种方法，既能保持类型安全，又能灵活应对这种“类型摇摆”呢？答案是肯定的，核心就在于 json.RawMessage。这个标准库提供的工具，本质上是一个零拷贝的字节容器，它能把原始的 JSON 片段原封不动地暂存为 []byte，将解析的主动权推迟到我们手中，让我们有机会在运行时根据实际情况“见招拆招”。

来看一个具体的实现方案：

type Line struct {
    Text   string `json:"$"`
    Number string `json:"@number"`
}
type Comment struct {
    Line json.RawMessage `json:"line"`
}
type Net struct {
    Comment Comment `json:"comment"`
}

// 自定义 UnmarshalJSON 实现类型自适应
func (c *Comment) UnmarshalJSON(data []byte) error {
    // 先尝试解析为单个对象
    var single Line
    if err := json.Unmarshal(data, &single); err == nil {
        // 成功：包装为长度为 1 的切片
        bytes, _ := json.Marshal([]Line{single})
        c.Line = bytes
        return nil
    }
    // 失败则尝试解析为数组
    var arr []Line
    if err := json.Unmarshal(data, &arr); err == nil {
        bytes, _ := json.Marshal(arr)
        c.Line = bytes
        return nil
    }
    return fmt.Errorf("cannot unmarshal 'line' as object or array of objects")
}

这套逻辑的精髓在于其“尝试-回退”的策略。在自定义的 UnmarshalJSON 方法里，我们首先假设字段是单个对象进行解析。如果成功了，就把它封装成一个只有一个元素的数组，再序列化成 json.RawMessage 存回去。如果失败了，就退一步，尝试将其作为数组来解析。无论哪种情况成功，最终存入结构体的都是一个表示 []Line 的 JSON 字节流。

使用起来就非常直观了：

var resp struct {
    Net Net `json:"net"`
}
if err := json.Unmarshal(rawJSON, &resp); err != nil {
    log.Fatal(err)
}

// 安全提取所有 line 文本（无论原始是对象还是数组）
var lines []Line
if err := json.Unmarshal(resp.Net.Comment.Line, &lines); err != nil {
    log.Fatal(err)
}
for _, l := range lines {
    fmt.Printf("Line %s: %s\n", l.Number, l.Text)
}

这样一来，业务逻辑层拿到的永远是一个清晰的 []Line 切片，可以完全无视底层 API 的“任性”行为，专注于数据处理本身。

关键优势与注意事项

✅ 类型安全：这是最大的优点。最终操作的是明确定义的 []Line 类型，IDE 的自动补全和编译器的类型检查全程在线，避免了运行时 panic 的风险。
✅ 零冗余：无需为同一份数据维护多个版本的结构体定义，所有兼容性逻辑都封装在 UnmarshalJSON 这一个方法里，干净利落。
✅ 可扩展：这个模式具有很强的扩展性。如果未来接口还可能返回 null 或者字符串等形式，只需在自定义解析方法中增加相应的尝试分支即可。
⚠️ 性能提示：json.RawMessage 本身避免了使用 interface{} 带来的反射开销，但方案内部进行了两次 json.Marshal/Unmarshal，会带来轻微的内存复制。对于超高频调用的核心路径，可以考虑复用 bytes.Buffer 或预分配切片来优化。
⚠️ 错误处理：生产环境中，建议在返回的错误信息中包裹更具体的上下文，例如使用 fmt.Errorf(“line: %w”, err)，这样在日志中能快速定位是哪条响应、哪个字段出了问题。

总而言之，面对不规范的、类型动态变化的 JSON API，被动适配往往事倍功半。更好的策略是主动掌控解析流程。json.RawMessage 配合自定义的 UnmarshalJSON 方法，正是 Go 语言哲学下一种兼具健壮性、可读性和类型安全的工业级解决方案。它让混乱的输入变得有序，让不确定的类型重归确定，这才是工程化处理该有的样子。