encoding/json Decoder 如何限制单次读取的嵌套深度

我在给一个接收外部 JSON 的 Go 接口加资源边界时，先想到的是给 json.Decoder 找一个“最大嵌套层数”配置。查过接口后才发现，传统 encoding/json 的 Decoder 并没有公开这个参数。它内部确实有固定的最大嵌套保护，但这个值不能直接改成业务想要的 20 层、50 层。

官方地址：https://pkg.go.dev/encoding/json

如果接口需要更严格的单次读取限制，做法是把“最大字节数”和“最大结构深度”拆成两个门：先在受控大小内读入一个 JSON 值，扫描对象和数组的真实嵌套，再把通过检查的字节交给 json.Decoder。不要把标准库内部固定上限当成业务策略。

先确认 Decoder 的限制边界

传统 encoding/json 的公开方法包括 Decode、Token、UseNumber 和 DisallowUnknownFields，没有 SetMaxDepth 之类的配置。官方源码中的扫描器用固定的 maxNestingDepth = 10000 防止结构过深导致栈溢出，超过后会返回语法错误。

这层保护解决的是标准库自身的安全底线，不等于“我的接口允许 10000 层”。如果业务数据只应该有几层，仍然需要在请求入口建立自己的阈值。Go 源码里另有一组尚未实现的 WithDepthLimit 设计注释，也不能当作当前 v1 encoding/json 的可调用 API。

把字节上限和深度上限分开

嵌套层数和请求体大小是两种不同的资源风险：一段 JSON 可以只有两层却包含很长的字符串，也可以很小但把对象和数组套得很深。实际入口最好先限制字节数，再限制结构深度。

下面的示例把“单次读取”定义为一个有大小上限的 JSON 输入。它先最多读 maxBytes + 1 个字节，超过上限立即拒绝；读入成功后用一个小状态机统计 {、[ 和对应的闭合符号。字符串里的括号会被忽略，避免把文本内容误算成结构深度。

package main

import (
	"bytes"
	"encoding/json"
	"errors"
	"fmt"
	"io"
)

var (
	// 让上层可以按错误类型区分字节限制和深度限制。
	ErrTooManyBytes = errors.New("json input is too large")
	ErrTooDeep      = errors.New("json nesting is too deep")
)

func checkJSONDepth(data []byte, maxDepth int) error {
	// 只把对象和数组的分隔符当作结构；字符串内部的括号不能改变深度。
	depth := 0
	inString := false
	escaped := false
	for _, ch := range data {
		if inString {
			if escaped {
				// 反斜杠只影响字符串中的下一个字节。
				escaped = false
			} else if ch == '\\' {
				escaped = true
			} else if ch == '"' {
				inString = false
			}
			continue
		}
		if ch == '"' {
			inString = true
			continue
		}
		switch ch {
		case '{', '[':
			depth++
			if depth > maxDepth {
				return fmt.Errorf("%w: depth=%d limit=%d", ErrTooDeep, depth, maxDepth)
			}
		case '}', ']':
			depth--
			if depth  maxBytes {
		return fmt.Errorf("%w: limit=%d", ErrTooManyBytes, maxBytes)
	}
	if err := checkJSONDepth(data, maxDepth); err != nil {
		return err
	}
	dec := json.NewDecoder(bytes.NewReader(data))
	if err := dec.Decode(dst); err != nil {
		return fmt.Errorf("decode JSON: %w", err)
	}
	var extra any
	if err := dec.Decode(&extra); err != io.EOF {
		if err == nil {
			return fmt.Errorf("multiple top-level JSON values are not allowed")
		}
		return fmt.Errorf("trailing JSON: %w", err)
	}
	return nil
}

这里的顺序很重要：io.LimitReader 只负责输入大小，checkJSONDepth 只负责结构深度，真正的 JSON 语法和目标类型转换仍交给 Decoder。如果你需要允许一个请求体里连续放多个顶层值，应先明确协议，再把“一个值”的边界单独处理，不要直接把整条流当成一个对象。

在 Decode 前拒绝过深数据

把上面的函数接到 HTTP 入口时，阈值应该和业务数据模型一起定，而不是照抄标准库的内部数字。比如只接收扁平配置，可以把深度设为 8；允许嵌套过滤器或树形菜单，可能需要 16 或 32。阈值过小会误伤合法数据，阈值过大又失去入口保护的意义。

type CreateRequest struct {
	Name   string            `json:"name"`
	Labels map[string]string `json:"labels"`
}

func parseCreateRequest(body io.Reader) (CreateRequest, error) {
	var req CreateRequest
	// 这里同时限制体积和结构深度，避免把默认内部上限当成业务契约。
	if err := decodeOne(body, &req, 1

如果入口还要禁止未知字段，可以在深度检查通过后调用 dec.DisallowUnknownFields() 再执行 Decode。这两件事解决的问题不同：前者限制结构规模，后者限制字段契约，不能互相替代。

流式 Token 场景如何处理

Decoder.Token 适合边读边消费 JSON 流。它返回对象、数组的分隔符，并保证分隔符嵌套匹配。你可以在消费 token 的同时维护一个深度计数，在打开对象或数组时加一，关闭时减一。

func consumeWithDepth(dec *json.Decoder, maxDepth int) error {
	depth := 0
	for {
		tok, err := dec.Token()
		if errors.Is(err, io.EOF) {
			return nil
		}
		if err != nil {
			return fmt.Errorf("read token: %w", err)
		}
		if delim, ok := tok.(json.Delim); ok {
			switch delim {
			case '{', '[':
				depth++
				if depth > maxDepth {
					return fmt.Errorf("%w: depth=%d limit=%d", ErrTooDeep, depth, maxDepth)
				}
			case '}', ']':
				depth--
			}
		}
	}
}

这个版本的代价也很明确：token 已经被消费，不能再把同一个 Decoder 交给另一个 Decode 调用。若既要提前检查深度、又要把结果解到结构体，就保留一份受控输入后再创建第二个 Decoder；若数据很大，则应让 token 消费逻辑自己构造结果，或选择专门支持深度选项的解析方案。

把失败处理接入自动化工作流

我最后把入口失败拆成四类，日志和通知就清楚很多：

• 超出字节数：在 io.ReadAll 之后判断，通常返回请求体过大。
• 超过业务深度：返回 ErrTooDeep，不要把它伪装成普通 JSON 语法错误。
• 语法不完整：交给 Decoder 的最终解析结果，记录请求上下文但不要回显整段输入。
• 目标类型不匹配：这是数据契约问题，与深度门禁分开统计。

需要注意，深度预扫描不是安全万能药。字符串长度、键数量、数组元素数量和单个数字长度仍然可能影响内存与 CPU；它们应分别设上限。对于真正的大型流式 JSON，也不要为了做一个预扫描而无界缓存整个请求体。

一张表记住该怎么选

常见问题

Decoder 能不能直接设置最大深度？

传统 encoding/json.Decoder 没有公开的 per-decoder 深度设置方法。应用层需要在 Decode 前做受控预扫描，或者在 Token 消费流程中自己维护计数。

标准库的 10000 层够不够用？

它是标准库内部防止过深结构的固定保护，不是业务接口的容量承诺。接口通常应根据自己的数据模型设置更小的阈值。

字符串里的 { 和 [ 要不要计数？

不要。只有 JSON 结构中的对象、数组分隔符改变深度，字符串内容必须先跳过并正确处理转义。

为什么不直接先调用 Token，再 Decode？

因为 Token 会推进 Decoder 的输入位置。除非你保留原始字节并重新创建 Decoder，否则不能把已经消费过的流再交给 Decode。

总结：传统 encoding/json 只能提供固定的内部最大嵌套保护，不能直接把单次读取深度改成业务阈值。最稳妥的入口流程是限制字节、扫描结构、再 Decode；流式场景则在 Token 消费时维护深度，并接受结果构造方式的变化。