Go encoding/json Decoder.DisallowUnknownFields 适合哪些接口

我在给内部写入接口收紧 JSON 契约时，最先考虑的不是“能不能打开严格模式”，而是“这个接口有没有资格拒绝未来字段”。Decoder.DisallowUnknownFields() 适合由你控制结构、希望客户端尽早暴露拼写错误的接口；不适合供应商 webhook、公共 API 或允许扩展元数据的 payload。因为它只对解码到结构体的对象键生效，未知键会让 Decode 返回错误。

判断标准很简单：接口契约是封闭的，就可以严格；契约需要向前兼容，就保持宽松。开启后，业务代码必须把解码错误当作失败处理，不能继续使用可能已经部分填充的结构体。

它到底把什么字段当成未知

标准库会把 JSON 对象键和目标结构体的导出字段、json 标签进行匹配。匹配不到的键才是 unknown field；如果目标是 map[string]any，键本来就由 map 接收，不会触发这个开关。

严格接口要把错误挡在业务层之前

下面的写法把严格解码放在 HTTP 边界，并额外检查第二个 JSON 值。示例中的错误文本只作为客户端提示，不把内部类型和堆栈直接暴露出去。

type CreateUserRequest struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

func decodeCreateUser(w http.ResponseWriter, r *http.Request) (CreateUserRequest, bool) {
	var req CreateUserRequest
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields() // 封闭写接口拒绝未声明的 JSON 键

	if err := dec.Decode(&req); err != nil {
		http.Error(w, "请求字段不符合接口契约", http.StatusBadRequest) // 解码失败时不要继续执行业务
		return CreateUserRequest{}, false
	}

	var extra any
	if err := dec.Decode(&extra); err != io.EOF {
		http.Error(w, "请求体必须只有一个 JSON 对象", http.StatusBadRequest) // 拒绝尾随 JSON 值
		return CreateUserRequest{}, false
	}
	return req, true
}

这里最重要的不是把错误信息写得多详细，而是失败就返回零值并停止后续流程。DisallowUnknownFields 返回的通常是类似 json: unknown field "nickname" 的错误；嵌套对象的定位信息并不适合直接当成稳定的客户端协议，因此生产接口可以记录服务端日志，再返回统一的 400。

别把严格模式当成所有输入的安全阀

如果上游是独立团队或外部平台，新增一个无害字段也可能是正常演进。此时可以用结构体接收业务字段，把可扩展部分单独放进 metadata，而不是让整个对象都进入严格模式。对兼容性要求高的读取接口，也可以继续使用默认宽松行为，并在业务层只校验真正必需的字段。

还要注意，严格模式解决的是“字段名没有契约”这一类输入问题，不会自动检查必填字段、字段取值范围、重复键或跨字段关系。name 为空、两个字段互相矛盾，仍然需要业务校验；重复 JSON 键也不能靠这个方法代替专门的策略。

上线前用四个问题做决定

1. 客户端和服务端是否由同一团队或同一版本契约共同维护？
2. 未来新增字段时，旧版本是否必须继续接受请求？
3. 未知字段是拼写错误，还是合法的扩展数据？
4. 解码失败后，是否能在进入数据库、队列或副作用操作前结束请求？

四个答案分别偏向“是、否、错误、是”时，开启严格模式通常值得。只要第三方扩展字段是业务设计的一部分，就不要为了看起来更严格而全局开启。

相关问题

DisallowUnknownFields 会检查 map 吗？ 不会，它主要约束解码到结构体时无法匹配的对象键。

未知字段报错后还能继续用结构体吗？ 不建议。解码可能已经写入部分字段，应该把本次请求视为失败并丢弃结果。

它能代替参数校验吗？ 不能。必填、范围、格式和跨字段规则仍要在解码成功后单独检查。