Go encoding/json/v2 无效 UTF-8 解码失败怎么处理

我第一次把一批旧 JSON 数据切到 encoding/json/v2 时，最容易误判的不是结构字段，而是某个字符串里混进了不完整的 UTF-8 字节。这个包默认会拒绝这类输入，所以解码失败其实是在提醒数据不符合 JSON 的 UTF-8 要求，并不是结构体字段写错了。

官方地址：https://go.dev/doc/go1.27

如果原始字节必须保真，就继续使用默认严格模式并修复上游；如果业务明确接受把坏字节替换成 U+FFFD，才在解码调用上显式传入 jsontext.AllowInvalidUTF8(true)。这个选项是兼容策略，不是原始数据恢复。

先把失败输入还原成真实字节

无效 UTF-8 很难靠肉眼在日志里确认，因为日志系统可能已经替换或转义了坏字节。下面的示例直接拼出一个包含 0xff 的 JSON 字符串，重点是观察 encoding/json/v2 的默认行为，而不是把这段代码当作生产数据清洗器。

package main

import (
    "fmt"

    "encoding/json/v2"
)

type Payload struct {
    Message string `json:"message"`
}

func main() {
    // 0xff 不是合法的 UTF-8 起始字节，故意放进 JSON 字符串制造边界输入。
    input := []byte{'{', '"', 'm', 'e', 's', 's', 'a', 'g', 'e', '"', ':', '"', 0xff, '"', '}'}

    var got Payload
    // 默认选项遵循严格 UTF-8 语义，错误应被保留给调用方处理。
    err := json.Unmarshal(input, &got)
    fmt.Printf("strict error type=%T, error=%v\n", err, err)
}

这里的 err 才是应该被记录和分流的结果。不要先把输入转成 Go 字符串再判断，因为那一步可能已经让上游库或日志链路替换了原始字节，排查时就失去了证据。

默认拒绝和显式容错是两种接口语义

encoding/json/v2 的默认解码要求 JSON 字符串使用有效 UTF-8。要接受不完整字节，需要把 jsontext.AllowInvalidUTF8(true) 作为本次调用的选项传入；它同时影响编码和解码，但这里只讨论解码。

package main

import (
    "fmt"

    "encoding/json/jsontext"
    "encoding/json/v2"
)

type Payload struct {
    Message string `json:"message"`
}

func decodeForBoundary(input []byte) (Payload, error) {
    var got Payload
    // 兼容模式允许输入继续进入语义解码，但坏字节会按 U+FFFD 处理。
    err := json.Unmarshal(input, &got, jsontext.AllowInvalidUTF8(true))
    return got, err
}

func main() {
    // 这个输入只用于说明选项语义，不代表已经从某个线上接口读取。
    input := []byte{'{', '"', 'm', 'e', 's', 's', 'a', 'g', 'e', '"', ':', '"', 0xff, '"', '}'}
    got, err := decodeForBoundary(input)
    if err != nil {
        // 兼容策略也必须保留错误分支，不能把所有失败都当成可替换字节。
        fmt.Println("decode failed:", err)
        return
    }
    // 输出中的替换字符说明数据被规范化过，不应再宣称字节级保真。
    fmt.Printf("message=%q\n", got.Message)
}

官方文档对这个选项的描述很关键：坏字节会被替换为 Unicode replacement character，也就是 U+FFFD。换句话说，调用成功只代表“得到了一个可继续处理的 Go 值”，不代表 Message 仍然等于原始字节序列。

我会把容错放在边界层，而不是全局打开

对我来说，最稳妥的做法是把容错选项限制在已经确认“允许信息损失”的入口函数里。内部模型、签名校验、需要回写的数据和审计字段继续使用默认严格模式；只有展示或迁移用的兼容入口才显式传入选项。

func decodeDisplayPayload(input []byte) (Payload, error) {
    var got Payload
    // 这个函数的调用方已接受 U+FFFD 替换，只服务于展示型读取。
    if err := json.Unmarshal(input, &got, jsontext.AllowInvalidUTF8(true)); err != nil {
        return Payload{}, fmt.Errorf("展示数据解码失败: %w", err)
    }
    return got, nil
}

func decodeTrustedPayload(input []byte) (Payload, error) {
    var got Payload
    // 可信数据保持默认严格语义，避免坏字节静默进入核心模型。
    if err := json.Unmarshal(input, &got); err != nil {
        return Payload{}, fmt.Errorf("可信数据解码失败: %w", err)
    }
    return got, nil
}

这两个函数的差异故意很小：真正的决策只有“是否显式传入选项”。这样做的好处是调用方能从函数名和接口边界看出数据语义，后续也容易补充指标，例如统计兼容入口收到替换字符的次数。不要把 AllowInvalidUTF8(true) 隐藏在全局包装器里，否则排查者很难知道数据何时已经被改写。

相关问题

把无效字节替换成 U+FFFD 后还能恢复原文吗？

不能保证。U+FFFD 只表示某段输入无法按合法 UTF-8 解码，多个不同的坏字节序列可能得到相同的替换结果；需要保留原文时，应在解码前保存原始字节并修复上游编码。

只在日志里看到解码失败，应该先改成兼容模式吗？

不建议直接全局放宽。先确认失败输入来自哪个边界、该字段是否允许损失，再决定把兼容选项限制在展示或迁移入口；核心数据仍应让错误显式暴露。

总结

encoding/json/v2 默认拒绝无效 UTF-8，是为了避免把原始数据悄悄改成另一段文本。jsontext.AllowInvalidUTF8(true) 可以处理历史脏数据，但代价是 U+FFFD 替换和字节保真丢失。实际项目里，把它作为局部、可命名的边界策略，通常比全局开启更容易审查和维护。

参考资料：https://go.dev/doc/go1.27；https://pkg.go.dev/encoding/json/v2；https://pkg.go.dev/encoding/json/jsontext