Go json.InvalidUnmarshalError 为什么必须传非空指针

在 Go 里，json.Unmarshal 的第二个参数不是“准备接收结果的任意变量”，而是一个必须可写的非空指针。把结构体值直接传进去，或者把 nil 传进去，返回的就是 *json.InvalidUnmarshalError；这和 JSON 格式写错、字段类型不匹配是三类不同问题。

修复的核心只有一句话：传入 &目标变量，不要传目标变量本身；如果目标本身是指针，还要先确认外层指针不是 nil。

Unmarshal 为什么需要非空指针

Unmarshal(data, v) 要把解析结果写回调用方。结构体值传入后，函数拿到的只是副本；即使内部修改成功，调用方也看不到结果。因此标准库要求 v 是非 nil 指针，才能沿着指针写入原变量。

package main

import (
    "encoding/json"
    "fmt"
)

type User struct {
    Name string `json:"name"`
}

func main() {
    data := []byte(`{"name":"Lin"}`)
    var user User

    // 错误：传入值的副本，Unmarshal 无法把结果写回 user。
    err := json.Unmarshal(data, user)
    fmt.Println(err)

    // 正确：传入 user 的地址，解析结果可以写回原变量。
    err = json.Unmarshal(data, &user)
    fmt.Println(err, user.Name)
}

这里的错误发生在目标参数检查阶段，甚至还没有进入字段映射。换一份 JSON 文本不会解决它，应该先检查调用点是否漏写了 &。

值、nil 和指针的区别

最容易混淆的是“指针类型”和“指针值”。下面几种写法的含义不同：

最后一行与倒数第二行只差一个 &：p 是 nil，不能写；&p 是指向指针变量的非空指针，可以让解码过程更新 p。如果输入是 JSON null，指针字段还可能被设置回 nil，这是内容语义，不等同于目标参数非法。

怎样识别 InvalidUnmarshalError

不要用字符串比较错误信息。标准库返回的是带有 Type 信息的错误类型，可以使用 errors.As 做类型判断：

var targetErr *json.InvalidUnmarshalError
if err := json.Unmarshal(data, target); err != nil {
    // 用 errors.As 识别目标参数形态错误，不依赖错误文本。
    if errors.As(err, &targetErr) {
        fmt.Printf("目标参数类型无效：%v\n", targetErr.Type)
        return
    }

    // 其他错误再分别处理 JSON 语法或字段类型问题。
    var syntaxErr *json.SyntaxError
    var typeErr *json.UnmarshalTypeError
    switch {
    case errors.As(err, &syntaxErr):
        fmt.Println("JSON 语法错误")
    case errors.As(err, &typeErr):
        fmt.Println("字段类型不匹配：", typeErr.Field)
    default:
        fmt.Println("其他解码错误：", err)
    }
}

示例中的 target 应替换成实际的解码目标，并补上 errors 与 fmt 导入。InvalidUnmarshalError 说明调用参数本身不符合契约；SyntaxError 说明输入文本无法按 JSON 语法解析；UnmarshalTypeError 则说明输入值和目标字段类型不匹配。

发布前的四项排查清单

1. 确认第二个参数是 &变量、可写的指针，或是指向指针变量的外层指针。
2. 如果目标来自函数参数，检查它是否可能是 nil；必要时在调用前初始化。
3. 用 errors.As 判断错误类型，不要根据“invalid character”之类文本猜测。
4. 参数错误修好后，再检查 JSON 语法、字段标签和字段类型，避免把不同故障混在一起。

相关问题

为什么传入结构体指针后字段仍为空？ 继续检查 JSON 字段名、大小写、json 标签以及输入是否为 null；这已经不是 InvalidUnmarshalError 的问题。

nil 指针一定不能解码吗？ 作为第二个参数直接传入的 nil 指针不能解码；传入它的地址，例如 &p，则给了解码器一个可写的外层目标，行为不同。