Go 中处理 JSON 数组与单对象动态兼容的 Unmarshal 方法

在实际的 Go 开发中，特别是处理外部 API 的时候，有一个问题特别磨人：同一个 JSON 字段，有时候是个对象，有时候又变成数组了。这篇文章就来聊聊，怎么在 Go 里把这事儿处理得漂亮——不用写重复代码，不用搞反射，也不用预先判断结构，核心就是通过自定义的 json.Unmarshaler 接口，让类型自己学会“智能适配”。

在 Go 的 JSON 处理实践中，API 响应不一致绝对算得上最常见、也最让人头疼的坑之一。比方说，同一个 `data` 字段，这次返回的是 `{"data": {...}}`，下次就成了 `{"data": [{...}, {...}]}`。如果你直接用固定结构体去接，比如 `[]ResourceData`，单对象的时候就会直接抛出一个 `json.UnmarshalTypeError`。那怎么办？为每种情况都定义一套独立的类型？这显然违背了 DRY 原则，而且一旦遇到嵌套字段，比如 `relationships` 里也这样动态变化，问题就会指数级地复杂化。

说到底，最简洁、也最可维护的解法，其实就在眼前：实现 json.Unmarshaler 接口。让 `Resource` 这个类型自己去判断、去适配输入的格式。核心逻辑其实不复杂：先试着按数组去解码，如果失败了，就回退到单对象解码。最后，不管哪种情况，都统一归一化成一个切片——这样一来，后续所有业务逻辑都不用操心格式问题，直接操作 `r.Data` 就行了，它始终是 `[]ResourceData` 类型。

来看看具体的实现：

package main

import (
    "encoding/json"
    "log"
)

type Resource struct {
    Data []ResourceData `json:"data"`
}

type ResourceData struct {
    ID          string                 `json:"id"`
    Type        string                 `json:"type"`
    Attributes  map[string]interface{} `json:"attributes"`
    Relationships map[string]Resource  `json:"relationships"`
}

// UnmarshalJSON 实现 json.Unmarshaler 接口
func (r *Resource) UnmarshalJSON(b []byte) error {
    // 定义匿名结构体，分别尝试解析为 slice 和 struct
    var temp struct {
        DataSlice struct {
            Data []ResourceData `json:"data"`
        }
        DataStruct struct {
            Data ResourceData `json:"data"`
        }
    }

    // 优先尝试解析为数组
    if err := json.Unmarshal(b, &temp.DataSlice); err == nil {
        r.Data = temp.DataSlice.Data
        return nil
    }

    // 若因类型不匹配失败（如实际是 object），再尝试解析为单对象
    if err := json.Unmarshal(b, &temp.DataStruct); err == nil {
        r.Data = append(r.Data, temp.DataStruct.Data)
        return nil
    }

    // 其他错误（如语法错误、字段缺失等）直接返回
    return json.Unmarshal(b, &temp.DataSlice) // 复用原始错误信息
}

这个方案有几个关键优势值得拎出来说说：

• 零侵入业务逻辑：调用方该怎么写还是怎么写，`json.Unmarshal(body, &r)` 一行搞定，上层代码完全不需要改动。
• 嵌套兼容性：注意看 `ResourceData.Relationships` 里的 `Resource` 类型，它也实现了同样的逻辑。这意味着，嵌套层级的动态多态性，天然就支持了——比如 `relationships.foo.data` 照样可以一会儿是单对象，一会儿是数组。
• 错误友好：非类型错误，比如 JSON 格式本身有问题，还是会原样透传出来，方便调试。只有针对 `*json.UnmarshalTypeError` 这类错误，才会静默地走回退逻辑。
• 性能可控：整个方案只做两次轻量级的解码尝试，完全依赖 Go 标准库高效的 `json` 包，比用 `map[string]interface{}` 加反射去深度遍历，不知道要清爽多少。

最后，有几个细节值得多留个心眼：

• 不要在 `UnmarshalJSON` 里干耗时的事情，比如发网络请求或者读写文件。保持它的职责单一，纯粹做数据转换。
• 如果 `data` 字段有可能返回 `null`，那就要在解码前显式检查一下。可以用 `bytes.HasPrefix(b, []byte("null"))` 来判断，否则 `json.Unmarshal` 会把 `nil` 赋给切片，导致 `r.Data == nil`，后续操作 `len(r.Data)` 的时候就会出问题。
• 单对象转切片的时候，用 `append(r.Data, ...)` 而不是 `r.Data = []ResourceData{...}`。这样做能保证空切片的初始化正确，符合零值安全的原则。

这一套模式，既能守住 Go 语言类型安全的底线，又能灵活应对现实世界中那些“不太讲究”的 API 设计。对于构建健壮的 JSON 客户端来说，这确实是一个值得推荐的做法。