154 lines
4.5 KiB
Go
154 lines
4.5 KiB
Go
// Package pagination 提供后端分页的通用封装：查询参数解析、分页元数据计算、SQL 偏移量，
|
||
// 以及后台 HTML 模板可复用的翻页链接构造。
|
||
//
|
||
// 目标：消除各 handler 里重复的「page/size 解析 + 上/下一页计算 + 越界钳制」样板，
|
||
// 同时保证对外协议（JSON 字段名、HTML 展示文案）完全不变。
|
||
package pagination
|
||
|
||
import (
|
||
"strconv"
|
||
|
||
"github.com/gin-gonic/gin"
|
||
)
|
||
|
||
// Params 是一页请求的规范化参数（page 已钳制到 >=1；size 已钳制到 [1, maxSize]）。
|
||
type Params struct {
|
||
Page int
|
||
PageSize int
|
||
}
|
||
|
||
// Parse 从 gin 查询串读取并规范化分页参数。
|
||
//
|
||
// pageKey/sizeKey 为查询参数名；sizeKey 为空表示不读取条数（固定用 defSize，不校验上限）。
|
||
// 解析规则（与既有后台列表页、history/favorite 接口保持一致）：
|
||
// - page 缺失或非数字 → defPage；<1 → defPage
|
||
// - size 缺失或非数字 → defSize；<1 → defSize；>maxSize → maxSize
|
||
func Parse(c *gin.Context, pageKey, sizeKey string, defPage, defSize, maxSize int) Params {
|
||
page := atoiDefault(c.Query(pageKey), defPage)
|
||
if page < 1 {
|
||
page = defPage
|
||
}
|
||
size := defSize
|
||
if sizeKey != "" {
|
||
size = atoiDefault(c.Query(sizeKey), defSize)
|
||
if size < 1 {
|
||
size = defSize
|
||
}
|
||
if maxSize > 0 && size > maxSize {
|
||
size = maxSize
|
||
}
|
||
}
|
||
return Params{Page: page, PageSize: size}
|
||
}
|
||
|
||
// Offset 返回 GORM 翻页用的 SQL 偏移量：(page-1)*size。
|
||
func (p Params) Offset() int { return (p.Page - 1) * p.PageSize }
|
||
|
||
// Meta 是分页元数据（总页数、上/下一页、是否可翻）。
|
||
//
|
||
// NewMeta 不会修改传入的 Page（与既有 brands/runways/street/reviews 行为一致：越界页码
|
||
// 照常透传给数据库，返回空列表，仅 HasNext 据此计算）。需要越界钳制显示（ingest-jobs）
|
||
// 的调用方拿到 Meta 后调用 Clamp。
|
||
type Meta struct {
|
||
Page int
|
||
PageSize int
|
||
Total int64
|
||
TotalPages int
|
||
PrevPage int
|
||
NextPage int
|
||
HasPrev bool
|
||
HasNext bool
|
||
}
|
||
|
||
// NewMeta 计算分页元数据。
|
||
//
|
||
// HasNext 等价于「page < 总页数」，与原有 `int64(page*size) < total` 在 total>0 时一致；
|
||
// total==0 时总页数记为 1，HasNext 恒为 false（与原逻辑相同）。
|
||
func (p Params) NewMeta(total int64) Meta {
|
||
totalPages := LastPage(total, p.PageSize)
|
||
m := Meta{
|
||
Page: p.Page,
|
||
PageSize: p.PageSize,
|
||
Total: total,
|
||
TotalPages: totalPages,
|
||
}
|
||
if p.Page > 1 {
|
||
m.PrevPage = p.Page - 1
|
||
m.HasPrev = true
|
||
}
|
||
if p.Page < totalPages {
|
||
m.NextPage = p.Page + 1
|
||
m.HasNext = true
|
||
}
|
||
return m
|
||
}
|
||
|
||
// Clamp 把页码钳制到 [1, TotalPages]，并重新计算 Prev/Next。
|
||
// 用于「越界页码应展示最后一页」的场景（ingest-jobs），不改变数据库查询用的原始 offset。
|
||
func (m *Meta) Clamp() {
|
||
if m.TotalPages > 0 && m.Page > m.TotalPages {
|
||
m.Page = m.TotalPages
|
||
m.HasPrev = m.Page > 1
|
||
m.HasNext = false
|
||
m.PrevPage = 0
|
||
m.NextPage = 0
|
||
if m.HasPrev {
|
||
m.PrevPage = m.Page - 1
|
||
}
|
||
}
|
||
}
|
||
|
||
// LastPage 计算总页数；无数据时返回 1（与原项目一致，避免前端出现 0 页）。
|
||
func LastPage(total int64, size int) int {
|
||
if size <= 0 {
|
||
return 1
|
||
}
|
||
last := int(total) / size
|
||
if int(total)%size > 0 {
|
||
last++
|
||
}
|
||
if last == 0 {
|
||
last = 1
|
||
}
|
||
return last
|
||
}
|
||
|
||
// Pager 是后台 HTML 模板复用的翻页视图。
|
||
//
|
||
// 由 handler 用 PageLink/PageLinkWith 生成 PrevURL/NextURL 后塞进模板数据，
|
||
// 模板只需写一行 {{template "pager" .Pager}}。
|
||
type Pager struct {
|
||
PrevURL string
|
||
NextURL string
|
||
HasPrev bool
|
||
HasNext bool
|
||
Label string // 页码信息文案（如「第 3 页 · 共 120 条」），可为空
|
||
}
|
||
|
||
// PageLink 基于当前请求构造仅替换 page 的翻页链接，保留其余查询参数。
|
||
// 用于 brands/runways/street/reviews 等（URL 路径本身已含 kind 段，无需额外拼接）。
|
||
func PageLink(c *gin.Context, page int) string {
|
||
q := c.Request.URL.Query()
|
||
q.Set("page", strconv.Itoa(page))
|
||
return c.Request.URL.Path + "?" + q.Encode()
|
||
}
|
||
|
||
// PageLinkWith 除替换 page 外，额外固定一个参数（如 ingest-jobs 的 pageSize）。
|
||
func PageLinkWith(c *gin.Context, page int, extraKey string, extraVal int) string {
|
||
q := c.Request.URL.Query()
|
||
q.Set("page", strconv.Itoa(page))
|
||
q.Set(extraKey, strconv.Itoa(extraVal))
|
||
return c.Request.URL.Path + "?" + q.Encode()
|
||
}
|
||
|
||
func atoiDefault(s string, def int) int {
|
||
if s == "" {
|
||
return def
|
||
}
|
||
n, err := strconv.Atoi(s)
|
||
if err != nil {
|
||
return def
|
||
}
|
||
return n
|
||
}
|