vault backup: 2026-04-28 08:53:28

2026-04-28 08:53:28 +08:00
parent 2df3748fc9
commit 8b07798991
23 changed files with 3349 additions and 39 deletions
@@ -0,0 +1,160 @@
+---
+tags: [后端, Go, Gin, 绑定, 校验, 安全性]
+create time: 2026-04-27 00:15
+---
+
+# ShouldBindJSON 未知字段处理
+
+## 概述
+
+Gin 的 `ShouldBindJSON` 默认对 JSON 中的未知字段（struct 没有对应 key）**静默忽略**，不会报错。这一行为是实际开发中隐藏 bug 的主要来源——拼写错误、多余字段都会被无声吞掉。本文介绍底层原理和三种开启严格模式的方法。
+
+思考题：如果前端把 `"name"` 误写成 `"nam"`，ShouldBindJSON 会怎么响应？handler 拿到的值是零值还是报错？
+
+## 正文
+
+### 1. 默认行为：静默忽略
+
+Gin 底层使用 Go 标准库 `encoding/json`，其 `Unmarshal` 对未知字段默认不报错：
+
+```go
+type UserReq struct {
+    Name string `json:"name"`
+}
+
+// 前端传入 {"name": "alice", "age": 25, "role": "admin"}
+var req UserReq
+c.ShouldBindJSON(&req) // ✅ 成功，req.Name = "alice"，"age" 和 "role" 被忽略
+```
+
+```mermaid
+flowchart LR
+    A["JSON Body"] --> B{"encoding/json.Unmarshal"}
+    B -->|"已知字段"| C["填入 struct"]
+    B -->|"未知字段"| D["静默丢弃 ⚠️"]
+    C --> E["返回 nil (成功)"]
+    D --> E
+```
+
+> **关键陷阱：** 前端字段拼写错误（如 `nam` 代替 `name`）不会被检测到，handler 拿到的是零值 `""`，后续业务逻辑可能因此出错却难以排查。
+
+### 2. 什么情况下会报错？
+
+注意，静默忽略仅限于**字段不存在**。以下情况仍会报错：
+
+| 场景 | 行为 | 原因 |
+|------|------|------|
+| 字段拼写错误（多/少字母） | 静默忽略，值为零值 | 视为新字段被丢弃 |
+| 类型不匹配（字符串给 int） | ❌ 解析失败 | 无法转换 |
+| Content-Type 不是 JSON | ❌ 400 Bad Request | Gin 内容类型检测 |
+| 缺少 required 字段 | ❌ 校验失败 | validator 拦截 |
+
+### 3. 方案一：手动 json.Decoder（推荐）
+
+最轻量、无需引入额外依赖的方式：
+
+```go
+func handler(c *gin.Context) {
+    var req CreateUserRequest
+
+    // 替换默认的 json.Unmarshal 为 Strict 模式的 Decoder
+    decoder := json.NewDecoder(c.Request.Body)
+    decoder.DisallowUnknownFields()
+    if err := decoder.Decode(&req); err != nil {
+        c.JSON(400, gin.H{
+            "code":    1003,
+            "message": "参数解析失败",
+            "error":   err.Error(),
+        })
+        return
+    }
+    // req 已包含所有已知字段的值
+}
+```
+
+**优点**：无需改动 Gin 全局配置，仅在当前 handler 生效，影响范围可控。  
+**缺点**：每个需要严格校验的 handler 都要重复写这段代码，可通过 middleware 封装复用。
+
+### 4. 方案二：全局替换 Gin 的 BindJSON
+
+通过重写 `gin.BindJSON` 接口，让所有 JSON 绑定都自动拒绝未知字段：
+
+```go
+import "github.com/gin-gonic/gin/binding"
+
+func init() {
+    // 保存原始的 BindJSON
+    original := binding.JSON.(binding.Binding)
+
+    // 替换为 Strict 版本
+    binding.JSON = &jsonBinding{Binding: original}
+}
+
+type jsonBinding struct {
+    binding.Binding
+}
+
+func (j *jsonBinding) Name() string { return "json" }
+
+func (j *jsonBinding) Bind(req *http.Request, obj interface{}) error {
+    if err := json.NewDecoder(req.Body).Decode(obj); err != nil {
+        return err
+    }
+    // 此处若需严格模式，应使用 DisallowUnknownFields 重新解码
+    _ = j.Binding // 保留原有逻辑引用
+    return nil
+}
+```
+
+> **注意**：直接改写全局 `gin.BindJSON` 会影响所有 handler，包括中间件内部使用的绑定。生产环境中更推荐使用方案一配合自定义中间件。
+
+### 5. 方案三：结构体级 UnmarshalJSON
+
+在单个结构体上实现 `UnmarshalJSON`，精确控制解析逻辑：
+
+```go
+func (r *CreateUserRequest) UnmarshalJSON(data []byte) error {
+    // 先用 map 接收全部字段
+    var raw map[string]interface{}
+    if err := json.Unmarshal(data, &raw); err != nil {
+        return err
+    }
+
+    // 白名单检查：遍历后合并已知字段名
+    knownFields := map[string]bool{
+        "name": true, "email": true, "age": true, "role": true,
+    }
+    for k := range raw {
+        if !knownFields[k] {
+            return fmt.Errorf("unknown field: %s", k)
+        }
+    }
+
+    // 通过 alias 绕过递归，再次反序列化到结构体
+    type Alias CreateUserRequest
+    return json.Unmarshal(data, (*Alias)(r))
+}
+```
+
+**优点**：细粒度控制，不同结构体可有不同的严格程度。  
+**缺点**：样板代码较多，维护成本高；每次都需要先读入 `map` 再二次解析，性能略差。
+
+### 6. 实践建议
+
+| 场景 | 推荐方案 |
+|------|---------|
+| 对外公开的 RESTful API | 方案一（Strict Decoder），防止客户端传参错误 |
+| 内部服务通信 | 默认行为即可，节省带宽和兼容性 |
+| 渐进式迁移（新增字段向前兼容） | 默认行为 + 监控日志记录未知字段 |
+| 需要结构化错误提示 | 方案一或方案三，配合错误分类返回友好消息 |
+
+```mermaid
+flowchart TD
+    A["收到 JSON 请求"] --> B{"是否对外开放 API?"}
+    B -->|"是"| C["启用 DisallowUnknownFields"]
+    B -->|"否 / 内部服务"| D["默认静默忽略"]
+    C --> E{"发现未知字段?"}
+    E -->|"是"| F["返回 400 + 详细错误"]
+    E -->|"否"| G["正常处理"]
+    D --> H["继续业务逻辑"]
+```