Go / 系统课时

安全解码 JSON 请求

安全解码 JSON 请求

本篇解决 Go HTTP 接口如何在业务逻辑之前安全接收 JSON:先校验媒体类型和请求体上限,再用 json.Decoder 严格解码,拒绝未知字段、空请求体与额外 JSON 值,并把失败稳定映射到 400、413 或 415。

学习目标

  • 使用 Content-Type、http.MaxBytesReader 和 json.Decoder 建立请求体边界
  • 用 DisallowUnknownFields 与第二次解码拒绝未知字段和额外 JSON 值
  • 将常见解码失败映射为稳定、可预测的 HTTP 状态码

把边界放在业务逻辑之前

JSON 接口不应直接对 r.Body 无限制读取。更稳妥的顺序是:解析媒体类型、限制可读取字节数、严格解码到明确结构体、确认流中没有第二个 JSON 值,最后再进入字段校验和业务处理。

JSON 请求体安全解码链路

Content-Type 可能带参数,例如 application/json; charset=utf-8,因此不能用字符串完全相等判断;应先用 mime.ParseMediaType 取得主媒体类型。请求体上限则要在解码前通过 http.MaxBytesReader 生效,避免先读入内存再补做长度检查。

用一个主示例覆盖关键失败路径

下面的程序启动一个只监听本机随机端口的 HTTP 服务,再由同一进程发送五类请求。这样能验证真实 net/http 读写链路,同时避免把端口写死。示例只负责安全解码,不把字段必填或业务规则混入解析层。

go
package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"mime"
	"net"
	"net/http"
	"strings"
)

const maxBodyBytes = 64

type createUserRequest struct {
	Name string `json:"name"`
	Age  int    `json:"age"`
}

type errorResponse struct {
	Error string `json:"error"`
}

func writeJSON(w http.ResponseWriter, status int, value any) {
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(value)
}

func decodeCreateUser(w http.ResponseWriter, r *http.Request) (createUserRequest, int, string) {
	mediaType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
	if err != nil || mediaType != "application/json" {
		return createUserRequest{}, http.StatusUnsupportedMediaType, "Content-Type 必须是 application/json"
	}

	// 必须在 Decoder 读取之前设置上限,才能在读取过程中阻止过大的请求体。
	r.Body = http.MaxBytesReader(w, r.Body, maxBodyBytes)
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields()

	var in createUserRequest
	if err := dec.Decode(&in); err != nil {
		var maxErr *http.MaxBytesError
		switch {
		case errors.As(err, &maxErr):
			return createUserRequest{}, http.StatusRequestEntityTooLarge, "请求体过大"
		case errors.Is(err, io.EOF):
			return createUserRequest{}, http.StatusBadRequest, "请求体不能为空"
		case strings.HasPrefix(err.Error(), "json: unknown field "):
			return createUserRequest{}, http.StatusBadRequest, "JSON 包含未知字段"
		default:
			return createUserRequest{}, http.StatusBadRequest, "JSON 格式或字段类型不正确"
		}
	}

	// 第一次解码成功后,第二次只能读到 EOF;否则请求体中还有额外内容。
	var extra any
	if err := dec.Decode(&extra); err != io.EOF {
		var maxErr *http.MaxBytesError
		if errors.As(err, &maxErr) {
			return createUserRequest{}, http.StatusRequestEntityTooLarge, "请求体过大"
		}
		return createUserRequest{}, http.StatusBadRequest, "请求体只能包含一个 JSON 值"
	}

	return in, http.StatusOK, ""
}

func handler(w http.ResponseWriter, r *http.Request) {
	in, status, message := decodeCreateUser(w, r)
	if message != "" {
		writeJSON(w, status, errorResponse{Error: message})
		return
	}
	writeJSON(w, http.StatusOK, in)
}

func runCase(name, baseURL, contentType, body string) {
	req, err := http.NewRequest(http.MethodPost, baseURL+"/users", strings.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", contentType)

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	data, readErr := io.ReadAll(resp.Body)
	closeErr := resp.Body.Close()
	if readErr != nil {
		panic(readErr)
	}
	if closeErr != nil {
		panic(closeErr)
	}
	fmt.Printf("%s: %d %s\n", name, resp.StatusCode, strings.TrimSpace(string(data)))
}

func main() {
	ln, err := net.Listen("tcp", "127.0.0.1:0")
	if err != nil {
		panic(err)
	}

	server := &http.Server{Handler: http.HandlerFunc(handler)}
	go func() {
		if err := server.Serve(ln); err != nil && !errors.Is(err, http.ErrServerClosed) {
			panic(err)
		}
	}()

	baseURL := "http://" + ln.Addr().String()
	runCase("valid", baseURL, "application/json; charset=utf-8", `{"name":"Ada","age":37}`)
	runCase("unknown", baseURL, "application/json", `{"name":"Ada","age":37,"role":"admin"}`)
	runCase("too-large", baseURL, "application/json", `{"name":"`+strings.Repeat("x", 80)+`","age":37}`)
	runCase("multiple", baseURL, "application/json", `{"name":"Ada","age":37} {"name":"Bob","age":40}`)
	runCase("wrong-type", baseURL, "text/plain", `{"name":"Ada","age":37}`)

	if err := server.Close(); err != nil {
		panic(err)
	}
}

预期输出

text
valid: 200 {"name":"Ada","age":37}
unknown: 400 {"error":"JSON 包含未知字段"}
too-large: 413 {"error":"请求体过大"}
multiple: 400 {"error":"请求体只能包含一个 JSON 值"}
wrong-type: 415 {"error":"Content-Type 必须是 application/json"}

随机监听端口只用于避免端口冲突,因此没有出现在输出中;实际部署时监听地址和端口应由配置管理,而不是写进请求解码逻辑。每次测试读取完响应后立即关闭响应体,也避免在连续请求场景中把连接资源一直留到函数返回。

正确认识严格模式的边界

DisallowUnknownFields 能防止客户端拼错字段名后仍被静默接受,但标准库通常只报告首先遇到的未知字段。若 API 希望一次返回全部字段问题,应在成功解码后进入独立验证层,不要让解码器承担完整的业务校验职责。

MaxBytesReader 限制的是读取字节数,不是 JSON 字符数;UTF-8 编码、空白和字段名都会计入上限。生产值应根据接口允许的最大有效载荷设置,并为正常请求留出合理余量。

如果公开 API 明确要求拒绝客户端拼错字段,严格未知字段策略很有价值;若协议刻意允许扩展字段,则是否启用严格模式应成为明确的版本兼容策略。

让错误响应保持可预测

解析层应在业务代码之前终止无效输入:媒体类型不支持返回 415,请求体超限返回 413,空请求体、JSON 语法或类型错误、未知字段以及额外 JSON 值返回 400。对外响应应使用稳定的错误类别,不直接暴露底层解析器的原始错误文本。

安全解码的核心不是“调用一次 Decode”,而是明确请求体是什么、最多多大、能包含哪些字段,并确认输入流中只有一个 JSON 值。完成这些边界检查后,再把结构体交给字段验证和业务逻辑。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安全解码 JSON 请求

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通