Go encoding/json v2 怎样为 JSON v2 自定义字段编码器

Go JSON v2 可以用 MarshalToFunc 定义某个 Go 类型的编码规则，再通过 WithMarshalers 交给一次 Marshal 调用。它不是按字段名注册的编码器：如果只想改变一个字段，先为该字段定义独立类型，通常比注册所有 string 更容易控制影响范围。

我会把“接口要什么表示”和“业务类型原本是什么”分开考虑。例如展示用编号需要大写，而内部编号必须保留原样。这是下面构造的教学场景，不是线上事故复盘；示例未在本机编译运行。

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

先确认调用的是哪个 JSON 包

本文代码固定以 Go 1.25 文档中的实验接口为基线。Go 1.25 需要在构建时设置 GOEXPERIMENT=jsonv2。不要把这里的实验开关要求直接推广到所有后续版本；新项目应查自己工具链版本的文档，也不要混用不同版本里的回退错误符号。

下面命令供使用 Go 1.25 工具链的读者自行运行，不是本文的执行记录。

# 在当前项目目录中临时启用 Go 1.25 的 JSON v2 实验。
GOEXPERIMENT=jsonv2 go run .

我更倾向给导入路径起别名 jsonv2。这样看见 jsonv2.Marshal 就知道规则交给了哪个包；普通 encoding/json 的调用不能照抄这个可变参数写法。

用独立类型限定需要改写的字段

把展示编号声明成 type DisplayCode string，然后将 Card.PublicCode 设为这个类型，Card.InternalCode 仍然保留 string。注册目标是 DisplayCode，不是 JSON 名称 public_code。

这里最容易忽略的是等号：type DisplayCode = string 是类型别名，不能借它建立独立的匹配范围。同一对象内如果有两个 DisplayCode 字段，它们都属于这套规则的候选；若两者要用不同表示，就继续拆分业务类型，或者建立专门的响应结构体。

把编码器交给本次 Marshal

下面完整示例把展示编号转成大写字符串。这里的大写转换只是演示格式选择，不能拿来规范化大小写敏感的密钥或真实业务标识。

package main

import (
    "encoding/json/jsontext"
    jsonv2 "encoding/json/v2"
    "fmt"
    "log"
    "strings"
)

// DisplayCode 是独立类型，不是 string 的类型别名。
type DisplayCode string

type Card struct {
    PublicCode DisplayCode `json:"public_code"`
    InternalCode string `json:"internal_code"`
}

func main() {
    input := Card{
        PublicCode: DisplayCode("blue"),
        InternalCode: "blue",
    }

    codeEncoder := jsonv2.MarshalToFunc(
        func(enc *jsontext.Encoder, value DisplayCode) error {
            // 编码器只负责一个值，不写字段名，也不自行拼接 JSON 引号。
            text := strings.ToUpper(string(value))
            return enc.WriteToken(jsontext.String(text))
        },
    )

    // 规则只交给本次调用；不会修改进程级默认编码器。
    data, err := jsonv2.Marshal(input, jsonv2.WithMarshalers(codeEncoder))
    if err != nil {
        // 遇到编码失败就停止，不把可能不完整的数据当成成功响应。
        log.Fatal(err)
    }
    fmt.Println(string(data))
}

MarshalToFunc 接收带 Encoder 的函数，回调要完成一个 JSON 值。此处 jsontext.String 构造字符串 token，WriteToken 负责写入，并把错误返回给外层。不要在这个回调里再写 public_code 字段名；字段所属对象由结构体编码负责。

按示例规则，读者自行运行时应检查：public_code 为字符串 BLUE，internal_code 仍为字符串 blue。这是预期语义，不是本机输出记录，也不以空白排版作为成败依据。

另一种接口 MarshalFunc 返回 JSON 字节。如果选择它，返回的是一个完整 JSON 值，不是随便一段文本；字符串也需要正确编码引号和转义。我在这个单字符串场景更愿意使用 token 写法，少自己维护一层 JSON 拼接。

按现象检查匹配、递归和错误

规则是调用级选项，但这不等于只作用在顶层字段。嵌套结构中同类型的值也需要纳入接口设计。若回调中选择再次调用编码入口，必须认真考虑是否又匹配回自身；本例直接写字符串 token，避免了这个多余嵌套。

为接口约定保留一张检查清单

读者可以在自己的项目中分别比较：传规则与不传规则、同值的不同字段类型、空字符串、含双引号的字符串，以及回调主动返回错误的情况。检查重点是表示和错误约定，不是从一段演示得出性能提升结论。本文不运行这些检查，也没有性能数字。

我会在“同一种类型、不同调用方需要不同 JSON 表示”时优先考虑调用级编码器。如果类型本身永远只有一种表示，类型方法也值得考虑；如果只是单个接口的字段组合不同，专门的响应结构体往往更直白。

能不能只按 public_code 名称注册？

这里使用的 MarshalToFunc 按 Go 类型工作，不提供按该字段名注册的参数。用字段专属类型或响应结构来表达这个约束。

编码规则会自动用于反序列化吗？

不会。WithMarshalers 只影响编码。接收端需要的解码规则应单独设计，不要把展示用大写转换当成可逆协议。

能直接复制到所有 Go 版本吗？

不要这样假设。本文明确固定 Go 1.25 实验接口，迁移时应对照对应版本标准库文档，尤其是实验启用方式和错误回退约定。

参考文档：https://pkg.go.dev/encoding/json/v2@go1.25.0；https://pkg.go.dev/encoding/json/jsontext@go1.25.0；https://go.dev/doc/go1.25。