GORM 文件与查询增强实战：封面上传、分页搜索与评论数聚合

📚 系列导航

本系列共七篇：

1. GORM 入门实战：用 Gin + GORM 写一个图书管理 API —— 单表 CRUD、软删除、零值陷阱，从零跑通完整项目
2. GORM 多表关联实战：评论模型、增删查与 Preload —— 第二张表 comments、评论增删查、详情按需加载
3. GORM 文件与查询增强实战：封面上传、分页搜索与评论数聚合 —— 上传与静态服务、分页/搜索/排序、评论数聚合
4. GORM 数据工程实战：批量导入、请求 DTO 与校验错误翻译 —— CreateInBatches、DTO 与模型分离、校验错误翻译
5. GORM 多对多实战：书籍与标签 —— many2many 连接表、按标签筛选与关联增删
6. GORM 工程化实战（一）：分层、注入与可测性（选读） —— Repository/Service 分层、构造注入、表驱动测试
7. GORM 工程化实战（二）：可靠性与生产化（选读） —— 统一错误处理、安全补强、对象存储、连接池

---

前置阅读：完成入门篇（《GORM 入门实战》）与《多表关联实战》——books + comments 双表项目。代码约定与入门篇一致（WithContext / errors.Is 判 404 / 400·404·201）。

真实接口绕不开的两件事，本篇补齐：给书加封面图（第一节），把列表查询升级为分页 + 搜索 + 排序 + 评论数（第二节）。

---

一、图片字段：封面上传与静态服务

目标： 给书加封面图：一个可用的上传接口，图片存磁盘、路径存数据库、静态目录对外可访问。

1.1 先定命名：为什么叫 cover_path 而不是 cover_url

字段名应当反映存的是什么：

存的是什么	更贴切的名字
完整 URL（http://host/uploads/x.jpg）	cover_url
相对路径（/uploads/x.jpg）——本教程方案	cover_path
对象存储 key（S3 等）	cover_key

本教程把图片落在 uploads/ 磁盘目录，数据库存相对路径（换域名、接 CDN、挪位置都不必改数据）。所以字段名叫 cover_path。前端习惯用 coverUrl？用 Go tag 把”内部语义”和”对外契约”解耦——内部名准确，JSON 名顺手，两不耽误：

CoverPath string `json:"coverUrl" gorm:"column:cover_path"`

1.2 模型加字段

models/book.go 在 Price 之后追加（字段标签写法见 1.1，Comments 等原有字段保持不变）：

CoverPath string `json:"coverUrl" gorm:"column:cover_path"` // 相对路径，可空

AutoMigrate 会给 books 补一列可空的 cover_path，已有行不受影响（空值）。

1.3 上传接口

handlers/cover.go：

package handlers

import (
    "errors"
    "fmt"
    "gin-demo/db"
    "gin-demo/models"
    "net/http"
    "path/filepath"
    "strings"
    "time"

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

// UploadCover 上传图书封面：限制类型与大小，存 uploads/，路径写回 cover_path
func UploadCover(c *gin.Context) {
    id := c.Param("id")

    // 1. 书必须存在
    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.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
        return
    }

    // 2. 取文件并校验
    file, err := c.FormFile("cover")
    if err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": "缺少文件字段 cover"})
        return
    }
    ext := strings.ToLower(filepath.Ext(file.Filename))
    switch ext {
    case ".jpg", ".jpeg", ".png", ".webp":
    default:
        c.JSON(http.StatusBadRequest, gin.H{"error": "仅允许 jpg/png/webp"})
        return
    }
    if file.Size > 2<<20 { // 2<<20 字节 = 2MB。注意这是"事后检查"：FormFile 已把整个文件读入，2MB 不是请求级硬上限（教学够用，真正挡大请求要在更外层做限制）
        c.JSON(http.StatusBadRequest, gin.H{"error": "文件过大（上限 2MB）"})
        return
    }

    // 3. 落盘：随机文件名，防覆盖、防路径注入
    filename := fmt.Sprintf("%d_%d%s", book.ID, time.Now().UnixNano(), ext)
    if err := c.SaveUploadedFile(file, filepath.Join("uploads", filename)); err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "保存文件失败"})
        return
    }

    // 4. 路径写回数据库（只更新这一个字段）
    // coverPath 存的是 URL 路径，用正斜杠拼接（为什么别用 filepath.Join 见下方要点）
    coverPath := "/uploads/" + filename
    if err := db.DB.WithContext(c.Request.Context()).
        Model(&book).Update("cover_path", coverPath).Error; err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "更新图书失败"})
        return
    }

    c.JSON(http.StatusOK, gin.H{"coverUrl": coverPath})
}

要点：

• 文件名不信任用户输入：filepath.Ext 只取扩展名，主名用 book.ID + 时间戳 拼——既防覆盖也防 ../../ 这类路径注入；
• 两种路径别混：coverPath 是 URL 路径，永远正斜杠 /（存数据库、给前端），用 path.Join 或直接拼接；落盘才用 filepath.Join（按 OS 分隔符）。Windows 反斜杠恰恰是反例——用 filepath.Join 拼 URL 会在 Windows 下产出 \uploads\ 存库，前端永远匹配不上；
• 类型校验用的是扩展名白名单（简单教学版；严格做法要嗅探文件头 http.DetectContentType，落地见《GORM 工程化实战（二）：可靠性与生产化》第二节）；
• Model(&book).Update("cover_path", ...) 单字段更新，不会误动其它字段（与入门篇 Updates(struct) 语义呼应）。

1.4 静态服务与目录准备

main.go 三处小改动：

import (
    "os"
    "path/filepath"
    // ...其余不变
)

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

    // 磁盘目录：用 filepath.Join 拼（OS 分隔符），MkdirAll 与 Static 共用同一个值
    uploadDir := filepath.Join(".", "uploads")
    _ = os.MkdirAll(uploadDir, 0o755) // 确保目录存在

    r := gin.Default()
    r.Use(requestTimeout(5 * time.Second))
    r.Static("/uploads", uploadDir) // URL 前缀写死正斜杠 /uploads；目录走 uploadDir
    // /uploads/xxx.jpg → ./uploads/xxx.jpg

    // ...路由区新增：
    r.POST("/books/:id/cover", handlers.UploadCover)
}

r.Static("/uploads", uploadDir) 让 /uploads/<文件名> 直接映射到磁盘目录——浏览器/前端拼 coverUrl 即可展示图片。

测试：

curl -X POST http://localhost:8080/books/1/cover \
  -F "cover=@/path/to/cover.jpg"
# {"coverUrl":"/uploads/1_1734xxxx.jpg"}

curl -I http://localhost:8080/uploads/1_1734xxxx.jpg   # 200，Content-Type image/jpeg

# 反例：非图片 / 超 2MB 应返回 400
curl -X POST http://localhost:8080/books/1/cover -F "cover=@/etc/hosts"
# {"error":"仅允许 jpg/png/webp"}

---

二、查询增强：分页、搜索、排序

目标： 把 GetBooks 从”全量列表”升级为”分页 + 搜索 + 排序”的通用接口，并给列表加上每本书的评论数（JOIN + GROUP BY）。多表关联篇（《多表关联实战》）学过的分页骨架，这里在更大的表上复用。

2.1 先收拢帮助函数

多表关联篇的 ListComments 里，分页解析是内联写的（先看完整形态是正确的教学顺序）。现在把它收拢到 handlers/pagination.go，供所有分页接口复用：

// handlers/pagination.go —— 分页参数解析 + 校验（防御式，非法值回落到默认）
package handlers

import (
    "strconv"

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

func parsePagination(c *gin.Context) (page, pageSize int) {
    page, err := strconv.Atoi(c.DefaultQuery("page", "1"))
    if err != nil || page < 1 {
        page = 1
    }
    pageSize, _ = strconv.Atoi(c.DefaultQuery("pageSize", "10"))
    if pageSize < 1 {
        pageSize = 10
    }
    if pageSize > 100 {
        pageSize = 100 // 上限 100：防止客户端一次拉取过量数据
    }
    return page, pageSize
}

2.2 改造 GetBooks

⚠️ 破坏性契约变更： GET /books 的响应从入门篇的裸数组变为 {items,total,page,pageSize} 对象——已有前端需要同步适配（系列路由总表里这条记为”1 → 3 改造”）。

handlers/book.go：

// GetBooks 图书列表：支持 q（标题/作者模糊搜索）、page/pageSize 分页；排序固定为创建时间倒序（外部排序字段需先白名单化，见[《GORM 工程化实战（二）》](./gorm-gin-engineering-reliability)§2.1）。
// 返回 {items, total, page, pageSize}。
func GetBooks(c *gin.Context) {
    // 1. 解析查询参数
    // 1.1 q：标题/作者模糊搜索关键词
    q := c.Query("q")
    // 1.2 分页参数解析 + 校验（在 handlers/pagination.go 里的 parsePagination）
    page, pageSize := parsePagination(c)

    // 2. 组装查询：可选标题/作者模糊搜索
    query := db.DB.WithContext(c.Request.Context()).Model(&models.Book{})
    if q != "" {
        like := "%" + q + "%"
        query = query.Where("title ILIKE ? OR author ILIKE ?", like, like)
    }

    // 3. 先 Count 过滤后的总条数
    var total int64
    if err := query.Count(&total).Error; err != nil {
        _ = c.Error(err) // 具体错误交给 Gin 日志；客户端消息保持统一
        c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
        return
    }

    // 4. 再取当前页（按创建时间倒序）
    var books []models.Book
    if err := query.
        Order("created_at DESC").
        Offset((page - 1) * pageSize).
        Limit(pageSize).
        Find(&books).Error; err != nil {
        _ = c.Error(err) // 具体错误交给 Gin 日志；客户端消息保持统一
        c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
        return
    }

    // 5. 返回分页结果
    c.JSON(http.StatusOK, gin.H{
        "items":    books,
        "total":    total,
        "page":     page,
        "pageSize": pageSize,
    })
}

测试：

curl "http://localhost:8080/books?q=Go&page=1&pageSize=10"
# {"items":[...],"total":1,"page":1,"pageSize":10}

curl "http://localhost:8080/books?page=2&pageSize=5"
# 翻页：total 不变，items 为第二页

要点（都是 GORM 查询的骨架级知识）：

• ILIKE 是 PG 专用：LIKE 分大小写、ILIKE 不分。教程用 PG，写 ILIKE；换 MySQL 用 LIKE，换 SQLite 用 LIKE（SQLite LIKE 对 ASCII 不区分大小写）——驱动差异的一个具体例子。另注意 q 若含 %/_ 会被当成通配符：参数化只防 SQL 注入、不防通配符语义，按字面搜索需先转义或加 ESCAPE，教程不展开；
• query 是可复用的链：同一个 query 变量先 Count 再追加 Order/Offset/Limit 执行 Find——Count 前不带分页条件，得到的是过滤后的总数，这正是分页接口的标准姿势；
• ORDER 注入：如果 sort 参数来自用户，千万别直接拼进 Order()（"/books?sort=created_at;DROP..."）——教程固定排序即可，接受外部排序字段要先做白名单（落地见《GORM 工程化实战（二）》§2.1）。

2.3 给列表加评论数：JOIN + GROUP BY

Preload 只能取”评论对象数组”，取不了”评论条数”。要”每本书带评论数”，用聚合——需要一个承载结果的结构：

// 列表响应结构：Book 本体 + 评论计数（不进数据库表，只做查询载体）
type BookListItem struct {
    models.Book
    CommentCount int64 `json:"commentCount"`
}

然后在 GetBooks 基础上只改第 4 步（第 1/2/3/5 步原样不动：分页解析仍走 parsePagination，总数仍用纯 books 表 Count）——把第 4 步的 var books []models.Book + Find 换成下面的 var items []BookListItem + Scan（BookListItem 见上方声明）：

var items []BookListItem
if err := query.
    Select("books.*, COUNT(comments.id) AS comment_count").
    Joins("LEFT JOIN comments ON comments.book_id = books.id AND comments.deleted_at IS NULL").
    Group("books.id").
    Order("books.created_at DESC").
    Offset((page - 1) * pageSize).
    Limit(pageSize).
    Scan(&items).Error; err != nil {
    _ = c.Error(err)
    c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
    return
}

聚合查询的三个坑（都是教科书级的）：

• LEFT JOIN + Group("books.id")：没评论的书也要出现（comment_count = 0），所以是 LEFT 不是 INNER；
• comments.deleted_at IS NULL 条件要进 JOIN 而不是 WHERE：放进 WHERE 会把”无评论的书”整行剔除，放进 JOIN 才能保留左表 + 只数未删除的评论——聚合查询最常见的坑；
• Scan 进自定义结构：BookListItem 嵌了 models.Book 再补一个计数字段——手写聚合 SQL 的结果装进”查询专用载体”，这正是 GORM 把”原生 SQL”接回类型世界的正规姿势（查询载体不进数据库表，只做取数）；
• 字段歧义：JOIN 之后 created_at、id 在两表都有——SQL 层要写 books.created_at、books.id（Group("books.id") 同理），不写表前缀会报”ambiguous column”。

驱动差异提示： Select("books.*") + Group("books.id") 能成立，依赖 PostgreSQL 的”函数依赖”特性——按主键分组时允许直接选其它列。MySQL 开着 only_full_group_by（默认开）时会报错，需要把 books.* 展开成完整列清单并全量分组；这是”手写聚合 SQL”跨数据库的典型差异，教程用 PG，不做兼容处理。

测试：

curl "http://localhost:8080/books?q=Go&pageSize=10"
# items[0].commentCount 应为该书的未删除评论数（无评论的书为 0）

列表接口与详情接口的契约分层：GET /books 返回 {items,total,page,pageSize}，GET /books/:id 返回单本书+评论。列表轻、详情重——这是前面所有”按需加载”决策的落点。

---

本篇小结

• 本篇新增路由：

方法	路径	handler / 作用
POST	/books/:id/cover	UploadCover
GET	/uploads/*	r.Static 静态服务
GET	/books（改造）	GetBooks 分页 + 搜索 + 评论数

• 你现在的项目：books + comments 双表、封面图上传与静态服务、分页搜索列表、每本书带评论数；
• 下一篇《数据工程实战》：批量导入真实数据、请求 DTO 与参数化校验、校验错误的友好翻译，末尾附系列一览与工程化条目清单（系列第 ⁶⁄₇ 篇预告的集中对账）。

---

附：PostgreSQL 特性速查（MySQL / SQLite 对照）

全系列真正依赖 PostgreSQL 的写法只有下面几处，其余都是标准 SQL，三库通用：

PG 特性	出现在哪	本系列写法	换 MySQL	换 SQLite
大小写不敏感的模糊搜索	本篇 §2.2	ILIKE ?	LIKE ?（大小写由 collation 决定；必要时 LOWER(col) LIKE LOWER(?)）	LIKE ?（ASCII 内不区分大小写；非 ASCII 需 COLLATE NOCASE）
按主键分组后可直接选其它列（函数依赖）	本篇 §2.3	SELECT books.*, COUNT(comments.id) ... GROUP BY books.id	默认 only_full_group_by 下报错：需把 books.* 展开成完整列清单并全部 GROUP BY	同 MySQL（无函数依赖，需全列分组）
软删除 + 唯一字段的部分唯一索引	入门篇第八章	CREATE UNIQUE INDEX ... WHERE deleted_at IS NULL	无直接等价：用生成列（(deleted_at IS NULL) 的布尔列）做部分唯一，或应用层保证	同 MySQL

另外 % / _ 在 ILIKE 与 LIKE 里都是通配符（参数化只防 SQL 注入、不防通配符语义），三库一致。教程主线按 PostgreSQL 跑通；想换 MySQL / SQLite，把上面几行替换掉即可，其余代码不用动。