Go encoding/json/v2 Options 怎样在控制 JSON 编码选项（输入边界）

我第一次把 Go 1.27 的 encoding/json/v2 接到一个已有接口时，真正卡住的不是 Marshal 调用，而是“选项到底应该放在哪里”：有些选项只影响编码，有些只影响解码，还有些属于 jsontext 的语法层。把它们都塞进一个全局变量，调用方很快就会互相影响。

更稳妥的做法是把 Options 看成一次调用的配置集合：公共约束先组合，当前调用需要的例外最后传入。Go 官方文档说明，后传入的选项会覆盖先传入的同一属性，不相关的选项会被对应操作忽略。

官方资料：https://go.dev/doc/go1.27　https://go.dev/doc/jsonv2-migration　https://pkg.go.dev/encoding/json/v2

先把 Options 的作用面分开

encoding/json/v2 的 Marshal、Unmarshal 等函数都接受可变数量的 Options。它不是普通的业务参数，也不是只能初始化一次的配置中心，而是描述这次 JSON 操作的语义。

例如，Deterministic(true)只对编码有意义；RejectUnknownMembers(true)只对解码有意义；jsontext.AllowDuplicateNames(false)则属于 JSON 文本语法约束。它们可以一起传入，但每个操作只读取自己关心的部分。

用三个选项表达明确的工程约束

下面这个例子把“稳定输出”“nil 切片保持旧语义”和“拒绝未知字段”放在同一次调用里。代码中的选项故意分开，便于读者看出它们分别约束编码和解码：

package main

import (
	"fmt"

	jsonv2 "encoding/json/v2"
)

type Event struct {
	Name  string   `json:"name"`
	Tags  []string `json:"tags"`
	Count int      `json:"count"`
}

func main() {
	e := Event{Name: "deploy", Tags: nil, Count: 1}

	// 编码侧固定 map 等无序数据的输出，并让 nil 切片保持 v1 的 null 语义。
	b, err := jsonv2.Marshal(e,
		jsonv2.Deterministic(true),
		jsonv2.FormatNilSliceAsNull(true),
	)
	if err != nil {
		// 生产代码应把编码错误交给调用方，而不是继续发送不完整 JSON。
		panic(err)
	}
	fmt.Println(string(b))

	var decoded Event
	input := []byte(`{"name":"deploy","tags":[],"count":1,"debug":true}`)
	// 解码侧拒绝结构体没有声明的成员，避免静默吞掉字段拼写错误。
	if err := jsonv2.Unmarshal(input, &decoded, jsonv2.RejectUnknownMembers(true)); err != nil {
		fmt.Println("拒绝未知字段:", err)
	}
}

这里最容易误解的是“传了选项就一定改变结果”。实际上，编码阶段传入 RejectUnknownMembers 没有意义，解码阶段传入 Deterministic 也不会让解码器做额外工作。把每个选项写在真正消费它的调用附近，维护成本更低。

公共配置与单次例外怎么组合

Options 的组合适合表达“组织默认值 + 当前请求差异”。如果多个选项同时设置同一属性，后出现的值优先。因此可以先保留一份团队约定，再在特殊导出场景覆盖：

var defaultJSONOptions = jsonv2.JoinOptions(
	jsonv2.Deterministic(true),
	jsonv2.FormatNilSliceAsNull(true),
)

func encodeForAPI(v any) ([]byte, error) {
	// 默认配置服务于普通接口，调用方不需要重复列出每个选项。
	return jsonv2.Marshal(v, defaultJSONOptions)
}

func encodeForSnapshot(v any) ([]byte, error) {
	// 快照调用只覆盖一个属性，其余默认值仍然保留。
	return jsonv2.Marshal(v, defaultJSONOptions, jsonv2.FormatNilSliceAsNull(false))
}

我更倾向于只封装稳定的公共约束，不把所有可能的选项都隐藏在 helper 里。否则调用点看不出输出为何变化，排查兼容问题时还要回头翻几层封装。

迁移 v1 语义时不要一开始全量打开

Go 1.27 引入 encoding/json/v2 后，v2 默认更严格，例如重复对象成员会报错、无效 UTF-8 会报错；原有 encoding/json 仍然受兼容承诺保护，不要求项目立即迁移。需要兼容旧行为时，可以传入 jsonv1.DefaultOptionsV1()，也可以只补一个已确认的差异。

例如，旧接口只依赖 nil 切片序列化成 null，就优先使用 FormatNilSliceAsNull(true)；只有当一组旧行为必须整体保持时，才考虑 DefaultOptionsV1()。这样能让迁移范围可解释，也避免把新语义全部关闭。

我的落地清单：按变化频率决定封装层级

• 输出要可复现时，在编码调用附近显式使用 Deterministic(true)，但不要把它当成跨构建、跨工具链的字节级协议保证。
• 输入要拒绝未知字段时，把 RejectUnknownMembers(true) 放在解码边界，并为客户端升级预留错误处理。
• 迁移旧接口时先记录具体差异，再选择一个兼容选项；不要因为“看起来更安全”就无条件套用整套 v1 默认。
• 公共 Options 只承载稳定约束，临时导出、调试或快照差异留在调用点，便于读者判断最终语义。

对我来说，Options 最有价值的地方不是选项数量多，而是把 JSON 语义变成调用点可见的决策。只要先区分编码、解码和语法层，再利用后传覆盖规则，就能把 v2 的严格默认与旧系统的兼容需求放在同一套代码里管理。

相关问题

Options 会修改全局 JSON 行为吗？

不会。它随本次 Marshal 或 Unmarshal 调用传入；只有你自己把它封装成公共变量或 helper 时，才会形成项目级约定。

为什么传入了一个选项却看不到效果？

先检查它是否作用于当前操作。例如确定性排序影响编码，拒绝未知成员影响解码，传到相反方向时会被忽略。

迁移项目必须改用 encoding/json/v2 吗？

不必须。可以继续使用 encoding/json，也可以在明确知道差异后用 v2 加入最小兼容选项，按接口逐步迁移。