Go encoding/json 切换到 v2 后字符串 tag 行为变化怎么办

切换到 encoding/json/v2 后，先检查带 ,string 的字段是不是数字。Go 1.27 的 v2 默认不把这个标签当作任意类型的“加引号”开关：普通 string、bool 以及集合字段不能照搬旧写法。若接口必须保持旧协议，可以先保留 encoding/json 的兼容入口，再逐个迁移字段，不能只替换 import。

Go 官方地址：https://go.dev/。我更倾向于先保住调用方协议，再改内部编码方式；这是一种迁移取舍，不是一次线上事故复盘。本文示例未执行，表中的内容是依据文档给出的协议预期，不是运行日志。

先确认改的是工具链，还是 JSON API

Go 1.27 已提供 encoding/json/v2 和 encoding/json/jsontext。原有 encoding/json 的底层使用了新实现，但保留 v1 的编解码行为；继续导入旧包，不等于采用 v2 默认语义。显式改用新包，才需要按新约定重新整理标签。

这个区分能减少不必要的改动：升级 Go 与升级业务线上的 JSON 协议可以拆开做。旧 API 继续受支持，没有要求把所有请求对象同时迁移。遇到错误时，记录所用包路径和选项，比只记录“升级了 Go”更有用。

把 string 标签差异压缩到字段类型

v2 的字段标签只约束该字段顶层值，不能给数组或对象套上标签来修改内部元素。调用级的 StringifyNumbers 选项则递归作用，影响范围不同；若只想改变一个标识字段，不应贸然把全请求的数字策略一起改掉。

我会先问：旧调用方到底发送了什么

迁移中最不适应的地方，往往不是编译错误，而是 Go 字段名没变、线上 JSON 类型却变了。普通文本直接使用 string 即可自然编码为 JSON 字符串，不需要额外的 ,string。如果旧客户端发送的是“字符串里面又包一层 JSON 字符串”，直接删除标签就会改变双方约定。

bool 也一样。接口需要真正的 true/false 时使用 bool；接口明确要求文本时，考虑独立的传输 DTO，以 string 字段表达并显式解析。不要为了让现有对象编码成功，顺手把协议从字符串改为布尔值，再要求所有调用方自行适应。

这里我看重的是分离：内部业务类型不必与历史传输类型完全一致。兼容层会多一点转换代码，但比在多个调用点分散使用选项更容易说明影响范围。

新写法只给数字标识保留标签

下面的 Submit 假设新协议明确规定：record_id 是数字文本，title 是普通文本，enabled 是 JSON 布尔值。它不是兼容所有旧请求的通用对象，而是这个协议的最小表达。

package payload

import (
    "fmt"
    jsonv2 "encoding/json/v2"
)

// Submit 将数字标识保留为 JSON 字符串，普通文本和布尔值保持原类型。
type Submit struct {
    RecordID int64  `json:"record_id,string"`
    Title    string `json:"title"`
    Enabled  bool   `json:"enabled"`
}

// Encode 不把编码失败的部分数据作为有效请求返回。
func Encode(v Submit) ([]byte, error) {
    data, err := jsonv2.Marshal(v)
    if err != nil {
        return nil, fmt.Errorf("编码提交内容失败: %w", err)
    }
    return data, nil
}

// Decode 使用临时对象，失败时不返回可能已经部分填充的字段。
func Decode(data []byte) (Submit, error) {
    var value Submit
    if err := jsonv2.Unmarshal(data, &value); err != nil {
        return Submit{}, fmt.Errorf("解析提交内容失败: %w", err)
    }
    return value, nil
}

例如 RecordID 为 83、Title 为“日报”、Enabled 为 true 时，语义预期是 record_id 对应字符串“83”，title 对应字符串“日报”，enabled 对应布尔值 true；不依赖对象成员输出顺序。Decode 失败就返回错误，调用方不应继续消费零值对象。

若短期必须保留旧式 string/bool 标签行为，可评估旧包提供的 StringifyWithLegacySemantics 选项，并在单一边界使用。它只处理相关语义，不代表一次性恢复全部 v1 行为；范围更大的保守选择是继续使用旧 API。代码评审时应把“暂时兼容哪些旧字段”写清楚。

回归样本应该围绕协议，不围绕错误字符串

迁移前可为调用方准备一组固定样本：数字文本“83”、原生数字 83、带空白的数字文本、普通文本、布尔值、缺失字段和 null。对每项先写明接受还是拒绝，再比对业务需要；缺失和 null 不应因为读起来都像“没有值”而合并处理。这里列的是读者项目中的回归建议，本文不执行这些测试。

还应放入业务实际使用的数字边界值，确认类型能表达目标范围；若字段实际使用自定义编解码方法，也应单独列入样本，不能只根据底层 Go 类型推测线上的表示。不要把精确错误文案当作稳定协议，错误处理应围绕是否成功及应用自己的错误分类。

迁移清单与我的取舍

• 列出显式使用 v2 的请求和响应边界，不把工具链升级当成全量 API 迁移。
• 逐个说明 ,string 字段在线上必须呈现的 JSON 类型。
• 数字标识按需要保留标签，文本与布尔字段按真实协议改写。
• 临时兼容配置集中在边界，并注明移除条件，不默认扩散到全部序列化调用。
• 为旧客户端保留明确的过渡路线，避免一次改动同时调整字段名、字段类型和错误处理。

普通 string 字段为什么不需要 ,string？

它本来就会编码为 JSON 字符串。额外的标签不是声明“这是字符串类型”，迁移时应区分普通文本与历史上的二次编码协议。

给 []int 加标签能把每个数字变字符串吗？

不能把字段级标签理解为递归改写。需要集合内部策略时，应评估专用传输类型或调用级选项的影响范围，而不是机械复用标量字段写法。

对外协议稳定、调用方多的接口，我会优先保留旧入口，等字段预期明确后再迁移。新接口则直接采用 v2，并让结构体标签与线上的 JSON 类型一一对应。真正值得保留的是协议含义，不是历史标签的外观。

参考：Go 1.27 发布说明、JSON v2 字段标签与选项、旧字符串语义兼容选项。