阶段2(上):后端专题 Go/Gin/PostgreSQL/MySQL/Redis/MQ/gRPC 的课程、企业场景、面试题和可运行示例
This commit is contained in:
1 parent
0bae9916a9
commit
5eb67c5d08
65 files changed
+6457
-77
No files matched your search
@@ -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 状态码。
|
||||
@@ -0,0 +1,114 @@
|
||||
---
|
||||
id: backend.gin.middleware-auth
|
||||
title: 中间件、JWT 鉴权和统一错误处理
|
||||
type: lesson
|
||||
domain: backend
|
||||
stack: [gin]
|
||||
tags: [Gin, 中间件, JWT, 鉴权, 错误处理]
|
||||
level: intermediate
|
||||
prerequisites: [backend.gin.routing-binding, backend.go.errors-concurrency]
|
||||
est_hours: 3
|
||||
related: [backend.gin.scenario.unified-api-response, backend.gin.interview]
|
||||
week: [2, 3]
|
||||
order: 2
|
||||
---
|
||||
|
||||
# 中间件、JWT 鉴权和统一错误处理
|
||||
|
||||
## 解释说明
|
||||
|
||||
- **中间件**就是一个 `gin.HandlerFunc`,在处理函数前后执行公共逻辑:日志、恢复 panic、跨域、鉴权、限流、请求 ID。和 Koa / Express 的洋葱模型一样:`c.Next()` 之前是“进入”,之后是“返回”;`c.Abort()` 终止后续处理函数(当前函数还会继续执行到结束,所以 Abort 后要 return)。
|
||||
- **注册范围**:`r.Use(...)` 全局;`group.Use(...)` 只对一组路由;也可以写在单个路由上。
|
||||
- **在中间件之间传值**:`c.Set("userID", id)` / `c.GetString("userID")`;跨到 service 层时,放进 `context.Context` 传递。
|
||||
- **JWT 鉴权**:登录成功后签发令牌(包含用户 ID `sub`、过期时间 `exp`),之后每次请求带 `Authorization: Bearer <token>`。中间件校验签名和过期时间,**必须指定允许的签名算法**,防止“算法替换”攻击。
|
||||
- **统一错误处理**:业务代码返回带错误码的错误,由一个地方转换成统一的响应格式,避免每个处理函数自己拼 JSON、格式不一致。
|
||||
|
||||
## 案例
|
||||
|
||||
企业后台的公共要求:所有接口返回 `{code, message, data, request_id}`;未登录 401、无权限 403、参数错误 400 都有固定的业务错误码;出问题时客服把 `request_id` 发给开发,开发在日志里一搜就能找到完整的请求记录。下一节的场景文档给出了完整设计。
|
||||
|
||||
## 代码示例
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"errors"
|
||||
"log"
|
||||
"net/http"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/golang-jwt/jwt/v5"
|
||||
)
|
||||
|
||||
var secret = []byte("dev-only-secret-change-me-at-least-32-bytes")
|
||||
|
||||
func Sign(userID string, ttl time.Duration) (string, error) {
|
||||
claims := jwt.RegisteredClaims{Subject: userID, ExpiresAt: jwt.NewNumericDate(time.Now().Add(ttl))}
|
||||
return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(secret)
|
||||
}
|
||||
|
||||
// Auth 校验 Bearer 令牌,把用户 ID 放进上下文
|
||||
func Auth() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
raw, ok := strings.CutPrefix(c.GetHeader("Authorization"), "Bearer ")
|
||||
if !ok {
|
||||
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"code": 40100, "message": "请先登录"})
|
||||
return
|
||||
}
|
||||
var claims jwt.RegisteredClaims
|
||||
_, err := jwt.ParseWithClaims(raw, &claims, func(*jwt.Token) (any, error) { return secret, nil },
|
||||
jwt.WithValidMethods([]string{"HS256"}), jwt.WithExpirationRequired())
|
||||
if err != nil {
|
||||
msg := "令牌无效"
|
||||
if errors.Is(err, jwt.ErrTokenExpired) {
|
||||
msg = "登录已过期"
|
||||
}
|
||||
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"code": 40101, "message": msg})
|
||||
return
|
||||
}
|
||||
c.Set("userID", claims.Subject)
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
|
||||
// Timing 演示“洋葱模型”:Next 之前和之后都能执行代码
|
||||
func Timing() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
start := time.Now()
|
||||
c.Next() // 执行后面的中间件和处理函数
|
||||
log.Printf("%s %s %d %v", c.Request.Method, c.FullPath(), c.Writer.Status(), time.Since(start))
|
||||
}
|
||||
}
|
||||
|
||||
func main() {
|
||||
r := gin.New()
|
||||
r.Use(gin.Recovery(), Timing())
|
||||
r.POST("/login", func(c *gin.Context) {
|
||||
token, _ := Sign("u1", 2*time.Hour)
|
||||
c.JSON(http.StatusOK, gin.H{"token": token})
|
||||
})
|
||||
authed := r.Group("/api", Auth())
|
||||
authed.GET("/me", func(c *gin.Context) {
|
||||
c.JSON(http.StatusOK, gin.H{"user_id": c.GetString("userID")})
|
||||
})
|
||||
_ = r.Run(":8080")
|
||||
}
|
||||
```
|
||||
|
||||
完整的“统一响应 + 错误码 + 请求 ID”实现和测试见 [examples/unified-api](examples/unified-api/)。
|
||||
|
||||
## 易错点
|
||||
|
||||
- **`Abort` 后不 return**:当前中间件后面的代码还会执行。
|
||||
- **不指定签名算法**:攻击者可能把算法改成 `none` 或用公钥当 HMAC 密钥;用 `jwt.WithValidMethods` 限定。
|
||||
- **密钥写死在代码里**:从环境变量读取,长度至少 32 字节,不同环境不同密钥。
|
||||
- **在 `c.Next()` 之后改响应头**:处理函数已经写出响应时,再设置头部不会生效;需要在写响应前设置。
|
||||
- **在 goroutine 里直接用 `c`**:请求结束后 `gin.Context` 会被复用,后台 goroutine 要用 `c.Copy()`。
|
||||
- **令牌无法主动失效**:JWT 是无状态的,退出登录、改密码后旧令牌仍有效;需要短有效期 + 刷新令牌,或服务端维护令牌版本号 / 黑名单。
|
||||
|
||||
## 面试常问
|
||||
|
||||
见 [Gin 面试题](interview.md):中间件执行顺序、JWT 和 Session 的区别、令牌失效方案。
|
||||
@@ -0,0 +1,185 @@
|
||||
// Package unifiedapi 演示企业后台接口规范:统一响应、业务错误码、请求 ID、参数校验中文提示、panic 兜底。
|
||||
package unifiedapi
|
||||
|
||||
import (
|
||||
"crypto/rand"
|
||||
"encoding/hex"
|
||||
"errors"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"reflect"
|
||||
"strings"
|
||||
"sync"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
"github.com/gin-gonic/gin/binding"
|
||||
"github.com/go-playground/validator/v10"
|
||||
)
|
||||
|
||||
// AppError 业务错误:HTTP 状态码 + 业务错误码 + 给用户看的提示
|
||||
type AppError struct {
|
||||
Status int
|
||||
Code int
|
||||
Message string
|
||||
}
|
||||
|
||||
func (e *AppError) Error() string { return e.Message }
|
||||
|
||||
var (
|
||||
ErrNotFound = &AppError{http.StatusNotFound, 40400, "资源不存在"}
|
||||
ErrInternal = &AppError{http.StatusInternalServerError, 50000, "服务器开小差了,请稍后再试"}
|
||||
)
|
||||
|
||||
func Invalid(msg string) *AppError { return &AppError{http.StatusBadRequest, 40000, msg} }
|
||||
|
||||
// Body 统一响应格式
|
||||
type Body struct {
|
||||
Code int `json:"code"`
|
||||
Message string `json:"message"`
|
||||
Data any `json:"data"`
|
||||
RequestID string `json:"request_id"`
|
||||
}
|
||||
|
||||
func OK(c *gin.Context, status int, data any) {
|
||||
c.JSON(status, Body{Code: 0, Message: "ok", Data: data, RequestID: c.GetString("requestID")})
|
||||
}
|
||||
|
||||
func writeErr(c *gin.Context, e *AppError) {
|
||||
c.AbortWithStatusJSON(e.Status, Body{Code: e.Code, Message: e.Message, RequestID: c.GetString("requestID")})
|
||||
}
|
||||
|
||||
// RequestID 沿用客户端传来的 X-Request-ID,没有就生成一个,并写回响应头
|
||||
func RequestID() gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
id := c.GetHeader("X-Request-ID")
|
||||
if id == "" || len(id) > 64 {
|
||||
b := make([]byte, 8)
|
||||
_, _ = rand.Read(b)
|
||||
id = hex.EncodeToString(b)
|
||||
}
|
||||
c.Set("requestID", id)
|
||||
c.Header("X-Request-ID", id)
|
||||
c.Next()
|
||||
}
|
||||
}
|
||||
|
||||
// Errors 统一把处理函数里 c.Error(err) 记录的错误和 panic 转成统一响应;内部错误不把细节暴露给用户
|
||||
func Errors(log *slog.Logger) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
defer func() {
|
||||
if r := recover(); r != nil {
|
||||
log.Error("panic", "request_id", c.GetString("requestID"), "panic", r)
|
||||
writeErr(c, ErrInternal)
|
||||
}
|
||||
}()
|
||||
c.Next()
|
||||
if len(c.Errors) == 0 || c.Writer.Written() {
|
||||
return
|
||||
}
|
||||
err := c.Errors.Last().Err
|
||||
var ae *AppError
|
||||
if errors.As(err, &ae) {
|
||||
writeErr(c, ae)
|
||||
return
|
||||
}
|
||||
log.Error("internal error", "request_id", c.GetString("requestID"), "err", err)
|
||||
writeErr(c, ErrInternal)
|
||||
}
|
||||
}
|
||||
|
||||
var setupOnce sync.Once
|
||||
|
||||
// useJSONFieldNames 让校验错误里显示 JSON 字段名(title)而不是结构体字段名(Title)
|
||||
func useJSONFieldNames() {
|
||||
if v, ok := binding.Validator.Engine().(*validator.Validate); ok {
|
||||
v.RegisterTagNameFunc(func(f reflect.StructField) string {
|
||||
name := strings.Split(f.Tag.Get("json"), ",")[0]
|
||||
if name == "" || name == "-" {
|
||||
return f.Name
|
||||
}
|
||||
return name
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// Bind 解析并校验 JSON,失败时记录一个用户能看懂的错误
|
||||
func Bind(c *gin.Context, req any) bool {
|
||||
err := c.ShouldBindJSON(req)
|
||||
if err == nil {
|
||||
return true
|
||||
}
|
||||
var ve validator.ValidationErrors
|
||||
if errors.As(err, &ve) {
|
||||
msgs := make([]string, 0, len(ve))
|
||||
for _, fe := range ve {
|
||||
switch fe.Tag() {
|
||||
case "required":
|
||||
msgs = append(msgs, fmt.Sprintf("%s 不能为空", fe.Field()))
|
||||
case "max":
|
||||
msgs = append(msgs, fmt.Sprintf("%s 长度不能超过 %s", fe.Field(), fe.Param()))
|
||||
case "oneof":
|
||||
msgs = append(msgs, fmt.Sprintf("%s 只能是 %s 之一", fe.Field(), fe.Param()))
|
||||
default:
|
||||
msgs = append(msgs, fmt.Sprintf("%s 不合法", fe.Field()))
|
||||
}
|
||||
}
|
||||
_ = c.Error(Invalid(strings.Join(msgs, ";")))
|
||||
} else {
|
||||
_ = c.Error(Invalid("请求体格式错误"))
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
type Task struct {
|
||||
ID int `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Priority string `json:"priority"`
|
||||
}
|
||||
|
||||
type CreateTask struct {
|
||||
Title string `json:"title" binding:"required,max=50"`
|
||||
Priority string `json:"priority" binding:"omitempty,oneof=low normal high"`
|
||||
}
|
||||
|
||||
// New 组装路由
|
||||
func New(log *slog.Logger) *gin.Engine {
|
||||
setupOnce.Do(useJSONFieldNames)
|
||||
var mu sync.Mutex
|
||||
tasks := map[int]Task{}
|
||||
next := 1
|
||||
|
||||
r := gin.New()
|
||||
r.Use(RequestID(), Errors(log))
|
||||
api := r.Group("/api")
|
||||
api.POST("/tasks", func(c *gin.Context) {
|
||||
var req CreateTask
|
||||
if !Bind(c, &req) {
|
||||
return
|
||||
}
|
||||
mu.Lock()
|
||||
t := Task{ID: next, Title: req.Title, Priority: req.Priority}
|
||||
tasks[t.ID] = t
|
||||
next++
|
||||
mu.Unlock()
|
||||
OK(c, http.StatusCreated, t)
|
||||
})
|
||||
api.GET("/tasks/:id", func(c *gin.Context) {
|
||||
var id int
|
||||
if _, err := fmt.Sscan(c.Param("id"), &id); err != nil {
|
||||
_ = c.Error(Invalid("id 必须是整数"))
|
||||
return
|
||||
}
|
||||
mu.Lock()
|
||||
t, ok := tasks[id]
|
||||
mu.Unlock()
|
||||
if !ok {
|
||||
_ = c.Error(ErrNotFound)
|
||||
return
|
||||
}
|
||||
OK(c, http.StatusOK, t)
|
||||
})
|
||||
api.GET("/boom", func(c *gin.Context) { panic("数据库连接串 postgres://secret 泄漏测试") })
|
||||
api.GET("/db-error", func(c *gin.Context) { _ = c.Error(errors.New("pq: relation \"tasks\" does not exist")) })
|
||||
return r
|
||||
}
|
||||
@@ -0,0 +1,68 @@
|
||||
package unifiedapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"log/slog"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/gin-gonic/gin"
|
||||
)
|
||||
|
||||
func do(t *testing.T, r http.Handler, method, path, body string, hdr map[string]string) (int, Body, http.Header) {
|
||||
t.Helper()
|
||||
req := httptest.NewRequest(method, path, strings.NewReader(body))
|
||||
req.Header.Set("Content-Type", "application/json")
|
||||
for k, v := range hdr {
|
||||
req.Header.Set(k, v)
|
||||
}
|
||||
w := httptest.NewRecorder()
|
||||
r.ServeHTTP(w, req)
|
||||
var b Body
|
||||
if err := json.Unmarshal(w.Body.Bytes(), &b); err != nil {
|
||||
t.Fatalf("响应不是统一格式:%s", w.Body.String())
|
||||
}
|
||||
return w.Code, b, w.Header()
|
||||
}
|
||||
|
||||
func TestUnifiedResponses(t *testing.T) {
|
||||
gin.SetMode(gin.TestMode)
|
||||
r := New(slog.New(slog.NewTextHandler(io.Discard, nil)))
|
||||
|
||||
cases := []struct {
|
||||
name, method, path, body string
|
||||
status, code int
|
||||
msgContains string
|
||||
}{
|
||||
{"创建成功", "POST", "/api/tasks", `{"title":"写周报","priority":"high"}`, 201, 0, "ok"},
|
||||
{"必填校验", "POST", "/api/tasks", `{"title":""}`, 400, 40000, "title 不能为空"},
|
||||
{"枚举校验", "POST", "/api/tasks", `{"title":"a","priority":"urgent"}`, 400, 40000, "priority 只能是 low normal high 之一"},
|
||||
{"JSON 格式错误", "POST", "/api/tasks", `{"title":`, 400, 40000, "请求体格式错误"},
|
||||
{"查询存在", "GET", "/api/tasks/1", "", 200, 0, "ok"},
|
||||
{"查询不存在", "GET", "/api/tasks/999", "", 404, 40400, "资源不存在"},
|
||||
{"panic 兜底", "GET", "/api/boom", "", 500, 50000, "服务器开小差"},
|
||||
{"内部错误不泄漏细节", "GET", "/api/db-error", "", 500, 50000, "服务器开小差"},
|
||||
}
|
||||
for _, c := range cases {
|
||||
t.Run(c.name, func(t *testing.T) {
|
||||
status, b, h := do(t, r, c.method, c.path, c.body, nil)
|
||||
if status != c.status || b.Code != c.code || !strings.Contains(b.Message, c.msgContains) {
|
||||
t.Fatalf("got %d %+v", status, b)
|
||||
}
|
||||
if b.RequestID == "" || h.Get("X-Request-ID") != b.RequestID {
|
||||
t.Fatalf("缺少请求 ID:%+v", b)
|
||||
}
|
||||
if strings.Contains(b.Message, "secret") || strings.Contains(b.Message, "relation") {
|
||||
t.Fatal("内部错误细节泄漏给了用户")
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
_, b, _ := do(t, r, "GET", "/api/tasks/1", "", map[string]string{"X-Request-ID": "trace-123"})
|
||||
if b.RequestID != "trace-123" {
|
||||
t.Fatalf("应沿用客户端的请求 ID,得到 %q", b.RequestID)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,39 @@
|
||||
module example/unifiedapi
|
||||
|
||||
go 1.26.0
|
||||
|
||||
require (
|
||||
github.com/gin-gonic/gin v1.12.0
|
||||
github.com/go-playground/validator/v10 v10.30.5
|
||||
)
|
||||
|
||||
require (
|
||||
github.com/bytedance/gopkg v0.1.3 // indirect
|
||||
github.com/bytedance/sonic v1.15.0 // indirect
|
||||
github.com/bytedance/sonic/loader v0.5.0 // indirect
|
||||
github.com/cloudwego/base64x v0.1.6 // indirect
|
||||
github.com/gabriel-vasile/mimetype v1.4.15 // indirect
|
||||
github.com/gin-contrib/sse v1.1.0 // indirect
|
||||
github.com/go-playground/locales v0.14.1 // indirect
|
||||
github.com/go-playground/universal-translator v0.18.1 // indirect
|
||||
github.com/goccy/go-json v0.10.5 // indirect
|
||||
github.com/goccy/go-yaml v1.19.2 // indirect
|
||||
github.com/json-iterator/go v1.1.12 // indirect
|
||||
github.com/klauspost/cpuid/v2 v2.3.0 // indirect
|
||||
github.com/leodido/go-urn v1.5.0 // indirect
|
||||
github.com/mattn/go-isatty v0.0.20 // indirect
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
|
||||
github.com/modern-go/reflect2 v1.0.2 // indirect
|
||||
github.com/pelletier/go-toml/v2 v2.2.4 // indirect
|
||||
github.com/quic-go/qpack v0.6.0 // indirect
|
||||
github.com/quic-go/quic-go v0.59.0 // indirect
|
||||
github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
|
||||
github.com/ugorji/go/codec v1.3.1 // indirect
|
||||
go.mongodb.org/mongo-driver/v2 v2.5.0 // indirect
|
||||
golang.org/x/arch v0.22.0 // indirect
|
||||
golang.org/x/crypto v0.57.0 // indirect
|
||||
golang.org/x/net v0.58.0 // indirect
|
||||
golang.org/x/sys v0.48.0 // indirect
|
||||
golang.org/x/text v0.42.0 // indirect
|
||||
google.golang.org/protobuf v1.36.10 // indirect
|
||||
)
|
||||
@@ -0,0 +1,89 @@
|
||||
github.com/bytedance/gopkg v0.1.3 h1:TPBSwH8RsouGCBcMBktLt1AymVo2TVsBVCY4b6TnZ/M=
|
||||
github.com/bytedance/gopkg v0.1.3/go.mod h1:576VvJ+eJgyCzdjS+c4+77QF3p7ubbtiKARP3TxducM=
|
||||
github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uSE=
|
||||
github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
|
||||
github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
|
||||
github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
|
||||
github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
|
||||
github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
|
||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/gabriel-vasile/mimetype v1.4.15 h1:05iP/CYtZ/w455R/KZM6rZ5ieAdh99UPtd+d3YzLmaI=
|
||||
github.com/gabriel-vasile/mimetype v1.4.15/go.mod h1:azpTcoLcDZRNgFou5j+APrqQx9HqVPWa6ijYQIIVswQ=
|
||||
github.com/gin-contrib/sse v1.1.0 h1:n0w2GMuUpWDVp7qSpvze6fAu9iRxJY4Hmj6AmBOU05w=
|
||||
github.com/gin-contrib/sse v1.1.0/go.mod h1:hxRZ5gVpWMT7Z0B0gSNYqqsSCNIJMjzvm6fqCz9vjwM=
|
||||
github.com/gin-gonic/gin v1.12.0 h1:b3YAbrZtnf8N//yjKeU2+MQsh2mY5htkZidOM7O0wG8=
|
||||
github.com/gin-gonic/gin v1.12.0/go.mod h1:VxccKfsSllpKshkBWgVgRniFFAzFb9csfngsqANjnLc=
|
||||
github.com/go-playground/assert/v2 v2.2.0 h1:JvknZsQTYeFEAhQwI4qEt9cyV5ONwRHC+lYKSsYSR8s=
|
||||
github.com/go-playground/assert/v2 v2.2.0/go.mod h1:VDjEfimB/XKnb+ZQfWdccd7VUvScMdVu0Titje2rxJ4=
|
||||
github.com/go-playground/locales v0.14.1 h1:EWaQ/wswjilfKLTECiXz7Rh+3BjFhfDFKv/oXslEjJA=
|
||||
github.com/go-playground/locales v0.14.1/go.mod h1:hxrqLVvrK65+Rwrd5Fc6F2O76J/NuW9t0sjnWqG1slY=
|
||||
github.com/go-playground/universal-translator v0.18.1 h1:Bcnm0ZwsGyWbCzImXv+pAJnYK9S473LQFuzCbDbfSFY=
|
||||
github.com/go-playground/universal-translator v0.18.1/go.mod h1:xekY+UJKNuX9WP91TpwSH2VMlDf28Uj24BCp08ZFTUY=
|
||||
github.com/go-playground/validator/v10 v10.30.5 h1:YyCXvVShZbs2Sm3Mb53eNOlhRXctSOzW5QJAouCTZL4=
|
||||
github.com/go-playground/validator/v10 v10.30.5/go.mod h1:wEqiaov48pXX1kjhc3Da8y0M0Dtg/BK7gurFBLgwFrQ=
|
||||
github.com/goccy/go-json v0.10.5 h1:Fq85nIqj+gXn/S5ahsiTlK3TmC85qgirsdTP/+DeaC4=
|
||||
github.com/goccy/go-json v0.10.5/go.mod h1:oq7eo15ShAhp70Anwd5lgX2pLfOS3QCiwU/PULtXL6M=
|
||||
github.com/goccy/go-yaml v1.19.2 h1:PmFC1S6h8ljIz6gMRBopkjP1TVT7xuwrButHID66PoM=
|
||||
github.com/goccy/go-yaml v1.19.2/go.mod h1:XBurs7gK8ATbW4ZPGKgcbrY1Br56PdM69F7LkFRi1kA=
|
||||
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
|
||||
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
|
||||
github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
|
||||
github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
|
||||
github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
|
||||
github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
|
||||
github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
|
||||
github.com/leodido/go-urn v1.5.0 h1:pLqT2kq1zpHW/1D18QMjMpdtX7cekxqtJJjg5ANyWw0=
|
||||
github.com/leodido/go-urn v1.5.0/go.mod h1:9BORnCDhdPBJNDEX+w1bJisa8yOKYi116VeO96s4ifE=
|
||||
github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
|
||||
github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
|
||||
github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
|
||||
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
|
||||
github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
|
||||
github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
|
||||
github.com/pelletier/go-toml/v2 v2.2.4 h1:mye9XuhQ6gvn5h28+VilKrrPoQVanw5PMw/TB0t5Ec4=
|
||||
github.com/pelletier/go-toml/v2 v2.2.4/go.mod h1:2gIqNv+qfxSVS7cM2xJQKtLSTLUE9V8t9Stt+h56mCY=
|
||||
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
|
||||
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
|
||||
github.com/quic-go/qpack v0.6.0 h1:g7W+BMYynC1LbYLSqRt8PBg5Tgwxn214ZZR34VIOjz8=
|
||||
github.com/quic-go/qpack v0.6.0/go.mod h1:lUpLKChi8njB4ty2bFLX2x4gzDqXwUpaO1DP9qMDZII=
|
||||
github.com/quic-go/quic-go v0.59.0 h1:OLJkp1Mlm/aS7dpKgTc6cnpynnD2Xg7C1pwL6vy/SAw=
|
||||
github.com/quic-go/quic-go v0.59.0/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
|
||||
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
|
||||
github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
|
||||
github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
|
||||
github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
|
||||
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
|
||||
github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
|
||||
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
|
||||
github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
|
||||
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
|
||||
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
|
||||
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
|
||||
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
|
||||
github.com/ugorji/go/codec v1.3.1 h1:waO7eEiFDwidsBN6agj1vJQ4AG7lh2yqXyOXqhgQuyY=
|
||||
github.com/ugorji/go/codec v1.3.1/go.mod h1:pRBVtBSKl77K30Bv8R2P+cLSGaTtex6fsA2Wjqmfxj4=
|
||||
go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
|
||||
go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
|
||||
go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
|
||||
go.uber.org/mock v0.6.0/go.mod h1:KiVJ4BqZJaMj4svdfmHM0AUx4NJYO8ZNpPnZn1Z+BBU=
|
||||
golang.org/x/arch v0.22.0 h1:c/Zle32i5ttqRXjdLyyHZESLD/bB90DCU1g9l/0YBDI=
|
||||
golang.org/x/arch v0.22.0/go.mod h1:dNHoOeKiyja7GTvF9NJS1l3Z2yntpQNzgrjh1cU103A=
|
||||
golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M=
|
||||
golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA=
|
||||
golang.org/x/net v0.58.0 h1:ynWG7rqYi4ccpTEuPZ2QGWHktVEM9DMCj9yzDE0Q7To=
|
||||
golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU=
|
||||
golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
|
||||
golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
|
||||
golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
|
||||
golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
|
||||
golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
|
||||
google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
|
||||
google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
|
||||
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
@@ -4,12 +4,37 @@ title: Gin Web 框架
|
||||
type: index
|
||||
domain: backend
|
||||
stack: [gin]
|
||||
tags: []
|
||||
tags: [Go, Gin, REST, 中间件]
|
||||
week: [1, 2, 3]
|
||||
---
|
||||
|
||||
# Gin Web 框架
|
||||
|
||||
路由、参数绑定、中间件、鉴权、统一错误处理。
|
||||
Gin 是 Go 里使用最广的 Web 框架之一:在标准库 `net/http` 之上提供了高性能路由、参数绑定和校验、中间件链。学会 Gin,看懂其他 Go 框架(Echo、Fiber、Hertz)也很快。
|
||||
|
||||
> 本专题建设中:课程、企业场景、面试题和示例代码会陆续补充。
|
||||
## 学习路线
|
||||
|
||||
| 顺序 | 课程 | 级别 | 预计 |
|
||||
| --- | --- | --- | --- |
|
||||
| 1 | [路由、参数绑定和校验](01-routing-binding.md) | 基础 | 3 小时 |
|
||||
| 2 | [中间件、JWT 鉴权和统一错误处理](02-middleware-auth.md) | 进阶 | 3 小时 |
|
||||
|
||||
## 企业场景
|
||||
|
||||
- [企业后台接口规范:统一响应、错误码、请求 ID 和参数校验](scenarios/unified-api-response.md)
|
||||
|
||||
## 面试题
|
||||
|
||||
- [Gin 面试题](interview.md)
|
||||
|
||||
## 示例代码
|
||||
|
||||
- [examples/unified-api](examples/unified-api/):统一响应 + 错误码 + 请求 ID + 参数校验中文提示 + panic 兜底 + 测试(`go test ./...`)
|
||||
|
||||
## 在 16 周计划中
|
||||
|
||||
- [第 1 周](../../../plan/week01-go-gin.md)(Gin 接口)、[第 2 周](../../../plan/week02-db-auth.md)(JWT 鉴权)、[第 3 周](../../../plan/week03-project1.md)(权限、限流中间件)
|
||||
|
||||
## 官方资料
|
||||
|
||||
- Gin 文档(中文):https://gin-gonic.com/zh-cn/docs/ ;参数校验 validator:https://github.com/go-playground/validator
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
id: backend.gin.interview
|
||||
title: Gin 面试题
|
||||
type: interview
|
||||
domain: backend
|
||||
stack: [gin]
|
||||
tags: [Gin, Web, 面试]
|
||||
level: intermediate
|
||||
related: [backend.gin.routing-binding, backend.gin.middleware-auth, backend.gin.scenario.unified-api-response]
|
||||
week: [1, 2, 3, 16]
|
||||
---
|
||||
|
||||
# Gin 面试题
|
||||
|
||||
> 在本计划里的体现:`todo-api`(第 1~2 周)、`task-board`(第 3 周)。
|
||||
|
||||
## 基础
|
||||
|
||||
### 【基础】Gin 和标准库 net/http 是什么关系?
|
||||
|
||||
**参考答案**:Gin 的 `Engine` 实现了 `http.Handler` 接口,底层仍然由 `net/http` 负责监听和连接管理。Gin 增加了基于前缀树的高性能路由、`gin.Context`(封装请求和响应、参数获取、绑定、中间件间传值)、中间件链和常用工具(JSON 渲染、校验)。所以 Gin 可以和任何标准库中间件、`httptest` 一起使用。
|
||||
|
||||
### 【基础】Gin 怎么获取路径参数、查询参数和请求体?
|
||||
|
||||
**参考答案**:路径参数 `c.Param("id")`;查询参数 `c.Query("k")` / `c.DefaultQuery("k", "默认")`;请求体用绑定 `c.ShouldBindJSON(&req)`,查询参数也可以 `c.ShouldBindQuery(&q)` 绑定到结构体。绑定时根据结构体的 `binding` 标签做校验。
|
||||
|
||||
**追问**:`ShouldBind` 和 `Bind` 的区别?→ `Bind*` 失败时自动返回 400 并中止,`ShouldBind*` 只返回错误、由你决定如何响应,一般统一用后者。
|
||||
|
||||
### 【基础】中间件的执行顺序是怎样的?`c.Next()` 和 `c.Abort()` 做什么?
|
||||
|
||||
**参考答案**:按注册顺序依次执行,形成洋葱模型:`c.Next()` 之前的代码按顺序执行,之后的代码按相反顺序执行。`c.Next()` 立即执行后续的处理函数;`c.Abort()` 阻止后续处理函数执行,但当前函数会继续执行完,所以通常 `Abort` 后紧跟 `return`。
|
||||
|
||||
### 【基础】RESTful 接口的状态码怎么选?
|
||||
|
||||
**参考答案**:查询成功 200、创建成功 201、删除成功 204、参数错误 400、未认证 401、已认证但无权限 403、不存在 404、状态冲突(如重复创建)409、请求过多 429、服务器错误 500、下游不可用 502/503。
|
||||
|
||||
## 进阶
|
||||
|
||||
### 【进阶】JWT 和 Session 有什么区别?JWT 怎么实现退出登录?
|
||||
|
||||
**参考答案**:Session 把登录状态存在服务端(内存或 Redis),客户端只拿一个 Session ID,服务端可以随时让它失效,但需要共享存储。JWT 把用户信息签名后交给客户端,服务端只验签,无状态、易扩展,但签发后在过期前一直有效。退出登录 / 改密码的方案:短有效期访问令牌(如 15 分钟)+ 刷新令牌;服务端维护用户的令牌版本号或黑名单(存 Redis),校验时比对。
|
||||
|
||||
**追问**:令牌存 localStorage 还是 Cookie?→ localStorage 怕 XSS 窃取;httpOnly Cookie 防 XSS 但要防 CSRF(SameSite、CSRF Token)。
|
||||
|
||||
### 【进阶】为什么在 goroutine 里使用 gin.Context 要先 `c.Copy()`?
|
||||
|
||||
**参考答案**:Gin 用对象池复用 `Context`,请求处理结束后它会被重置给下一个请求使用。如果后台 goroutine 还持有原来的 `c`,读到的可能是别的请求的数据。`c.Copy()` 生成只读副本。更好的做法是只把需要的值(用户 ID、请求 ID、`c.Request.Context()` 派生的 context)传给后台任务。
|
||||
|
||||
### 【进阶】如何设计统一的错误处理?
|
||||
|
||||
**参考答案**:定义业务错误类型(HTTP 状态 + 业务码 + 用户提示),处理函数通过 `c.Error(err)` 记录错误并返回,由一个错误中间件统一转换成标准响应;未知错误和 panic 统一返回通用提示,详细信息带请求 ID 写日志。详见本技术栈的场景文档。
|
||||
|
||||
### 【进阶】Gin 的路由为什么快?
|
||||
|
||||
**参考答案**:Gin 使用 httprouter 风格的前缀树(radix tree),每个 HTTP 方法一棵树,按路径公共前缀压缩存储,匹配时间与路径长度相关,基本不受路由数量影响;同时 `Context` 用对象池减少内存分配。
|
||||
|
||||
## 场景题
|
||||
|
||||
### 【场景题】接口被恶意刷,怎么在 Gin 里做限流?
|
||||
|
||||
**参考答案**:单实例用令牌桶(`golang.org/x/time/rate`),按用户 ID 或 IP 维护一个限流器 map(注意定期清理);多实例部署需要全局限流,用 Redis(固定窗口 `INCR+EXPIRE` 或滑动窗口 ZSet、Lua 脚本保证原子)。超限返回 429 并带 `Retry-After`。更外层可以在 Nginx 或网关做 IP 级限流,应用层做用户级、接口级限流。本计划第 3 周项目一实现过。
|
||||
|
||||
### 【场景题】一个上传接口偶尔导致服务内存暴涨,怎么处理?
|
||||
|
||||
**参考答案**:限制请求体大小(`http.MaxBytesReader` 或 Gin 的 `MaxMultipartMemory`,Nginx 的 `client_max_body_size`);大文件流式处理而不是一次读入内存;校验文件类型和大小;上传改成前端直传对象存储(预签名 URL),后端只接收回调。
|
||||
|
||||
### 【场景题】怎么给 Gin 服务写接口测试?
|
||||
|
||||
**参考答案**:把路由组装放在一个函数里(如 `New(deps) *gin.Engine`),测试时注入内存版依赖;用 `httptest.NewRecorder()` 和 `r.ServeHTTP(w, req)` 直接调用,不启动端口;用表格驱动覆盖成功、参数错误、未登录、无权限、不存在、内部错误等情况;数据库相关的用集成测试单独跑。示例见 [examples/unified-api](examples/unified-api/)。
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
id: backend.gin.scenario.unified-api-response
|
||||
title: 企业后台接口规范:统一响应、错误码、请求 ID 和参数校验
|
||||
type: scenario
|
||||
domain: backend
|
||||
stack: [gin, go]
|
||||
tags: [接口规范, 错误码, 请求ID, 可观测性, 参数校验]
|
||||
level: intermediate
|
||||
prerequisites: [backend.gin.middleware-auth]
|
||||
est_hours: 2
|
||||
related: [backend.gin.interview]
|
||||
week: [2, 3]
|
||||
---
|
||||
|
||||
# 企业后台接口规范:统一响应、错误码、请求 ID 和参数校验
|
||||
|
||||
## 业务背景与问题
|
||||
|
||||
一个内部管理系统由 4 个后端同事开发,半年后接口风格五花八门:有的返回 `{"error": "..."}`,有的返回 `{"msg": "...", "status": -1}`;参数错误有时 400 有时 200;数据库报错原文直接返回给前端(暴露了表名);用户反馈“提交失败”时,开发只能根据时间点大海捞针地翻日志。前端为每个接口单独写错误处理,维护成本高。
|
||||
|
||||
## 约束
|
||||
|
||||
- 不能一次性重写所有接口,要能逐步迁移。
|
||||
- 前端需要稳定的结构:成功、业务失败、系统错误能用同一套代码处理。
|
||||
- 安全要求:内部错误信息(SQL、堆栈、连接串)不能返回给用户。
|
||||
- 运维要求:任何一次失败都能通过一个 ID 在日志里找到完整链路。
|
||||
|
||||
## 方案设计
|
||||
|
||||
**响应格式**(HTTP 状态码表达大类,`code` 表达具体业务原因):
|
||||
|
||||
```json
|
||||
{"code": 0, "message": "ok", "data": {"id": 1}, "request_id": "a1b2c3d4e5f60718"}
|
||||
{"code": 40000, "message": "title 不能为空", "data": null, "request_id": "..."}
|
||||
```
|
||||
|
||||
**错误码规则**:5 位数字,前 3 位对应 HTTP 状态码,后 2 位是业务细分。例如 40000 参数错误、40100 未登录、40101 登录过期、40300 无权限、40400 资源不存在、40900 状态冲突、50000 系统错误。错误码在一个文件里集中定义,并生成文档给前端。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as 前端
|
||||
participant RID as RequestID 中间件
|
||||
participant ERR as Errors 中间件
|
||||
participant H as 处理函数
|
||||
FE->>RID: 请求(可带 X-Request-ID)
|
||||
RID->>ERR: 设置 request_id,写回响应头
|
||||
ERR->>H: c.Next()
|
||||
H-->>ERR: c.Error(AppError) 或 panic 或 成功响应
|
||||
ERR-->>FE: 统一格式;内部错误只返回“服务器开小差”,详细信息写日志(带 request_id)
|
||||
```
|
||||
|
||||
**职责划分**:
|
||||
|
||||
1. `RequestID` 中间件:沿用网关或前端传入的 ID(便于跨服务追踪),没有就生成。
|
||||
2. 处理函数:只做“绑定参数 → 调用 service → 成功响应 / `c.Error(err)`”,不自己拼错误 JSON。
|
||||
3. `Errors` 中间件:把 `AppError` 转成对应响应;未知错误和 panic 统一转成 50000,详细信息只写日志。
|
||||
4. 校验错误翻译成中文、用 JSON 字段名,前端可以直接展示。
|
||||
5. **逐步迁移**:新接口直接用新规范;旧接口在网关层或前端适配层兼容,按模块逐步改造。
|
||||
|
||||
## 关键代码
|
||||
|
||||
完整实现和 8 个测试用例见 [examples/unified-api](../examples/unified-api/)。核心是错误中间件:
|
||||
|
||||
```go
|
||||
func Errors(log *slog.Logger) gin.HandlerFunc {
|
||||
return func(c *gin.Context) {
|
||||
defer func() {
|
||||
if r := recover(); r != nil {
|
||||
log.Error("panic", "request_id", c.GetString("requestID"), "panic", r)
|
||||
writeErr(c, ErrInternal)
|
||||
}
|
||||
}()
|
||||
c.Next()
|
||||
if len(c.Errors) == 0 || c.Writer.Written() {
|
||||
return
|
||||
}
|
||||
err := c.Errors.Last().Err
|
||||
var ae *AppError
|
||||
if errors.As(err, &ae) {
|
||||
writeErr(c, ae) // 业务错误:提示语是写给用户看的
|
||||
return
|
||||
}
|
||||
log.Error("internal error", "request_id", c.GetString("requestID"), "err", err)
|
||||
writeErr(c, ErrInternal) // 未知错误:不暴露细节
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 取舍
|
||||
|
||||
- **HTTP 状态码 + 业务码 vs 全部返回 200**:全部 200 的做法前端处理简单,但网关监控、浏览器缓存、重试策略都依赖 HTTP 状态码。本方案两者都给:状态码表达大类,业务码表达细节。
|
||||
- **错误码集中定义**:增加一点流程成本(新增错误码要登记),换来前后端一致和可生成文档。
|
||||
- **请求 ID 自己生成 vs 接入链路追踪(OpenTelemetry)**:先用请求 ID 解决 80% 的排查问题,后续接入追踪时把 trace ID 作为请求 ID 即可,接口格式不变。
|
||||
|
||||
## 易错点
|
||||
|
||||
- 处理函数里既 `c.JSON` 又 `c.Error`,中间件里要判断 `c.Writer.Written()`,否则会写两次响应。
|
||||
- `panic` 恢复后要记录堆栈(`debug.Stack()`),否则很难定位。
|
||||
- 请求 ID 来自客户端时要限制长度和字符,防止日志注入。
|
||||
- 错误提示里拼接用户输入,要注意不要把敏感数据回显。
|
||||
- 不同服务的错误码冲突:多服务时按服务分段(例如前两位是服务编号)。
|
||||
|
||||
## 面试怎么讲
|
||||
|
||||
> “我们后台接口曾经格式不统一、错误信息直接暴露 SQL、排查问题要翻很久日志。我定了统一响应格式和 5 位业务错误码,用两个中间件实现:一个生成或透传请求 ID,一个统一把业务错误、未知错误和 panic 转成标准响应,内部错误只给用户友好提示、细节带着请求 ID 写日志。校验错误翻译成中文直接给前端展示。新接口直接用,旧接口逐步迁移。之后用户报错只要提供请求 ID,就能在日志里一次定位。”
|
||||
|
||||
可能的追问:错误码怎么管理和生成文档?多个微服务之间请求 ID 怎么传递(HTTP 头透传、gRPC metadata)?为什么不全部返回 200?
|
||||
Reference in new issue
Block a user