Go JSON 输入字段类型不稳定时怎么自定义 UnmarshalJSON

Go 服务对接第三方接口时，最容易被低估的一类问题是字段类型不稳定：今天的 count 返回 12，另一条记录却返回 "12"。如果结构体直接写成 int64，其中一种输入就会触发 json.UnmarshalTypeError。比较稳妥的做法是只给这个字段定义 UnmarshalJSON，在兼容层把字符串和数字统一成业务类型，其他字段仍交给标准库解析。

不要把整个请求体解码成 map[string]any 再到处断言。为不稳定字段包一层小类型，用 json.RawMessage 保留原始形态，并对无法确认的值返回错误，兼容范围会更清楚。

为什么固定 int 字段接不住两种 JSON 类型

标准库按目标字段的静态类型解码。目标是 int64 时，JSON 数字可以直接进入；JSON 字符串则不是同一类型，解析器会把问题返回给调用方。把所有字段改成 any 虽然能暂时绕开报错，却会把类型判断扩散到业务代码，排序、比较和持久化都要重复处理。

自定义类型的边界更小。例如订单的数量字段可以定义为 FlexibleInt，只有它负责兼容输入；订单结构体仍然保持可读的字段声明。

自定义 UnmarshalJSON 的关键结构

下面这个类型把“输入兼容”隔离在一个位置。先用 json.RawMessage 拿到字段原文，再分别尝试字符串和数字；结构体使用别名类型解码，避免递归调用。

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "strconv"
)

type FlexibleInt int64

func (f *FlexibleInt) UnmarshalJSON(data []byte) error {
    // 先去掉外围空白，保留 null、字符串和数字的原始形态。
    data = bytes.TrimSpace(data)
    if bytes.Equal(data, []byte("null")) {
        *f = 0
        return nil
    }

    var text string
    if len(data) > 0 && data[0] == '"' {
        if err := json.Unmarshal(data, &text); err != nil {
            return fmt.Errorf("数量字符串格式错误: %w", err)
        }
        if text == "" {
            return fmt.Errorf("数量不能为空")
        }
        value, err := strconv.ParseInt(text, 10, 64)
        if err != nil {
            return fmt.Errorf("数量不是整数: %w", err)
        }
        *f = FlexibleInt(value)
        return nil
    }

    var value int64
    if err := json.Unmarshal(data, &value); err != nil {
        return fmt.Errorf("数量必须是整数或数字字符串: %w", err)
    }
    *f = FlexibleInt(value)
    return nil
}

type Order struct {
    ID    string      `json:"id"`
    Count FlexibleInt `json:"count"`
}

func decodeOrder(data []byte) (Order, error) {
    // 别名不带方法集，避免 json.Unmarshal 再次进入 Order.UnmarshalJSON。
    type orderAlias Order
    var dst orderAlias
    if err := json.Unmarshal(data, &dst); err != nil {
        return Order{}, err
    }
    return Order(dst), nil
}

这里的关键不是把错误藏起来，而是把允许的输入集合写在类型里。若接口还可能返回小数、数组或对象，应继续收紧规则并返回错误，不要因为“先让请求成功”就把它们转换成 0。

边界值要明确区分，不要全部吞掉

null 是否置零只是示例策略。若数据库需要区分“未提供”和“明确为 0”，就应把字段改成指针或增加存在性标记；若旧接口把空字符串当成缺省值，也要单独写出规则。错误信息最好带上字段语义，调用方才能定位是上游数据问题还是格式约定不一致。

还有一个容易忽略的点：实现方法的接收者必须是指针，因为解析结果需要写回字段。可以加一条编译期接口检查，防止未来改签名后悄悄失去自定义解析：

var _ json.Unmarshaler = (*FlexibleInt)(nil)

建议至少覆盖四组测试：数字、数字字符串、空字符串或 null、对象或非整数文本。测试的重点不是重复标准库，而是锁定你主动扩展的兼容范围。

落地时的检查清单

• 只为确实不稳定的字段创建兼容类型，别让整个模型变成弱类型。
• 方法签名使用指针接收者，返回值始终是 error。
• 在方法内部使用别名、RawMessage 或临时字段，避免递归。
• 对 null、空字符串、溢出、小数和对象分别决定“接受、拒绝还是保留缺失”。

相关问题

UnmarshalJSON 方法应该定义在结构体还是字段类型上？

字段只有一个不稳定值时，优先定义在字段类型上，影响范围更小；多个字段需要联合校验时，再考虑结构体级方法。

为什么不直接用 json.Number？

json.Number适合保留 JSON 数字的文本表示，但它不会自动接受带引号的字符串和空值。需要跨类型兼容时，仍要有明确的自定义规则。

能不能把解析失败改成 0？

除非协议明确规定，否则不建议。0 可能是有效业务值，吞错会让坏数据继续进入计算和数据库。

自定义 UnmarshalJSON 的价值是把兼容性集中起来，同时保留类型安全。先写清楚允许的 JSON 形态，再决定 null 和空字符串策略，后续接口变更会更容易控制。