1. 课程导论：为什么需要参数校验、校验在REST API中的位置、课程目标与前置知识

1.1 为什么需要参数校验——从一次线上事故说起

假设你负责一个电商平台的用户注册接口 POST /api/v1/users。客户端传入以下 JSON 请求体：

{
  "email": "not-an-email",
  "age": -5,
  "phone": "abc123"
}

如果服务端不做任何参数校验，直接将这些数据写入数据库或传递给下游业务逻辑，可能引发以下连锁问题：

• 数据污染：无效邮箱、负数年龄进入数据库，导致后续查询、统计、报表全部异常。
• 安全漏洞：恶意用户通过超长字符串、SQL 注入、XSS 攻击绕过无校验的接口。
• 业务逻辑崩溃：下游服务收到非法参数后 panic、死锁或产生错误订单。
• 调试成本激增：问题在三天后暴露，需要从日志反查入口，定位困难。

1.2 参数校验在REST API中的位置

在标准的 REST API 请求处理流程中，参数校验处于 请求反序列化之后、业务逻辑执行之前 的关键位置。下面这张图展示了完整的请求生命周期：

从图中可以清晰看到：参数校验是 请求进入业务逻辑之前的最后一道闸门。一旦校验通过，数据将被视为“可信的”，直接参与核心业务处理。如果在这个位置缺失校验，所有下游环节都将暴露在风险中。

1.3 校验在Go Web框架中的典型位置

在 Go 语言的主流 Web 框架中，参数校验通常发生在 中间件层 或 Handler 函数入口处。以下是一个典型的 Gin 框架校验位置示例：

// 不推荐：校验与业务逻辑混在一起
func CreateUserHandler(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // 手动校验（散落在业务代码中）
    if req.Age < 0 || req.Age > 150 {
        c.JSON(400, gin.H{"error": "age must be between 0 and 150"})
        return
    }
    if !strings.Contains(req.Email, "@") {
        c.JSON(400, gin.H{"error": "invalid email"})
        return
    }
    // 业务逻辑...
}

// 推荐：使用结构体标签 + 校验库，集中管理
type CreateUserRequest struct {
    Email string `json:"email" binding:"required,email"`
    Age   int    `json:"age" binding:"gte=0,lte=150"`
    Phone string `json:"phone" binding:"required,len=11"`
}

func CreateUserHandler(c *gin.Context) {
    var req CreateUserRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(400, gin.H{"error": err.Error()})
        return
    }
    // 业务逻辑（此时参数已可信）
    // ...
}

1.4 课程目标与学习路径

本课程旨在帮助你构建一套 从请求入口到业务逻辑落地的完整参数校验体系。课程结束后，你将掌握以下能力：

1.5 前置知识要求

为了确保学习效果，建议你具备以下基础：

• Go 语言基础：熟悉结构体、接口、函数、错误处理、包管理（go mod）。
• HTTP 基础：了解 RESTful API 设计原则、HTTP 方法（GET/POST/PUT/DELETE）、状态码（200/400/404/500）。
• JSON 序列化：理解 json.Marshal / json.Unmarshal 以及结构体标签 json:"field_name"。
• 至少一个 Web 框架基础：Gin、Echo、Fiber、Chi 中的任意一个（课程以 Gin 为主，但原理通用）。

1.6 课程内容全景图

下面这张图展示了本课程 20 章的知识结构，帮助你建立全局视角：

1.7 本章小结

• 参数校验是 REST API 的守门员：它位于请求反序列化之后、业务逻辑之前，防止无效数据污染系统。
• Go 语言中推荐使用结构体标签 + 校验库：将校验规则声明化，与业务逻辑解耦。
• 本课程覆盖从基础到实战的完整路径：20 章内容，从工具使用到工程落地，最终完成一个可投入生产的校验体系。
• 前置知识要求不高：具备 Go 基础、HTTP 基础和任意 Web 框架入门经验即可开始学习。