Go json/v2 开启严格 UTF-8 后旧数据为什么解码失败

我第一次把旧 JSON 数据切到 encoding/json/v2 时，最容易误判的是：结构体没有变，字段名也没有变，为什么同一条记录突然解码失败？真正的原因往往不在 Go 类型，而在 JSON 字符串里混进了非法 UTF-8 字节。v1 会把这类字节替换成 Unicode 替换字符，v2 默认直接拒绝，所以过去被悄悄“修正”的数据会在新入口暴露出来。

官方地址：https://pkg.go.dev/encoding/json/v2

这类问题适合采用“严格入口 + 有标记的兼容入口 + 可追溯迁移”的模式：新数据坚持严格 UTF-8，历史数据先隔离并记录转换代价，不能把 jsontext.AllowInvalidUTF8(true) 当成无损修复开关。

先确认失败发生在 JSON 字符串的 UTF-8 边界

当前官方文档把 v2 的默认行为定义得很清楚：JSON 字符串中的非法 UTF-8 会导致解码失败；jsontext.AllowInvalidUTF8(true) 可以改变这个默认值，但非法字节会被替换为 U+FFFD。Go 1.27 已将 encoding/json/v2 和 encoding/json/jsontext 作为标准库包提供，因此迁移时应先检查运行时版本和实际使用的包路径。

可以用一段最小输入来理解边界。下面的 0xff 只是在内存中模拟历史记录里的坏字节，示例不代表某个具体数据库或接口的真实输出。

package main

import (
    "fmt"

    "encoding/json/v2"
)

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

func main() {
    // 用非法字节模拟旧系统写入 JSON 字符串的历史记录。
    raw := []byte{'{', '"', 'n', 'a', 'm', 'e', '"', ':', '"', 'A', 0xff, 'B', '"', '}'}

    var record Record
    // v2 默认检查 JSON 字符串的 UTF-8，不会静默吞掉坏字节。
    if err := json.Unmarshal(raw, &record); err != nil {
        fmt.Printf("decode failed: %v\n", err)
        return
    }
    fmt.Println(record.Name)
}

如果把同样的错误看成“字段不存在”或“类型不匹配”，后面的排查方向就会完全走偏。先判断原始字节是否符合 UTF-8，再检查字段结构；这两个问题应分别记录。

兼容读取可以止血，但它不是迁移完成

如果旧数据必须先读出来，v2 提供了显式的兼容入口。它的价值是让历史数据处理有一个清楚的边界，而不是让整个应用重新回到宽松默认。调用方应该把这条路径限制在回放、导入或迁移任务中，并把使用原因写进日志或迁移记录。

package main

import (
    "fmt"

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

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

func decodeLegacy(raw []byte) (LegacyRecord, error) {
    var record LegacyRecord
    // 兼容选项允许旧输入通过，但非法字节会变成 U+FFFD。
    err := json.Unmarshal(raw, &record, jsontext.AllowInvalidUTF8(true))
    return record, err
}

func main() {
    // 迁移程序应检查错误，并把替换过的记录单独计数。
    record, err := decodeLegacy([]byte(`{"name":"legacy"}`))
    if err != nil {
        fmt.Printf("legacy decode failed: %v\n", err)
        return
    }
    fmt.Println(record.Name)
}

这里最重要的不是“能解码”，而是知道发生了有损变化。U+FFFD 只表示某段字节无法按 UTF-8 解释，并不能恢复原始字符；如果旧系统实际使用的是某种已知编码，应先在明确的输入边界完成编码转换，再交给严格 JSON 解码器。

为旧记录建立可追溯的转换策略

我在迁移脚本里会把原始记录标识、来源、原始字节的保存位置和转换结果分开记录。这样即使选择替换，也能回答“哪条记录被替换过、替换了几次、是否可以回放”。对于已经确认是普通 Go 字符串、且只需要清理非法 UTF-8 的场景，可以使用标准库的 strings.ToValidUTF8；但它同样是替换策略，不是还原策略。

package migration

import "strings"

func normalizeText(input string) (string, bool) {
    // 用明确的替换符标记不可解释的字节，返回值表示是否发生替换。
    normalized := strings.ToValidUTF8(input, "�")
    return normalized, normalized != input
}

旧数据通常可以分成三类：能证明原编码的记录，按原编码转换后再严格解码；只知道含有坏字节、但无法还原的记录，采用替换并标记有损；连 JSON 结构都不完整的记录，保留原文和标识，进入人工或专门修复队列。不要把三类记录混在同一个成功计数里。

上线前用清单收敛错误边界

• 新写入路径使用严格 UTF-8，并在边界处拒绝不合规输入。
• 兼容选项只出现在迁移或回放入口，不作为全局默认。
• 失败记录保留 ID、来源和原始字节线索，成功数与有损替换数分开统计。
• 对已知旧编码先做有依据的转换，对未知来源不要猜编码。
• 迁移后的 JSON 再走严格解码，确保后续链路不会继续积累坏数据。

可以把这个问题概括成一句话：v2 不是无缘无故“变严格”，而是把 v1 曾经用 U+FFFD 掩盖的数据问题显式暴露出来。把兼容入口限定在历史数据处理，把规范入口留给新数据，迁移才既能推进，又不会让有损结果悄悄回到生产链路。

相关问题

AllowInvalidUTF8 会保留原始非法字节吗？

不会。官方文档说明它会把非法 UTF-8 替换成 U+FFFD，因此需要保留原始数据或原始记录线索时，不能只依赖解码后的 Go 值。

为什么旧版 encoding/json 没报错？

v1 默认会把 JSON 字符串中的非法 UTF-8 替换成 Unicode 替换字符，所以应用可能一直在使用已经改变过的字符串。

能不能直接对整段 JSON 调用 ToValidUTF8？

不建议把它当成通用修复。整段输入可能同时包含 JSON 结构、字符串和转义边界；更稳妥的做法是先确认来源编码，或在受控兼容入口读取后对具体字段制定转换规则。