Go 判断 JSON 合法却仍解码失败怎么办

遇到“JSON 明明合法，Go 还是解码失败”，先不要继续修改 JSON 文本。json.Valid 只回答“这段字节是不是合法 JSON”，而 json.Unmarshal 还要检查目标参数是不是可写指针、字段类型能不能接收，以及自定义解码逻辑是否返回错误。排查时把这三层分开，通常很快就能定位。

先把 JSON 合法性和目标类型分开

下面这段数据在语法上是合法的，但 count 是字符串。如果结构体把它声明为 int，解码阶段仍会返回类型错误：

package main

import (
    "encoding/json"
    "fmt"
)

type Payload struct {
    Count int `json:"count"`
}

func main() {
    data := []byte(`{"count":"12"}`)
    fmt.Println(json.Valid(data)) // 只检查 JSON 语法，结果为 true

    var dst Payload
    err := json.Unmarshal(data, &dst) // 目标字段类型仍需匹配
    fmt.Printf("value=%+v, err=%v\n", dst, err)
}

Valid 通过只说明括号、引号、逗号和字面量符合 JSON 编码；它不会替你检查业务字段的类型、必填关系或取值范围。若输入来自 HTTP 请求，还要确认传入的是完整请求体，而不是已经被截断、拼接或重复读取后的空字节。

按错误类型定位解码失败

不要只打印 err.Error()。标准库提供了可判断的错误类型，先分类再处理会比字符串匹配稳定：

var dst Payload
err := json.Unmarshal(data, &dst)
if err != nil {
    var typeErr *json.UnmarshalTypeError
    var syntaxErr *json.SyntaxError
    switch {
    case errors.As(err, &typeErr):
        // Value、Type 和 Field 可帮助定位字段类型不匹配
        fmt.Printf("字段=%s，输入=%s，目标=%s，偏移=%d\n", typeErr.Field, typeErr.Value, typeErr.Type, typeErr.Offset)
    case errors.As(err, &syntaxErr):
        // Offset 表示语法错误附近的字节位置
        fmt.Printf("JSON 语法错误，偏移=%d\n", syntaxErr.Offset)
    default:
        // 还要覆盖目标参数非法或自定义 UnmarshalJSON 返回的错误
        fmt.Printf("其他解码错误：%v\n", err)
    }
}

如果错误是 json: Unmarshal(non-pointer ...)，检查是否误传了结构体值而不是指针；如果是 cannot unmarshal string into Go struct field ... of type int，修复输入契约或调整字段类型，不要用 json.Valid 掩盖问题。需要保留多态字段时，可以先把字段声明为 json.RawMessage，等识别类型后再进行第二次解码。

用 RawMessage 和严格字段策略收敛边界

当接口允许一个字段出现多种形态时，RawMessage 能把“整体 JSON 合法”与“分支结构是否匹配”拆开。它适合记录原始片段、延迟判断，或针对不同版本选择不同结构体。

type Envelope struct {
    Kind string          `json:"kind"`
    Data json.RawMessage `json:"data"`
}

// DisallowUnknownFields 让拼写错误的字段尽早暴露，而不是静默丢弃。
decoder := json.NewDecoder(bytes.NewReader(data))
decoder.DisallowUnknownFields()
var env Envelope
if err := decoder.Decode(&env); err != nil {
    // 记录请求编号和错误类型，但不要把完整敏感请求体写入日志
    return fmt.Errorf("decode envelope: %w", err)
}

这类严格策略要和接口兼容性一起评估：新增字段的上游如果本来就允许扩展，直接拒绝未知字段可能造成旧客户端不兼容。比较稳妥的做法是先在灰度环境开启，确认调用方字段集合后再收紧。

常见问题

json.Valid 为 true，为什么 Unmarshal 仍然报错？

因为前者只检查 JSON 编码，后者还要把值写入目标 Go 类型；字段类型、目标参数或自定义解码逻辑都可能失败。

把结构体传给 Unmarshal 可以吗？

不可以。目标通常必须是可写指针，例如 json.Unmarshal(data, &dst)；传值会得到 InvalidUnmarshalError。

应该把所有字段都改成 interface{} 吗？

不建议。这样会失去类型约束和早期错误提示，只有确实存在多态数据时才对局部字段使用 RawMessage 或受控接口。

官方文档：https://pkg.go.dev/encoding/json