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 解码
下面程序可直接运行。关键点是先用 http.MaxBytesReader 包装 r.Body,再创建 json.Decoder;DisallowUnknownFields() 会拒绝未声明字段,第二次 Decode 必须得到 io.EOF,从而拒绝连续发送两个 JSON 对象的请求。
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))
}预期输出(启动后,时间前缀会随环境变化):
<TIME> listening on http://127.0.0.1:8080http.MaxBytesReader 的限制是字节数,不是 JSON 字符数;1 MiB 即 1,048,576 字节。若请求超过限制,解码会返回可识别的 *http.MaxBytesError,本例据此返回 413。
验证成功与失败分支
先发送一个合法请求。enabled 是布尔值,未提供时会保持 Go 的零值 false;limit=10 会覆盖默认值 20。
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}'预期结果:
HTTP/1.1 201 Created
Content-Type: application/json
...
{"name":"demo","enabled":true,"limit":10,"requestId":"req-001"}再验证一个缺失必填字段的请求:
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}'预期结果:
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 细节,错误状态码也能稳定地由边界层负责。