json/v2 自定义格式化器不生效的排查顺序

encoding/json/v2 的自定义格式化器没有全局注册表。用 json.MarshalFunc 创建的处理器，必须通过 json.WithMarshalers 传给同一次 json.Marshal、MarshalWrite 或 MarshalEncode 调用，而且泛型参数要能匹配实际值类型。排查时先看版本和导入路径，再看选项、类型、组合顺序，通常比从格式化函数内部开始猜更快。

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

先确认版本与导入路径

第一步看 go.mod 和 import。Go 1.27 的标准库路径是 encoding/json/v2；如果代码仍导入 encoding/json，调用的就是 v1 API。早期试验代码还可能导入 github.com/go-json-experiment/json，或者依赖 GOEXPERIMENT=jsonv2 才能看到标准库实验包。三者的类型和选项不能想当然地混用。

如果项目从 Go 1.25 或 1.26 升级而来，先统一依赖路径，再删除仅为实验包准备的构建开关。不要同时给两个 json 包起相同别名，否则代码审查时很难看出 Marshal 到底来自哪一个包。

再确认 WithMarshalers 传给了同一次调用

下面是一个能直接证明格式化器被调用的最小示例。它把整数分值 Amount 格式化为带两位小数的 JSON 字符串，并用计数器确认命中次数。

package main

import (
    "fmt"
    "log"
    "strconv"

    json "encoding/json/v2"
)

type Amount int64

type Invoice struct {
    Total Amount `json:"total"`
}

func main() {
    calls := 0
    amountFormatter := json.MarshalFunc(func(v Amount) ([]byte, error) {
        // 计数用于区分“函数没命中”和“命中后输出不符合预期”。
        calls++
        text := fmt.Sprintf("%.2f", float64(v)/100)
        // strconv.Quote 生成合法的 JSON 字符串字面量。
        return []byte(strconv.Quote(text)), nil
    })

    out, err := json.Marshal(
        Invoice{Total: 1234},
        // 格式化器必须作为当前 Marshal 的选项传入。
        json.WithMarshalers(amountFormatter),
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("json=%s calls=%d\n", out, calls)
}

json={"total":"12.34"} calls=1

最常见的错误是：创建了 amountFormatter，但最终调用成 json.Marshal(invoice)；或者只把选项传给外层的某个辅助函数，却在辅助函数内部重新调用了不带选项的 json.Marshal。格式化器不是进程级状态，不会自动影响其他调用点。

核对 MarshalFunc 的目标类型

json.MarshalFunc[T] 是类型特定的。上例注册的是 Amount，它不会顺便处理所有 int64，也不会自动处理另一个底层类型同为 int64 的命名类型。先打印或在测试中断言待编码字段的静态类型，不要只看运行值长得像什么。

值与指针也要有意识地选择。v2 会把值变成可寻址对象，因此针对 *T 的函数可以用于值 T 或非 nil 的 *T；但 nil 指针仍有自己的空值语义。若用接口类型作为泛型参数，它会匹配实现该接口的值，范围可能比预期更宽。排障时优先从具体命名类型开始，确认命中后再抽象成接口。

另一个常见混淆是把“字段格式化标签”和“调用方格式化函数”当成同一机制。Go 1.27 初始正式版的 json/v2 不应依赖实验阶段的 format struct tag 作为通用解决方案；需要任意类型的自定义表示时，以 MarshalFunc、MarshalToFunc 或类型方法为准。

检查组合顺序与选项覆盖

有多个格式化器时，要先用 json.JoinMarshalers 合并，再传一次 json.WithMarshalers。适用于同一值的函数中，列表前面的优先。如果前面的函数成功返回，后面的函数不会再被调用；只有返回 errors.ErrUnsupported，分派才会继续寻找下一个适用处理器，全部不支持时才回到默认编码。

formatters := json.JoinMarshalers(
    json.MarshalFunc(func(v Amount) ([]byte, error) {
        // 精确类型放前面，避免被更宽泛的接口处理器提前截获。
        return []byte(strconv.Quote(fmt.Sprintf("%.2f", float64(v)/100))), nil
    }),
    json.MarshalFunc(func(v fmt.Stringer) ([]byte, error) {
        // 宽泛处理器作为后备，只处理实现 Stringer 的其他类型。
        return []byte(strconv.Quote(v.String())), nil
    }),
)

out, err := json.Marshal(value,
    // 多个处理器合并后只设置一次 WithMarshalers。
    json.WithMarshalers(formatters),
)

不要连续传两个独立的 json.WithMarshalers(...) 并期待自动追加。Options 的同一属性以后传值覆盖先传值；想组合就使用 JoinMarshalers。同理，封装函数若在末尾追加一套公共 Options，也可能覆盖调用方之前提供的格式化器。

嵌套类型不生效时检查递归调用

如果自定义的是外层复合类型，并在 MarshalToFunc 中手工写完整 JSON，那么内部字段不会自动再次经过原来的语义分派。官方文档建议复合类型在处理子值时调用 json.MarshalEncode，这样当前编码器携带的 Options，包括 WithMarshalers，才能继续作用于嵌套类型。

因此“顶层 Amount 能格式化，放进自定义容器后不生效”时，不要先怀疑泛型匹配；先看容器处理器是否绕过了 MarshalEncode。直接拼接 JSON 字节还会把字符串转义、无效 UTF-8 和嵌套错误处理都压到自己的代码上。

用表格按顺序收敛问题

常见问题

类型实现了 MarshalJSON，WithMarshalers 还会生效吗？

会。调用方通过 WithMarshalers 提供的匹配函数优先于类型自身的方法和默认表示。

为什么同一个格式化器在 Marshal 中生效，在 Unmarshal 中不生效？

WithMarshalers 只影响编码。解码要使用 UnmarshalFunc 或 UnmarshalFromFunc，并通过 WithUnmarshalers 传入。

返回 errors.ErrUnsupported 有什么作用？

它表示当前处理器主动放弃该值，让 JoinMarshalers 尝试后面的适用处理器；如果都放弃，才进入默认编码规则。

怎样最快证明“确实没调用”？

在格式化函数中增加测试计数器，并同时断言调用次数与 JSON 结果。只比较最终字符串，容易把未命中与命中后返回错误混为一谈。