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 日志就能看到。
四个必须建立的心智
- 结构体一物三用:同一个 struct 既是表结构(
gorm标签)、又是请求/响应载体(json标签)、还是数据库操作的参数(&book)。类型即契约,改一处全联动。 - 查数据是「填空」,不是「返回值」:
Find(&books)、First(&book, id)必须传目标变量的指针,GORM 靠反射填进去;漏写&等于填了个副本,函数外拿不到。ShouldBindJSON(&x)、Delete(&models.Book{})、AutoMigrate(&models.Book{})同理——要往里填、或要对象本身,都得传地址。反过来,*gorm.DB/*gin.Context这种指针类型声明表示「引用同一个实例、不拷贝」,*string/*int表示「可能没传」(nil)。 - 零值即「未提供」:
Updates(结构体)按零值(0、""、false)判断要不要更新,所以把字段改成0会被静默跳过。第七章的零值陷阱根就在这里。 - 错误是结果的一部分: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 是同一套流程的实例化。六步骨架:
- 抓参数:
id := c.Param("id")或c.Query("keyword") - 绑请求:
c.ShouldBindJSON(&xxx),失败直接 400 - 查存在:
db.DB.First(&xxx, id),查无记录(errors.Is命中gorm.ErrRecordNotFound)→ 404 - 做操作:
Create/Find/Updates/Delete——每次操作都返回result - 验结果:非「查无记录」的
result.Error→ 500;RowsAffected == 0→ 404 - 回响应:
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)}

