// Created At 2026-09-01
// Go · PostgreSQL · ORM

GORM 入门实战:用 Gin + GORM 写一个图书管理 API

开始之前

适合已经会 Go 基础语法、想从零跑通一个 GORM 项目的读者。动手前确认三件事:

  • Go 1.22+(本教程用到 errors.Is;推荐 1.24+)
  • 本地 PostgreSQL(没有就 Docker:docker run --name pg -e POSTGRES_PASSWORD=123456 -p 5432:5432 -d postgres:16)
  • 手动建库:CREATE DATABASE library;——AutoMigrate 只能建表,不能建库

换 MySQL / SQLite 也可以,代码跨库通用,差别只在驱动与 DSN(见第一章)。但第 2 篇起会用到 PostgreSQL 专属特性(ILIKE、按主键分组的函数依赖、部分唯一索引),差异会在用到处就地标注。

项目结构先平铺,业务复杂后再演进(见第 6 篇):

gin-demo/
├── main.go           # 入口文件
├── db/
│   └── db.go         # 数据库连接
├── models/
│   └── book.go       # 数据模型
├── handlers/
│   └── book.go       # 业务逻辑(CRUD)
└── go.mod

为什么平铺? db / models / handlers 三个包足够跑通,也方便逐章对照;用 internal/ + Service / Repository 分层是《工程化(一)》的事。

先建立心智模型

GORM 最不一样的对手不是 Spring/Django,而是 JDBC/MyBatis 这类手写 SQL 的路子:后者要你拼 SQL、再把结果集一行行映射成对象,GORM 恰好反过来。

一句话总纲: Gin 把「HTTP 请求」变成「Go 函数调用」,GORM 把「Go 结构体」翻译成「数据库 SQL」。主线只有一条:请求进来 → 装进结构体 → 交给 GORM → 结果填回结构体 → 返回 JSON。

不是写 SQL,是操作结构体

你只描述意图(Create、Find、Updates、Delete),翻译成 SQL 是框架的事。想确认它生成了什么 SQL,开 GORM 日志就能看到。

四个必须建立的心智

  1. 结构体一物三用:同一个 struct 既是表结构(gorm 标签)、又是请求/响应载体(json 标签)、还是数据库操作的参数(&book)。类型即契约,改一处全联动。
  2. 查数据是「填空」,不是「返回值」:Find(&books)、First(&book, id) 必须传目标变量的指针,GORM 靠反射填进去;漏写 & 等于填了个副本,函数外拿不到。ShouldBindJSON(&x)、Delete(&models.Book{})、AutoMigrate(&models.Book{}) 同理——要往里填、或要对象本身,都得传地址。反过来,*gorm.DB / *gin.Context 这种指针类型声明表示「引用同一个实例、不拷贝」,*string / *int 表示「可能没传」(nil)。
  3. 零值即「未提供」:Updates(结构体) 按零值(0、""、false)判断要不要更新,所以把字段改成 0 会被静默跳过。第七章的零值陷阱根就在这里。
  4. 错误是结果的一部分:Go 没有异常,每次操作返回 result,错误要看 result.Error、影响行数看 result.RowsAffected。

软删除:框架改写 SQL 的又一个例子

第八章的 Delete 不会真的删除数据——GORM 把它改写成「软删除」,删掉的记录以后也不会再出现在查询里。机制留到第八章,先记住:别指望 Delete 一定生成 DELETE 语句。

本篇只到单表 CRUD;评论与分页、封面上传、请求 DTO、标签关联、分层与可靠性,依次在后续篇目展开。

第一章:项目初始化

建目录、初始化模块:

mkdir gin-demo
cd gin-demo
go mod init gin-demo

安装依赖:

go get github.com/gin-gonic/gin
go get gorm.io/gorm
go get gorm.io/driver/postgres

go get 会解析最新的兼容版本。教程不用 go get -u——-u 会连坐升级所有间接依赖,没必要。

换数据库就换驱动与 DSN:

数据库 驱动 DSN
PostgreSQL go get gorm.io/driver/postgres host=localhost user=postgres password=123456 dbname=library sslmode=disable
MySQL go get gorm.io/driver/mysql user:pass@tcp(localhost:3306)/library?charset=utf8mb4&parseTime=True
SQLite go get gorm.io/driver/sqlite ./data.db

第二章:连接数据库

启动时调用 db.InitDB():拼出 DSN,用 gorm.Open 建立连接,成功后返回 *gorm.DB 供其他包使用;失败直接退出。

DSN 就是一行 key=value:host / port / user / password / dbname,本地开发再加 sslmode=disable(生产要开 SSL)。

创建 db/db.go:

package db

import (
    "fmt"
    "log"

    "gorm.io/driver/postgres"
    "gorm.io/gorm"
)

var DB *gorm.DB

func InitDB() {
    host := "localhost"
    port := 5432
    user := "postgres"
    password := "123456"
    dbname := "library"

    dsn := fmt.Sprintf("host=%s port=%d user=%s password=%s dbname=%s sslmode=disable",
        host, port, user, password, dbname)

    var err error
    DB, err = gorm.Open(postgres.Open(dsn), &gorm.Config{})
    if err != nil {
        log.Fatal("数据库连接失败:", err)
    }
    log.Println("数据库连接成功")
}

⚠️ 生产环境请用环境变量管理敏感配置,不要硬编码——配套仓库用 DATABASE_DSN 覆盖整个 DSN,验证/测试靠它切到另一套库。

注意: PostgreSQL 要手动建库;AutoMigrate 能自动建表但不能建库;sslmode=disable 仅限本地开发。

第三章:定义数据模型

创建 models/book.go,用一个结构体描述表:

package models

import "gorm.io/gorm"

type Book struct {
    gorm.Model
    Title  string `json:"title" gorm:"not null"`
    Author string `json:"author" gorm:"not null"`
    Price  int    `json:"price" gorm:"not null;check:price >= 0"` // 单位:分(5990 表示 59.90 元)
}
  • gorm.Model:内置 ID、CreatedAt、UpdatedAt、DeletedAt 四个字段
  • gorm:"not null":对应数据库的 NOT NULL 约束
  • gorm:"check:price >= 0":数据库级 CHECK,负数直接写不进去(校验不能只靠 DTO)
  • json:"title":指定 JSON 序列化时的字段名,响应体里也用它

三个新手最容易忽略的点:

  • gorm.Model 的字段在 JSON 里是大写原名:它没有 json 标签,所以响应里是 "ID"、"DeletedAt": null。想统一命名就用自定义字段声明或 DTO(见第十章「响应精简」)。
  • 金额统一用 int(单位:分):浮点数有精度误差(0.1 + 0.2 != 0.3),price: 5990 表示 59.90 元,前端需要”元”时自行除以 100。
  • binding:"required" 加在 DTO 上,不加在模型上:模型会被创建、更新等多个接口复用,各接口的必填规则并不相同,钉死在模型上就会把合法请求拦成 400(第五章会用一次)。

命名规则:

  • 类型名用单数 Book(Go 惯例);表名由 GORM 自动复数化成 books,写成 Books 没有任何数据库上的收益。文件名随意,本教程统一用 book.go。
  • 同一个字段在三个层有三个名字:Go 字段 PascalCase、数据库列 snake_case(GORM 自动转换)、JSON camelCase(json: 标签)。改列名用 gorm:"column:...",改 JSON 名用 json: 标签,两个开关各管各的。
  • 需要自定义表名时加一行:func (Book) TableName() string { return "my_books" }。

第四章:自动迁移

在 main.go 里建表(此时还没有路由):

func main() {
    db.InitDB()

    if err := db.DB.AutoMigrate(&models.Book{}); err != nil {
        log.Fatal("迁移失败:", err)
    }

    // ... 服务与路由见第九章
}
  • 只加不删:不删列,也不撤销已有约束——去掉 not null 标签列仍是 NOT NULL,换关联的 OnDelete 行为已有外键也不会变;约束变更要显式迁移(db.Migrator().DropConstraint() / 手写 SQL)
  • 字段的 size、precision、可空性变化时,GORM 会尝试改列类型
  • 重命名字段等于新增一列;要改名用 db.Migrator().RenameColumn()

先看公式:CRUD 的统一流程

第五到第八章的五个 handler 是同一套流程的实例化。六步骨架:

  1. 抓参数:id := c.Param("id") 或 c.Query("keyword")
  2. 绑请求:c.ShouldBindJSON(&xxx),失败直接 400
  3. 查存在:db.DB.First(&xxx, id),查无记录(errors.Is 命中 gorm.ErrRecordNotFound)→ 404
  4. 做操作:Create / Find / Updates / Delete——每次操作都返回 result
  5. 验结果:非「查无记录」的 result.Error → 500;RowsAffected == 0 → 404
  6. 回响应:c.JSON(200/201, ...)

每章都是公式的一个实例:

操作 抓参数 绑请求 查存在 做操作 验结果 响应
POST /books – ✓ – Create Error → 500 201
GET /books – – – Find Error → 500 200
GET /books/:id ✓ – First → 404 – ErrRecordNotFound → 404 200
PUT /books/:id ✓ ✓ First → 404 Updates Error → 500 200
DELETE /books/:id ✓ – – Delete Error → 500;RowsAffected=0 → 404 200

两个和其他框架最不一样的地方:

  • Gin 的数据入口只有一个 *gin.Context:路径参数、查询参数、请求体都从它身上拿,没有控制器类,一个函数签名通吃所有请求。
  • GORM 每一步都返回同一个 result:*gorm.DB 既是链式调用的承接者,也是 Error 和 RowsAffected 的载体——这就是心智模型 4 在 API 层的落点。

另外,本篇所有 db 调用都链上请求上下文:db.DB.WithContext(c.Request.Context()).Xxx(...)(原因见第五章)。

第五章:创建图书

第六、七、八章的 CRUD 函数都追加到同一个文件 handlers/book.go,文件头统一为:

package handlers

import (
    "errors"
    "gin-demo/db"
    "gin-demo/models"
    "net/http"

    "github.com/gin-gonic/gin"
    "gorm.io/gorm"
)

第一个接口,创建图书:

// CreateBook 创建图书(POST /books)
func CreateBook(c *gin.Context) {
    var book models.Book

    // 1. 绑定 JSON 请求体
    if err := c.ShouldBindJSON(&book); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "请发送合法的 JSON"})
        return
    }

    // 2. 插入数据库
    result := db.DB.WithContext(c.Request.Context()).Create(&book)
    if result.Error != nil {
        _ = c.Error(result.Error) // 具体错误进日志,客户端只看统一文案
        c.JSON(http.StatusInternalServerError, gin.H{"error": "创建失败"})
        return
    }

    // 3. 返回创建的数据(这就是「结构体一物三用」:请求装进来、DB 插进去、原样返回)
    c.JSON(http.StatusCreated, book)
}

500 之前那行 _ = c.Error(result.Error) 是干什么的? 它把具体错误交给 Gin:gin.Default() 里的 Logger 中间件会把 c.Errors 拼进访问日志(日志行末尾的 Error #01: ...),而 HTTP 响应仍只给客户端一句统一文案——原因进日志,细节不外泄。c.Error 本身返回 error(只在 c.Errors 装满或传的不是 error 时才非 nil),所以用 _ 丢掉返回值;本篇其余 handler 的 500 分支都照这一行办,生产环境再换成 slog + 统一错误中间件(见第七篇)。

⚠️ 路由到第九章才注册。建议先跳到第九章把 main.go 抄下来跑起服务,再回头逐章测试第五~八章的接口。

测试:

curl -X POST http://localhost:8080/books \
  -H "Content-Type: application/json" \
  -d '{"title":"Go语言实战","author":"张三","price":5990}'

响应示例(注意键名大小写):

{
  "ID": 1,
  "CreatedAt": "2026-09-05T13:05:46+08:00",
  "UpdatedAt": "2026-09-05T13:05:46+08:00",
  "DeletedAt": null,
  "title": "Go语言实战",
  "author": "张三",
  "price": 5990
}

ID / CreatedAt / DeletedAt 大写是 gorm.Model 没有 json 标签导致的(见第三章);title / author / price 是我们自己用 tag 定义的。

请求校验:用 DTO 收请求

上一版不校验任何东西——{"price":5990}(没有 title / author)也能插库成功。那只是为了让「请求 → 结构体 → 数据库」这条线先跑通;真实接口不能这样上线。校验不是锦上添花,而是接口契约的一部分,并且它属于收请求的结构,不属于 models.Book:

第一步:定义请求结构(DTO),放在 handlers/book.go 里、CreateBook 上方(小写够用;将来要跨包引用再改成导出的 CreateBookInput):

// createBookInput:创建图书专用的请求结构(DTO),校验标签只属于它
type createBookInput struct {
    Title  string `json:"title" binding:"required"`
    Author string `json:"author" binding:"required"`
    Price  int    `json:"price" binding:"gte=0"`
}

第二步:把原来的「绑定 → 入库」两步换掉。 只定义 DTO 而不换绑定目标,代码一个字都不会变——缺字段照样插库成功:

var input createBookInput // 原来是 var book models.Book
if err := c.ShouldBindJSON(&input); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": "请发送合法的 JSON(title、author 必填,price 不能为负)"})
    return
}
book := models.Book{Title: input.Title, Author: input.Author, Price: input.Price} // DTO → 模型
result := db.DB.WithContext(c.Request.Context()).Create(&book)                    // 之后照旧

为什么不写 Create(&input)? input 是 DTO、book 是模型:模型嵌了 gorm.Model(主键、时间戳、软删),以后还会多出 cover_path 这类不归客户端管的列。这行「翻译」是刻意的安全检查——只有写进 models.Book{...} 的字段才会落库(客户端多传的键为什么必须挡在门外,见第七章的 ⚠️)。校验错误翻译、更新 DTO 等完整实践见《数据工程实战》。

为什么不在 models.Book 上加 binding:"required"? 模型会被多个接口复用:创建要全量、更新的入参各不相同,钉死在模型上,凡是只需要部分字段的接口都会被 400 拦下。模型管数据库结构与 JSON 命名,校验是接口契约、属于请求结构。

改完后缺字段才真的走 400:

# 400(原代码这里是 201);传完整字段 → 201,响应与章首示例一致
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8080/books \
  -H "Content-Type: application/json" -d '{"price":5990}'

为什么必须带 Context

WithContext(ctx) 把 Go 的 context.Context 挂到本次查询链上;执行时它会贯穿 database/sql → 数据库驱动,成为取消与超时的信号来源。

c.Request.Context() 的生命周期绑定在请求上:客户端断开连接时它会被取消。带上它,查询会随之中断、连接归还连接池而不是挂死;不带的裸写法(db.DB.Create(&book))也能跑,但对请求生命周期毫无感知。

所以本篇所有 db 调用都写成 db.DB.WithContext(c.Request.Context()).Xxx(...)。服务端防慢查询的超时中间件在第九章的 main.go 里;超时后 GORM 返回 context.DeadlineExceeded,会走 500,生产环境可映射成 504(见第 7 篇)。

第六章:查询图书

两个查询接口:

// GetBooks 查询所有图书(GET /books)
func GetBooks(c *gin.Context) {
    books := []models.Book{} // 空切片而非 nil:表为空时 JSON 输出 [],而不是 null
    result := db.DB.WithContext(c.Request.Context()).Find(&books)
    if result.Error != nil {
        _ = c.Error(result.Error)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
        return
    }
    c.JSON(http.StatusOK, books)
}

// GetBook 查询单条图书(GET /books/:id)
func GetBook(c *gin.Context) {
    id := c.Param("id")

    var book models.Book
    result := db.DB.WithContext(c.Request.Context()).First(&book, id)
    if errors.Is(result.Error, gorm.ErrRecordNotFound) {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }
    if result.Error != nil {
        _ = c.Error(result.Error)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
        return
    }

    c.JSON(http.StatusOK, book)
}

测试:

curl http://localhost:8080/books
curl http://localhost:8080/books/1

为什么 First 的检查分两层? 查无记录时 GORM 返回 gorm.ErrRecordNotFound,用 errors.Is 精确命中它才返回 404;数据库断开这类错误落到 500,不会误报成”图书不存在”。GetBooks 用 []models.Book{} 而非 var books []models.Book,因为后者在空表时输出 null 而不是 []。

第七章:更新图书

// UpdateBook 更新图书(PUT /books/:id)
func UpdateBook(c *gin.Context) {
    id := c.Param("id")

    // 1. 检查图书是否存在(和第六章 GetBook 是同一套两层检查——这次自己写出来)
    var book models.Book
    result := db.DB.WithContext(c.Request.Context()).First(&book, id)
    if errors.Is(result.Error, gorm.ErrRecordNotFound) {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }
    if result.Error != nil {
        _ = c.Error(result.Error)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
        return
    }

    // 2. 绑定 JSON 请求体
    var input models.Book
    if err := c.ShouldBindJSON(&input); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "请发送合法的 JSON"})
        return
    }

    // 3. 更新字段(WHERE 由上方 First 决定;只写 input 里的非零字段——见心智模型 3)
    result = db.DB.WithContext(c.Request.Context()).Model(&book).Updates(input)
    if result.Error != nil {
        _ = c.Error(result.Error)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "更新失败"})
        return
    }

    // 4. 返回更新后的数据(GORM 把本次改动的字段回写 book;没改的字段保持上方 First 加载的值)
    c.JSON(http.StatusOK, book)
}

PUT 还是 PATCH?

PUT 严格语义是「整体替换」,部分更新该用 PATCH。下一节会把更新实现成真正的整体替换,所以这里用 PUT 是对的;若以后想把接口改成部分更新(只改客户端传了的字段),那是另一套写法,本篇不展开(见《数据工程实战》§2.2)。

零值陷阱

心智模型 3 的直接后果:{"price":0} 会被静默跳过,”把价格改成 0”做不到。根源不在 GORM,而在绑定那一层:非指针字段收 JSON 时,”没传”和”传了零值”落进同一个 0——GORM 拿到的是「值」,不是「意图」。

本篇只给一条写法:把接口做成真正的整体替换(PUT),用 Select 列出参与更新的列。 PUT 的语义本来就是「整体替换」,零值自然是合法值,于是不需要指针——列出的列零值照写,白名单还顺带堵住批量赋值(替换上面 UpdateBook 的第 2、3 步,第 1 步查存在不动;result 已在第 1 步声明,这里用 = 续上):

type updateBookInput struct { // PUT 要求全量提交,所以 required 在这里是合理的
    Title  string `json:"title" binding:"required"`
    Author string `json:"author" binding:"required"`
    Price  int    `json:"price" binding:"gte=0,lte=1000000"`
}

var in updateBookInput
if err := c.ShouldBindJSON(&in); err != nil {
    c.JSON(http.StatusBadRequest, gin.H{"error": "请发送合法的 JSON(title、author 必填)"})
    return
}
result = db.DB.WithContext(c.Request.Context()).Model(&book).
    Select("title", "author", "price"). // 列出的列零值照写,同时就是白名单
    Updates(models.Book{Title: in.Title, Author: in.Author, Price: in.Price})
-- 传 {"title":"","author":"新作者","price":0} 时生成的 SQL(GORM v1.31.2 实测)
UPDATE `books` SET `title`="",`author`="新作者",`price`=0,`updated_at`="..." WHERE ... AND `id` = 1

代价是 PUT 语义本身要求的:客户端漏传 title 等于「清空标题」,不是「不改」——所以 required 必须加。这条写法只适用于 PUT;如果这个接口本质上是部分更新(「没传就不动」),那是另一套写法,本篇不展开,见《数据工程实战》§2.2。

⚠️ 别把模型当请求体。 var input models.Book 直接拿模型收请求,而 JSON 绑定不区分大小写:{"deletedAt":"2026-01-01T00:00:00Z"} 能把书软删、{"coverUrl":"/uploads/x.jpg"} 能绕过上传接口改封面——等于开放了批量赋值。修法就是 DTO:收什么和存什么是两件事。本篇保留模型版本只为让零值陷阱看得见。

测试:

# PUT 全量替换:0 真的写进去了
curl -X PUT http://localhost:8080/books/1 -H "Content-Type: application/json" \
  -d '{"title":"","author":"新作者","price":0}'

第八章:删除图书

因为 Book 使用了 gorm.Model,GORM 默认执行软删除:记录不真正移除,只是 deleted_at 被设为当前时间,查询时默认被过滤掉。

// DeleteBook 软删除图书(DELETE /books/:id)
func DeleteBook(c *gin.Context) {
    id := c.Param("id")

    // 执行软删除
    result := db.DB.WithContext(c.Request.Context()).Delete(&models.Book{}, id)
    if result.Error != nil { // 先验错误,再判行数——顺序不能反
        _ = c.Error(result.Error)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "删除失败"})
        return
    }
    if result.RowsAffected == 0 {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }

    c.JSON(http.StatusOK, gin.H{"message": "删除成功"})
}

软删除行为解析

GORM 实际执行的是 UPDATE ... SET deleted_at=NOW() WHERE id=? AND deleted_at IS NULL:

操作 GORM 行为
第一次 DELETE 设置 deleted_at = NOW(),不再出现在查询中
再次 DELETE 同一条 由于 deleted_at IS NOT NULL,GORM 找不到记录,RowsAffected == 0,返回”图书不存在”

软删除后,默认的 First / Find 会自动加上 deleted_at IS NULL;要查已删除的记录,用 db.DB.WithContext(c.Request.Context()).Unscoped().First(&book, id)。

软删只动自己这一行:它不会级联到子表(比如这本书的评论)。想让”删书连带隐藏评论”,第二篇 §2.4 专门讨论了两种做法与怎么取舍(读侧判定 vs 写侧联动)。

⚠️ 唯一约束的坑:软删除的行仍占着唯一索引——带唯一索引的字段(比如 ISBN)在软删后重建同名记录会撞约束。PostgreSQL 的解法是部分唯一索引:CREATE UNIQUE INDEX ... WHERE deleted_at IS NULL,只让未删除的行参与唯一性。第 5 篇会在真实的 tags.name 上用一遍。

如果需要物理删除(彻底删除)

该函数属于可选项。第九章的完整版 main.go 默认注册了它;不想对外开放就把那行删掉。

// DeleteBookPermanently 物理删除图书(DELETE /books/:id/permanent)
func DeleteBookPermanently(c *gin.Context) {
    id := c.Param("id")
    // Unscoped() 绕过软删除,执行物理删除
    result := db.DB.WithContext(c.Request.Context()).Unscoped().Delete(&models.Book{}, id)
    if result.Error != nil { // 先验错误,再判行数(与 DeleteBook 同一套顺序)
        _ = c.Error(result.Error)
        c.JSON(http.StatusInternalServerError, gin.H{"error": "删除失败"})
        return
    }
    if result.RowsAffected == 0 {
        c.JSON(http.StatusNotFound, gin.H{"error": "图书不存在"})
        return
    }
    c.JSON(http.StatusOK, gin.H{"message": "物理删除成功"})
}

⚠️ 有子记录时会失败:第 2 篇给 Book 加上评论关联后,GORM 建的外键默认 NO ACTION——删一本有评论的书会被 PostgreSQL 拒绝(violates foreign key constraint)。解法是给关联声明加 constraint:OnDelete:CASCADE(第 2 篇的模型已带),或在事务里先删评论。软删除不受影响。

测试:curl -X DELETE http://localhost:8080/books/1。

第九章:注册路由

把前面的东西串起来——路由部分是:

r := gin.Default()
r.Use(requestTimeout(5 * time.Second)) // 请求级超时:慢查询被 context 中断

r.POST("/books", handlers.CreateBook)
r.GET("/books", handlers.GetBooks)
r.GET("/books/:id", handlers.GetBook)
r.PUT("/books/:id", handlers.UpdateBook) // 整体替换语义(Select 列出参与更新的列)
r.DELETE("/books/:id", handlers.DeleteBook)
r.DELETE("/books/:id/permanent", handlers.DeleteBookPermanently) // 可选

r.Run(":8080")

requestTimeout 就是第五章说的”给每个请求挂超时兜底”:把 context.WithTimeout 派生出的 ctx 写回请求,下游的 WithContext 才能感知超时。

完整 main.go(含 import、数据库初始化、迁移、中间件与上面这些路由):

完整 main.go(点击展开)
package main

import (
    "context"
    "log"
    "time"

    "gin-demo/db"
    "gin-demo/handlers"
    "gin-demo/models"
    "github.com/gin-gonic/gin"
)

// 给每个请求挂一个超时兜底(第五章)
func requestTimeout(d time.Duration) gin.HandlerFunc {
    return func(c *gin.Context) {
        ctx, cancel := context.WithTimeout(c.Request.Context(), d)
        defer cancel()
        c.Request = c.Request.WithContext(ctx)
        c.Next()
    }
}

func main() {
    // 连接数据库
    db.InitDB()

    // 自动迁移
    if err := db.DB.AutoMigrate(&models.Book{}); err != nil {
        log.Fatal("迁移失败:", err)
    }

    r := gin.Default()
    // 请求级超时:慢查询会被 context 中断,走 500(生产可映射 504)
    r.Use(requestTimeout(5 * time.Second))

    // RESTful API 路由
    r.POST("/books", handlers.CreateBook)
    r.GET("/books", handlers.GetBooks)
    r.GET("/books/:id", handlers.GetBook)
    r.PUT("/books/:id", handlers.UpdateBook) // 整体替换语义(Select 列出参与更新的列)
    r.DELETE("/books/:id", handlers.DeleteBook)
    // 可选:第八章的物理删除示例(默认软删除即可满足需求)
    r.DELETE("/books/:id/permanent", handlers.DeleteBookPermanently)

    r.Run(":8080")
}

跑起来后就可以用 curl 逐章测试,包括物理删除:curl -X DELETE http://localhost:8080/books/1/permanent。

第十章:总结

操作 GORM 方法 对应 SQL
创建 db.Create(&book) INSERT INTO ...
查询所有 db.Find(&books) SELECT * FROM ...
查询单条 db.First(&book, id) SELECT * FROM ... WHERE id = ?
更新 db.Model(&book).Select("...").Updates(x) UPDATE ... SET ...(列表里的列零值也写)
软删除 db.Delete(&models.Book{}, id) UPDATE ... SET deleted_at = NOW()
物理删除 db.Unscoped().Delete(&models.Book{}, id) DELETE FROM ...
查询已删除 db.Unscoped().First(&models.Book{}, id) SELECT * FROM ... WHERE id = ?(不限软删除)

全文的 5 个 handler 都是「先看公式」节六步骨架的实例化:参数 → 绑定 → 存在 → 操作 → 结果 → 响应;所有 db 操作均链上 WithContext(c.Request.Context()),查询用 errors.Is 区分「查无记录」(404)与其它错误(500)。

进阶方向

  • 事务:db.Transaction()
  • 钩子函数:BeforeCreate、AfterUpdate
  • 响应精简:gorm.Model 的大写键怎么统一——自定义字段声明,或 DTO 做统一响应结构
  • 连接池:sqlDB, _ := db.DB.DB() 拿到 *sql.DB 后,用 SetMaxOpenConns() / SetConnMaxLifetime() 配置
  • 超时映射:errors.Is(err, context.DeadlineExceeded) 时返回 504,而不是笼统的 500
  • SQL 调试:&gorm.Config{Logger: logger.Default.LogMode(logger.Info)}
如果这篇文章对你有帮助,可以请我喝杯咖啡 ☕️
Ali PayWechat Pay