Go问答：json.Decoder DisallowUnknownFields接口收到多余字段时怎样提前报错怎样完成一个可复用的最小示例

Go 的 json.Decoder 默认会忽略 JSON 里没有对应结构体字段的键。如果接口希望客户端一旦多传字段就立刻得到 400，可以在创建 Decoder 后调用 DisallowUnknownFields()，再把 Decode 返回的错误交给统一的请求错误处理。这个开关只针对结构体字段匹配，不会自动让所有 JSON 都变成严格模式。

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

用 DisallowUnknownFields 在解码阶段拒绝多余字段

把开关放在每个请求体自己的 Decoder 上，作用范围就清楚：当前请求解码到结构体时，遇到没有声明、没有被忽略且属于导出字段的键，Decode 返回错误。服务端应在进入数据库或业务服务前结束请求，避免“客户端以为字段已生效、服务端却静默丢弃”的错觉。

package main

import (
    "encoding/json"
    "fmt"
    "strings"
)

type CreateUser struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

func main() {
    body := `{"id": 7, "name": "Lin", "debug": true}`
    dec := json.NewDecoder(strings.NewReader(body))
    dec.DisallowUnknownFields() // 把未声明字段变成解码错误

    var req CreateUser
    if err := dec.Decode(&req); err != nil {
        // 生产接口在这里映射为 HTTP 400，不要继续调用业务层
        fmt.Println(err)
        return
    }
    fmt.Printf("%+v\n", req)
}

上例会打印 json: unknown field "debug"，req 不应被当作合法请求继续使用。实际 HTTP handler 可以把这类错误和语法错误、类型错误统一归为客户端输入错误；日志里保留原始错误，响应体则返回稳定的错误码和简短消息，避免把内部结构暴露给调用方。

字段未知、字段类型错误和尾随 JSON 不是同一件事

DisallowUnknownFields 解决的是“键名没有匹配到结构体字段”。例如 name: 123 仍属于类型不匹配，应按 json.UnmarshalTypeError 的路径处理；JSON 少了某个字段也不会因为这个开关自动报错，必填校验仍应放在解码后。

另外，调用一次 Decode 只消费一个 JSON 值。若接口协议要求请求体只能有一个对象，可再检查是否已经到达 EOF：

func decodeOne(r io.Reader, dst any) error {
    dec := json.NewDecoder(r)
    dec.DisallowUnknownFields() // 先限制对象字段
    if err := dec.Decode(dst); err != nil {
        return err
    }

    var extra any
    if err := dec.Decode(&extra); err != io.EOF {
        // 第二个值或尾随非空内容都说明请求体不符合单对象协议
        if err == nil {
            return errors.New("request body must contain one JSON value")
        }
        return err
    }
    return nil
}

这段辅助函数需要导入 errors 和 io。如果你的协议允许 JSON 流，就不要使用“必须 EOF”的规则；如果只想限制 HTTP 请求体，通常还会配合请求体大小上限。

严格模式的兼容策略与两个常见边界

因此，严格模式不是越强越好，而是要和接口版本策略配套。内部接口、配置写入和容易因拼写错误造成业务偏差的请求，适合严格结构体；公开接口若允许向后兼容，可以给扩展字段单独留容器，或通过版本化 Request 类型承接变化。不要为了“让它报错”把本应开放的元数据整体改成固定结构。

常见问题

DisallowUnknownFields 能检查 JSON 里缺少字段吗？

不能。它只拒绝多出来且无法匹配的键；必填字段要在 Decode 成功后自行判断。

给 map 解码时为什么没有 unknown field 错误？

因为 map 的键集合本来就是动态的。需要白名单时，应先解码到结构体，或在业务层对 map 的键做显式校验。

能不能用 json.Unmarshal 实现同样效果？

标准库的这个开关属于 Decoder 方法。需要严格字段检查时，改用 NewDecoder；不要把 Unmarshal 的默认忽略行为当成严格校验。

接口边界的关键不是“看到多余字段就一律拒绝”，而是先决定哪些字段属于稳定契约，再让 Decoder 在业务逻辑之前执行这条契约。这样返回的 400 才真正对应一个可修复的客户端问题。