如果一个请求体里多了业务结构体没有声明的字段，Go JSON v2 默认仍然会把这个成员忽略。要把输入契约收紧，关键不是给每个字段加标签，而是在解码入口传入 json.RejectUnknownMembers(true)。这样，未知成员会让解码失败，并且可以从结构化错误中取出字段位置。
官方地址：https://pkg.go.dev/encoding/json/v2
实际项目里，我会把严格解码放在外部 JSON 进入业务结构体的边界：内部兼容层可以按需保留旧行为，但请求校验层明确拒绝拼写错误、误传参数和未发布字段。
先分清“未知字段”与“缺少字段”
JSON 对象成员没有匹配到目标结构体字段时，称为未知成员。Go JSON v2 文档说明，默认情况下未知成员及其值会被忽略；RejectUnknownMembers 只改变这一项解码语义，不会自动把所有业务必填规则变成校验器。
例如目标结构体只有 ID 和 Name，输入却多出 debug。默认解码后，ID、Name 可以正常进入结构体，debug 则没有落点。这个行为对向后兼容有利，但也会把客户端拼写错误静默吞掉。
严格模式解决的是“不能出现未声明成员”，不是“每个声明成员都必须出现”。字段是否为空、字符串是否符合格式、数值是否在范围内，仍应由业务层单独处理。
用 RejectUnknownMembers 开启严格解码
JSON v2 的普通解码函数接收可变数量的选项。将 json.RejectUnknownMembers(true) 传给 json.Unmarshal，就能让结构体解码在发现未知成员时返回错误。
package main
import (
"fmt"
"encoding/json/v2"
)
type CreateUserRequest struct {
ID string `json:"id"`
Name string `json:"name"`
}
func decodeRequest(data []byte) error {
var req CreateUserRequest
// 在请求边界开启严格模式，防止未声明成员悄悄进入兼容链路。
if err := json.Unmarshal(data, &req, json.RejectUnknownMembers(true)); err != nil {
return fmt.Errorf("decode create-user request: %w", err)
}
// 严格解码只负责输入成员边界，必填字段仍由业务规则检查。
if req.ID == "" || req.Name == "" {
return fmt.Errorf("id and name are required")
}
return nil
}
这个选项只影响解码，不影响结构体 marshaling。代码中的业务检查也不能删掉：输入没有 name 时，严格模式不会因为“缺失”而自动报错。
把错误变成可处理的字段提示
只把底层错误字符串直接返回给客户端，通常不够稳定。JSON v2 在拒绝未知成员时会使用 json.ErrUnknownName，并将语义错误包装为 json.SemanticError。官方文档还提供了 JSON Pointer，用于定位未知成员在输入中的位置。
package main
import (
"errors"
"fmt"
"encoding/json/v2"
)
func explainDecodeError(err error) string {
// 先提取结构化语义错误，再决定对外展示什么信息。
semantic, ok := errors.AsType[*json.SemanticError](err)
if !ok || semantic.Err != json.ErrUnknownName {
// 语法错误、类型错误和业务错误不应伪装成未知字段。
return "请求体无法按当前结构解析"
}
// JSON Pointer 的最后一个 token 就是未声明的成员名。
name := semantic.JSONPointer.LastToken()
if name == "" {
return "请求体包含未声明成员"
}
return fmt.Sprintf("请求体包含未声明成员 %q", name)
}
SemanticError 的具体文本可能随实现细节变化，所以更适合依赖错误类型和哨兵值，而不是匹配整段英文错误消息。对外响应可以只给出字段名；服务端日志再记录 JSON Pointer 和原始错误，便于排查嵌套对象中的位置。
嵌套结构、标签和兼容字段怎么处理
严格模式的价值在于把外部输入的成员集合固定下来，但嵌套结构仍要按实际契约设计。一个常见误区是：顶层结构体开启严格模式，就把所有动态扩展字段都当成错误。若某个字段本来就是扩展容器，应显式把它建模为 map[string]jsontext.Value 或 JSON v2 对应的原始值类型，而不是期待未知成员自动落入 map。
字段标签负责声明名称映射和忽略规则；被明确忽略的字段不应被误认为未知字段。相反，客户端把 user_nmae 写成拼写错误时，严格模式应让它失败，而不是靠服务端“猜”它想表达 user_name。
对正在迁移的接口，可以把允许扩展的内容集中到一个明确字段中，例如 extensions。这样既保留扩展能力，又不会让任意顶层成员绕过契约。
type Envelope struct {
RequestID string `json:"request_id"`
Extensions map[string]jsontext.Value `json:"extensions,omitzero"`
}
// 扩展内容必须位于 extensions 内，顶层拼写错误仍由严格模式拦截。
如果代码需要使用 jsontext.Value，请同时导入 encoding/json/jsontext。严格模式不会替你决定扩展值的业务 schema；它只保证扩展入口是显式的。
从旧 Decoder 迁移到 JSON v2
旧 API 通常这样开启严格解码：创建 encoding/json.Decoder 后调用 DisallowUnknownFields()。迁移到 encoding/json/v2 时，可以把“严格成员边界”改成一次 Unmarshal 调用上的 RejectUnknownMembers(true)。
// 旧写法：选项挂在 Decoder 状态上，适合已有 io.Reader 管线。
dec := jsonv1.NewDecoder(reader)
// 让目标为结构体时，未匹配的对象键返回错误。
dec.DisallowUnknownFields()
err := dec.Decode(&req)
// v2 写法：把严格语义作为本次解码的显式选项传入。
data, err := io.ReadAll(reader)
if err != nil {
return err
}
// 选项只作用于当前调用，便于让不同入口拥有不同兼容策略。
err = jsonv2.Unmarshal(data, &req, jsonv2.RejectUnknownMembers(true))
迁移时不要只替换 import 就认为行为已经等价。Go 官方迁移指南强调，encoding/json 会继续保留并支持，应用应按接口逐步验证兼容性。对于仍需保留旧流式读取的入口，可以先继续使用旧 Decoder；新接口则直接采用 v2 选项，并在测试中覆盖未知字段、缺失字段、嵌套字段和扩展字段。
把严格解码放在哪一层最稳妥
我更建议把它放在 HTTP、消息队列或任务入口的“反序列化层”，而不是在每个业务函数里重复传选项。入口层统一决定：未知字段是直接返回 400、进入隔离队列，还是被兼容适配器转换。业务函数接收到的应是已经通过成员边界处理的结构体。
上线前至少准备四类样例：完全匹配的请求、带拼写错误的请求、缺少声明字段的请求、以及通过显式 extensions 传递扩展内容的请求。这样能把“拒绝未知字段”和“业务必填校验”分开观察。
如果客户端发布节奏不一致，可以先在日志中统计未知成员，再对高频客户端给出迁移提示；但一旦开启正式拒绝，不能同时依赖静默丢弃来保证兼容。兼容策略应该写在接口文档里，而不是藏在 JSON 解码器的默认值中。
常见问题
RejectUnknownMembers 会检查缺少的字段吗？
不会。它只拒绝目标结构体没有声明的 JSON 成员，必填字段和字段值范围仍要由业务校验处理。
未知字段错误能拿到字段名吗？
可以优先从 SemanticError 的 JSONPointer 取最后一个 token，并用 ErrUnknownName 区分这类错误；不要依赖完整错误字符串。
动态字段应该怎样保留？
把动态内容放进显式的扩展字段，例如 extensions，再为其中的值定义独立处理规则，不要让任意顶层未知成员变成隐式扩展。
旧项目必须马上切换到 JSON v2 吗？
不必。可以保留 encoding/json，按接口逐步迁移；真正需要严格未知成员时，在新入口明确使用 v2 选项，并用兼容测试覆盖旧客户端。
归纳一下：未知字段控制的关键开关是 json.RejectUnknownMembers(true)，错误处理的关键是 SemanticError + ErrUnknownName + JSONPointer，工程落地的关键则是把严格边界放在输入入口，并为合法扩展提供显式容器。
