阶段2(上):后端专题 Go/Gin/PostgreSQL/MySQL/Redis/MQ/gRPC 的课程、企业场景、面试题和可运行示例

This commit is contained in:
Shikui Wang committed 2026-10-23 15:24:57 +08:00
1 parent 0bae9916a9
commit 5eb67c5d08
65 files changed
+6457 -77

No files matched your search

+113
View File
@@ -0,0 +1,113 @@
---
id: backend.gin.routing-binding
title: 路由、参数绑定和校验
type: lesson
domain: backend
stack: [gin]
tags: [Gin, 路由, 参数校验, REST]
level: basic
prerequisites: [backend.go.basics-types]
est_hours: 3
related: [backend.gin.middleware-auth, backend.gin.interview]
week: [1]
order: 1
---
# 路由、参数绑定和校验
## 解释说明
- **路由**:`r.GET("/tasks/:id", handler)`,`:id` 是路径参数,`*path` 是通配。用 `r.Group("/api")` 给一组路由加公共前缀和中间件。Gin 的路由是前缀树(radix tree),匹配速度和路由数量关系不大。
- **取参数**:路径参数 `c.Param("id")`;查询参数 `c.Query("page")` / `c.DefaultQuery("page", "1")`;请求体用**绑定**。
- **绑定和校验**:定义结构体,用标签声明来源和规则,`c.ShouldBindJSON(&req)` 一步完成解析和校验(底层是 go-playground/validator):
| 标签 | 含义 |
| --- | --- |
| `json:"title"` | JSON 字段名 |
| `form:"page"` | 查询参数 / 表单字段名(配合 `ShouldBindQuery`) |
| `binding:"required,max=100"` | 必填、最大长度 100 |
| `binding:"omitempty,oneof=todo doing done"` | 可选,有值时必须是其中之一 |
| `binding:"gte=1,lte=100"` | 数字范围 |
- **响应**:`c.JSON(状态码, 数据)`;写完响应后要 `return`,否则后面的代码还会执行。
- **RESTful 约定**:资源用名词复数(`/tasks`),动作用 HTTP 方法;创建返回 201,删除成功返回 204,参数错误 400,未登录 401,无权限 403,不存在 404,冲突 409。
## 案例
任务列表接口要支持分页和状态筛选:`GET /api/tasks?page=2&size=20&status=done`。查询参数绑定到结构体,校验 `size` 不超过 100(防止一次拉太多数据拖垮数据库),`status` 只允许固定几个值。
## 代码示例
```go
package main
import (
"net/http"
"strconv"
"github.com/gin-gonic/gin"
)
type ListQuery struct {
Page int `form:"page,default=1" binding:"gte=1"`
Size int `form:"size,default=20" binding:"gte=1,lte=100"`
Status string `form:"status" binding:"omitempty,oneof=todo doing done"`
}
type CreateTask struct {
Title string `json:"title" binding:"required,max=100"`
Note string `json:"note" binding:"max=1000"`
}
func main() {
r := gin.Default() // 自带 Logger 和 Recovery 中间件
api := r.Group("/api")
{
api.GET("/tasks", func(c *gin.Context) {
var q ListQuery
if err := c.ShouldBindQuery(&q); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return // 一定要 return
}
c.JSON(http.StatusOK, gin.H{"page": q.Page, "size": q.Size, "status": q.Status, "items": []string{}})
})
api.POST("/tasks", func(c *gin.Context) {
var req CreateTask
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
return
}
c.JSON(http.StatusCreated, gin.H{"id": 1, "title": req.Title})
})
api.GET("/tasks/:id", func(c *gin.Context) {
id, err := strconv.Atoi(c.Param("id"))
if err != nil || id <= 0 {
c.JSON(http.StatusBadRequest, gin.H{"error": "id 必须是正整数"})
return
}
c.JSON(http.StatusOK, gin.H{"id": id})
})
}
_ = r.Run(":8080")
}
```
试一试:
```bash
curl 'localhost:8080/api/tasks?size=500' # 400:size 超过 100
curl -X POST localhost:8080/api/tasks -d '{"title":""}' -H 'Content-Type: application/json' # 400:title 必填
curl -X POST localhost:8080/api/tasks -d '{"title":"学 Gin"}' -H 'Content-Type: application/json' # 201
```
## 易错点
- **写完响应不 return**:后面的代码继续执行,可能再次写响应,日志出现 `headers were already written`。
- **`BindJSON` 和 `ShouldBindJSON`**:前者校验失败会自动写 400 且之后不能改状态码,统一用 `ShouldBind*` 自己处理。
- **请求体只能读一次**:中间件里读过 `c.Request.Body`,后面再绑定会是空的;需要多次读用 `c.ShouldBindBodyWith`。
- **校验错误直接返回给前端**:原始错误信息是英文、带结构体字段名,生产环境要转换成友好的提示(见下一课的统一错误处理)。
- **路由冲突**:`/tasks/:id` 和 `/tasks/new` 这类静态和参数路由的组合,不同版本的 Gin 处理不同,设计路由时尽量避免歧义。
## 面试常问
见 [Gin 面试题](interview.md):路由原理、绑定和校验、RESTful 状态码。