Files

114 lines
4.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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 状态码。