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 值,最后再进入字段校验和业务处理。

Content-Type 可能带参数,例如 application/json; charset=utf-8,因此不能用字符串完全相等判断;应先用 mime.ParseMediaType 取得主媒体类型。请求体上限则要在解码前通过 http.MaxBytesReader 生效,避免先读入内存再补做长度检查。
用一个主示例覆盖关键失败路径
下面的程序启动一个只监听本机随机端口的 HTTP 服务,再由同一进程发送五类请求。这样能验证真实 net/http 读写链路,同时避免把端口写死。示例只负责安全解码,不把字段必填或业务规则混入解析层。
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)
}
}预期输出
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 值。完成这些边界检查后,再把结构体交给字段验证和业务逻辑。