Go jsonunmarshal 怎么处理解码类型

日常写Go代码调用`json.Unmarshal`解析JSON数据的时候，经常会遇到解码类型不符合预期、类型不匹配报错的情况，我们可以通过调整接收结构体、自定义解码方法、适配动态类型等方式处理这类问题。

Go 里常说的“jsonunmarshal 解码类型”，实际入口是标准库 encoding/json.Unmarshal。处理这类问题的关键不是把所有输入先读成 map[string]any，而是先确定目标字段类型：普通字段交给默认规则，格式特殊的字段实现 UnmarshalJSON([]byte) error。如果自定义方法里直接再次解码原类型，还会递归调用自己。

你可以优先用指定结构体字段绑定的方式声明接收类型，特殊场景下再用json.Number、自定义UnmarshalJSON方法或者map[string]interface{}做动态适配，不要硬转类型忽略错误。

先确认 json.Unmarshal 进入了哪个类型

标准库会把 JSON 对象映射到结构体，把数组映射到切片或数组，把 JSON 数字映射到目标数字类型。第二个参数如果不是指针，或者传入 nil，入口就无法把结果写回去。字段名默认按名称匹配，也可以用标签固定外部字段名。

package main

import (
    "encoding/json"
    "fmt"
)

type Order struct {
    ID    int      `json:"id"`
    Price float64  `json:"price"`
    Tags  []string `json:"tags"`
}

func main() {
    raw := []byte(`{"id": 17, "price": 8.5, "tags": ["go", "json"]}`)
    var order Order
    // 传入 &order，Unmarshal 才能把解码结果写回结构体。
    if err := json.Unmarshal(raw, &order); err != nil {
        // 入口错误先返回，避免继续使用不完整对象。
        panic(err)
    }
    fmt.Println(order.ID, order.Price, order.Tags)
}

如果把 price 写成 JSON 字符串，而目标仍是 float64，默认解码不会替你猜测转换规则。这时要么修正输入契约，要么把“数字或字符串”定义成一个有明确行为的自定义类型。

用 UnmarshalJSON 处理不稳定的字段格式

自定义类型的典型做法是先保留原始 JSON，再根据首字符或候选类型尝试转换。下面的 FlexibleInt 同时接受 JSON 数字和 JSON 字符串，但最终只保存一个 int64，业务层不需要到处判断输入形态。

type FlexibleInt int64

func (v *FlexibleInt) UnmarshalJSON(data []byte) error {
    var number int64
    // 先按数字读取，成功时不改变字符串分支的语义。
    if err := json.Unmarshal(data, &number); err == nil {
        *v = FlexibleInt(number)
        return nil
    }

    var text string
    // 再接受带引号的数字，并把转换失败原样返回给调用方。
    if err := json.Unmarshal(data, &text); err != nil {
        return fmt.Errorf("FlexibleInt expects number or string: %w", err)
    }
    parsed, err := strconv.ParseInt(text, 10, 64)
    if err != nil {
        return fmt.Errorf("invalid FlexibleInt %q: %w", text, err)
    }
    *v = FlexibleInt(parsed)
    return nil
}

方法使用指针接收者，因为解码需要修改目标值。对于时间、枚举或带单位的字符串，也可以采用相同入口，但应在方法内部明确空值、范围和格式，而不是吞掉错误。

用别名类型切断自定义解码递归

为结构体实现 UnmarshalJSON 后，直接写 json.Unmarshal(data, v) 会再次找到同一个方法，形成递归。解决办法是声明一个底层结构相同但没有方法集的辅助类型，再把特殊字段单独取出。

type Payload struct {
    ID    int         `json:"id"`
    Count FlexibleInt `json:"count"`
    Meta  json.RawMessage `json:"meta"`
}

func (p *Payload) UnmarshalJSON(data []byte) error {
    type payloadAlias Payload
    var aux payloadAlias
    // 别名没有 Payload 的方法集，解码普通字段不会再次进入本方法。
    if err := json.Unmarshal(data, &aux); err != nil {
        return err
    }
    *p = Payload(aux)
    return nil
}

这里的 FlexibleInt 仍会按自己的规则解码，Meta 则保留原始片段供后续分支处理。若要拒绝拼写错误的字段，可改用 json.Decoder 并调用 DisallowUnknownFields；这属于接口严格程度的选择，不是所有兼容接口都适合开启。

把“解码类型错误”定位到具体字段

排错时不要只打印 err.Error()。JSON 语法坏了通常是 *json.SyntaxError；值和目标类型不匹配时通常是 *json.UnmarshalTypeError，其中 Field 能帮助你定位嵌套字段。自定义方法返回的解析错误则应保留上下文。

var typeErr *json.UnmarshalTypeError
if errors.As(err, &typeErr) {
    // Field 给出结构体路径，便于把错误关联到输入字段。
    log.Printf("field=%s want=%s got=%s", typeErr.Field, typeErr.Type, typeErr.Value)
}

var syntaxErr *json.SyntaxError
if errors.As(err, &syntaxErr) {
    // Offset 表示语法错误附近的字节位置，不等同于业务字段名。
    log.Printf("invalid JSON near byte %d", syntaxErr.Offset)
}

最后检查三件事：目标是否为非 nil 指针；自定义方法是否处理了 null 和错误返回；接口是否真的需要拒绝未知字段。这样“解码类型不对”就能落到输入、目标类型或自定义转换中的一个边界上。

相关问题

为什么 Unmarshal 后结构体字段还是零值？

先看传入的是否是指针、字段是否导出、标签是否写对；未匹配的对象键默认会被忽略。

UnmarshalJSON 为什么会无限递归？

通常是方法内部再次把原类型作为目标。使用不带方法集的别名类型承接默认解码即可。

数字和字符串都要兼容，应该用 map[string]any 吗？

不必。为不稳定字段定义小型自定义类型，转换规则集中在一个方法里，结构体其余字段仍保持静态类型。