jsonv2迁移后自定义Marshal失效怎么办

Go JSON v2 迁移后发现自定义 Marshal 像是失效，通常不是 v2 完全忽略了自定义编码，而是调用链里出现了新的优先级：类型的 MarshalJSONTo 会优先于旧的 MarshalJSON，调用方通过 WithMarshalers 注册的函数还会优先于类型方法。先把实际调用的包、方法集和选项拆开，通常就能定位问题。

官方地址：https://go.dev/doc/jsonv2-migration

最稳妥的处理顺序是：先用最小类型确认方法是否被调用，再检查 MarshalerTo 和 WithMarshalers 覆盖，最后才调整 v1/v2 兼容选项。Go 1.27 中旧的 MarshalJSON 仍受支持，不必因为迁移就一次性重写全部类型。

先确认你迁移到了哪一层

Go 1.25、1.26 阶段可以通过 GOEXPERIMENT=jsonv2 试用新实现；Go 1.27 起，encoding/json/v2 和 encoding/json/jsontext 已成为可用的标准库包，原来的 encoding/json 也由 v2 实现支撑，但 v1 的默认行为仍然保持兼容。换句话说，“换了实现”和“采用 v2 默认语义”不是同一件事。

package main

import (
	"fmt"

	jsonv2 "encoding/json/v2"
)

type OrderID int64

// MarshalJSON 先保留旧接口，便于渐进迁移已有调用方。
func (id OrderID) MarshalJSON() ([]byte, error) {
	// 自定义输出为带前缀的字符串，避免把业务编号当普通数字。
	return []byte(fmt.Sprintf(`"order-%d"`, id)), nil
}

func main() {
	// 传入指针能明确表达可寻址对象，也方便后续增加指针接收者方法。
	b, err := jsonv2.Marshal(OrderID(42))
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b)) // "order-42"
}

这个最小例子能先回答一个问题：旧 MarshalJSON 在 v2 里仍可用。如果它在业务类型中没有被触发，优先检查导入路径、真实传入的动态类型和是否有更高优先级的自定义器，而不是先修改 JSON 选项。

同时实现两个接口时，MarshalJSON 会被绕过

v2 的编码选择顺序可以简化为：调用方通过 WithMarshalers 提供的类型函数优先；没有命中时，优先调用 MarshalerTo.MarshalJSONTo；再退回 Marshaler.MarshalJSON。因此，旧类型如果后来新增了 MarshalJSONTo，两个方法的输出不一致时，看到的自然是新方法的结果。

package main

import (
	"fmt"

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

type Version struct {
	Major int
	Minor int
}

// MarshalJSON 是 v1 生态仍会调用的兼容实现。
func (v Version) MarshalJSON() ([]byte, error) {
	return []byte(fmt.Sprintf(`"v%d.%d"`, v.Major, v.Minor)), nil
}

// MarshalJSONTo 是 v2 推荐的流式接口；它会优先于 MarshalJSON。
func (v Version) MarshalJSONTo(enc *jsontext.Encoder) error {
	// 通过 v2 的编码入口写入一个完整 JSON 字符串值。
	return jsonv2.MarshalEncode(enc, fmt.Sprintf("v%d.%d", v.Major, v.Minor))
}

func main() {
	b, err := jsonv2.Marshal(Version{Major: 2, Minor: 1})
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b)) // "v2.1"
}

迁移时有两种选择：短期只保留 MarshalJSON，让旧调用方和新调用方共享同一个结果；长期改写为 MarshalJSONTo，让方法直接写入 jsontext.Encoder。如果两个方法必须同时存在，就让它们遵守相同的默认语义，并在测试中明确哪一个是 v2 的主路径。

检查 WithMarshalers 和动态类型

v2 允许调用方为任意类型提供自定义函数。这个机制适合不能修改的第三方类型，但它也可能覆盖你刚写好的方法。尤其要检查封装层是否统一传入了 json.WithMarshalers(...)，以及注册函数的泛型类型是否匹配了指针或值。

package main

import (
	"fmt"

	jsonv2 "encoding/json/v2"
)

type UserID int64

// 这个注册器只影响当前 Marshal 调用，不会修改 UserID 的方法。
var userIDMarshaler = jsonv2.MarshalFunc(func(id UserID) ([]byte, error) {
	// 调用方策略把编号编码成 JSON 字符串。
	return []byte(fmt.Sprintf(`"uid:%d"`, id)), nil
})

func main() {
	b, err := jsonv2.Marshal(UserID(7), jsonv2.WithMarshalers(userIDMarshaler))
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b)) // "uid:7"
}

如果删除 WithMarshalers 后旧方法恢复，原因就找到了。若类型被放进 any、接口或指针容器中，还要确认注册函数的类型参数与实际动态类型一致；不要只看外层变量的静态声明。

保留 MarshalJSON 时避免指针和递归陷阱

v2 会保证值可寻址，因此指针接收者方法的调用比旧实现更一致；工程上仍建议让方法接收者和调用约定保持清晰。更常见的错误是自定义方法内部再次对同一个类型调用 json.Marshal，导致递归，或者为了绕过方法把别名写错，结果把字段名和标签语义一起改变。

package main

import (
	"fmt"

	jsonv2 "encoding/json/v2"
)

type Profile struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

// MarshalJSON 使用局部辅助类型，避免再次命中 Profile.MarshalJSON。
func (p Profile) MarshalJSON() ([]byte, error) {
	// 辅助结构只承载本次需要改变的字段，避免对自身递归编码。
	view := struct {
		Display string `json:"display"`
		Age     int    `json:"age"`
	}{Display: p.Name, Age: p.Age}
	return jsonv2.Marshal(view)
}

func main() {
	b, err := jsonv2.Marshal(Profile{Name: "Lin", Age: 30})
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b)) // {"display":"Lin","age":30}
}

如果只是想保留原结构再覆盖一个字段，也可以定义不带方法的辅助类型，并显式复制字段。不要在 MarshalJSON 中直接把 p 再传给同一个 Marshal，这与 v1 还是 v2 无关，都会形成递归调用。

按风险分阶段迁移

如果问题不是方法完全没被调用，而是输出从 null 变成空数组、大小写匹配或重复键处理发生变化，可以先让 v2 使用 v1 兼容选项，再逐项关闭兼容开关。这样能把“自定义方法问题”和“默认语义差异”分离。

package main

import (
	"fmt"

	jsonv1 "encoding/json"
	jsonv2 "encoding/json/v2"
)

type Payload struct {
	Items []string `json:"items"`
}

func main() {
	value := Payload{}
	// 先保留 v1 默认语义，便于逐项比较迁移差异。
	b, err := jsonv2.Marshal(value, jsonv1.DefaultOptionsV1())
	if err != nil {
		panic(err)
	}
	fmt.Println(string(b))
}

DefaultOptionsV1 只控制默认编码语义，不会把调用方注册器、MarshalerTo 和 MarshalJSON 的优先级倒过来。先确认方法选择，再处理选项差异，排查路径会更短。

迁移后的快速排查清单

相关问题

只实现 MarshalJSON 需要马上改成 MarshalJSONTo 吗？

不需要。Marshaler 仍受支持；只有在需要流式写入、读取 v2 选项或希望减少中间字节切片时，才值得迁移到 MarshalerTo。

为什么我给 MarshalJSON 加了日志，却一次也没有输出？

优先检查同一类型是否实现了 MarshalJSONTo，调用处是否传入了 WithMarshalers，以及真正编码的动态类型是否是该类型。v2 的方法选择是有明确优先级的。

迁移期能否继续使用 encoding/json？

可以。Go 1.27 的旧包继续支持，且由 v2 实现支撑；如果只想逐步采用新语义，可以在 v2 调用中传入 DefaultOptionsV1，再按差异逐项调整。