Go / 系统课时

解析请求参数与 JSON 正文

解析请求参数与 JSON 正文

这一课把一个 POST 接口的输入边界处理完整:读取查询参数、请求头和 JSON body,限制正文为 1 MiB,并把媒体类型错误、JSON 解码失败、字段缺失和超限分别转换为明确的 HTTP 状态码。

学习目标

  • 正确读取 URL.Query()、请求头与 JSON 正文。
  • 用 http.MaxBytesReader 限制请求体大小,并拒绝多余 JSON 内容。
  • 为 400、413、415、422 等不同输入错误返回可检查的结果。

先定义输入契约

示例接口为 POST /widgets?limit=10,要求请求头带 X-Request-ID,正文使用 application/json,字段为 name 与可选的 enabled。limit 默认 20,允许范围 1~100;JSON body 最大 1 MiB。

这些约束要在进入业务逻辑前一次性验证。否则,同一个坏请求可能在数据库层、业务层甚至日志里才暴露,状态码也会变得不稳定。

查询参数、请求头与 JSON 正文汇入校验链路

实现有上限的 JSON 解码

下面程序可直接运行。关键点是先用 http.MaxBytesReader 包装 r.Body,再创建 json.Decoder;DisallowUnknownFields() 会拒绝未声明字段,第二次 Decode 必须得到 io.EOF,从而拒绝连续发送两个 JSON 对象的请求。

go
package main

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

const maxBodyBytes = 1 << 20 // 1 MiB

type createWidgetRequest struct {
	Name    string `json:"name"`
	Enabled bool   `json:"enabled"`
}

type createWidgetResponse struct {
	Name      string `json:"name"`
	Enabled   bool   `json:"enabled"`
	Limit     int    `json:"limit"`
	RequestID string `json:"requestId"`
}

func writeError(w http.ResponseWriter, status int, message string) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)
	_ = json.NewEncoder(w).Encode(map[string]string{"error": message})
}

func createWidget(w http.ResponseWriter, r *http.Request) {
	limit := 20
	if raw := r.URL.Query().Get("limit"); raw != "" {
		n, err := strconv.Atoi(raw)
		if err != nil || n < 1 || n > 100 {
			writeError(w, http.StatusBadRequest, "limit must be an integer from 1 to 100")
			return
		}
		limit = n
	}

	requestID := strings.TrimSpace(r.Header.Get("X-Request-ID"))
	if requestID == "" {
		writeError(w, http.StatusBadRequest, "X-Request-ID is required")
		return
	}

	mediaType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
	if err != nil || mediaType != "application/json" {
		writeError(w, http.StatusUnsupportedMediaType, "Content-Type must be application/json")
		return
	}

	r.Body = http.MaxBytesReader(w, r.Body, maxBodyBytes)
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields()

	var input createWidgetRequest
	if err := dec.Decode(&input); err != nil {
		var maxErr *http.MaxBytesError
		if errors.As(err, &maxErr) {
			writeError(w, http.StatusRequestEntityTooLarge, "request body exceeds 1 MiB")
			return
		}
		writeError(w, http.StatusBadRequest, "invalid JSON body")
		return
	}

	if err := dec.Decode(&struct{}{}); err != io.EOF {
		writeError(w, http.StatusBadRequest, "body must contain exactly one JSON value")
		return
	}

	if strings.TrimSpace(input.Name) == "" {
		writeError(w, http.StatusUnprocessableEntity, "name is required")
		return
	}

	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	_ = json.NewEncoder(w).Encode(createWidgetResponse{
		Name:      input.Name,
		Enabled:   input.Enabled,
		Limit:     limit,
		RequestID: requestID,
	})
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /widgets", createWidget)

	log.Println("listening on http://127.0.0.1:8080")
	log.Fatal(http.ListenAndServe(":8080", mux))
}

预期输出(启动后,时间前缀会随环境变化):

text
<TIME> listening on http://127.0.0.1:8080

http.MaxBytesReader 的限制是字节数,不是 JSON 字符数;1 MiB 即 1,048,576 字节。若请求超过限制,解码会返回可识别的 *http.MaxBytesError,本例据此返回 413。

验证成功与失败分支

先发送一个合法请求。enabled 是布尔值,未提供时会保持 Go 的零值 false;limit=10 会覆盖默认值 20。

bash
curl -i -X POST 'http://127.0.0.1:8080/widgets?limit=10' -H 'Content-Type: application/json' -H 'X-Request-ID: req-001' -d '{"name":"demo","enabled":true}'

预期结果:

text
HTTP/1.1 201 Created
Content-Type: application/json
...
{"name":"demo","enabled":true,"limit":10,"requestId":"req-001"}

再验证一个缺失必填字段的请求:

bash
curl -i -X POST 'http://127.0.0.1:8080/widgets' -H 'Content-Type: application/json' -H 'X-Request-ID: req-002' -d '{"enabled":true}'

预期结果:

text
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
...
{"error":"name is required"}

响应中的 Date、Content-Length 等动态头可能不同,但状态码与 JSON 字段应一致。

把错误归到正确层级

查询参数格式错误、缺少请求头、JSON 语法错误或出现未知字段,都属于客户端请求无法按当前契约解析,本例返回 400。Content-Type 不是 application/json 返回 415;正文超过 1 MiB 返回 413;JSON 可解析但必填业务字段 name 为空时返回 422。

不要直接对未知大小的 r.Body 调用 io.ReadAll 再解码,这会让客户端决定服务端的内存消耗。也不要只调用一次 Decode 就认为请求结束,否则 {"name":"a"}{"name":"b"} 这类连续 JSON 值可能绕过“单一对象”的输入契约。

当接口进入真实业务层时,可以把已校验的 limit、requestID 和 createWidgetRequest 作为干净输入继续传递。这样后续服务不需要重复处理 HTTP 细节,错误状态码也能稳定地由边界层负责。

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

目录与阅读设置

阅读设置

17

记录一个想法

解析请求参数与 JSON 正文

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

登录哪都通