Documentation
¶
Overview ¶
Package pagination 提供框架无关的分页参数定义。
本包是 PageRequest 的唯一定义位置，middleware 和 data/gormx 均依赖本包， 避免 middleware 层反向依赖 data 层。
Index ¶
Constants ¶
const ( // DefaultPage 是默认页码。 DefaultPage = 1 // DefaultPageSize 是默认每页条数。 DefaultPageSize = 20 // MaxPageSize 是每页最大条数。 MaxPageSize = 500 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type OverMaxPolicy ¶ added in v0.25.2
type OverMaxPolicy int
OverMaxPolicy 描述「请求页长超过上限」时的处理语义。
两种语义都真实存在于消费方，且**响应条数不同**（可观测差异，不能顺手统一）：
- OverMaxClamp：钳到 MaxPageSize（pkg/pagination 现行语义）。
- OverMaxFallback：回退到 DefaultPageSize。
const ( // OverMaxClamp 把超限的页长钳到 MaxPageSize。 // 这是 OverMaxPolicy 的零值，也是 pkg/pagination 的现行语义。 OverMaxClamp OverMaxPolicy = iota // OverMaxFallback 把超限的页长回退到 DefaultPageSize。 OverMaxFallback )
type PageRequest ¶
type PageRequest struct {
Page int `json:"page" query:"page" form:"page"`
PageSize int `json:"page_size" query:"page_size" form:"page_size"`
}
PageRequest 表示分页查询请求参数。
func NewPageRequest ¶
func NewPageRequest(page, pageSize int) *PageRequest
NewPageRequest 根据页码和每页条数创建 PageRequest。
func (*PageRequest) Normalize ¶
func (r *PageRequest) Normalize()
Normalize 规范化分页参数，为非法值设置默认值，并限制最大每页条数。
func (*PageRequest) Offset ¶
func (r *PageRequest) Offset() int
Offset 返回分页查询的偏移量。 当计算结果溢出时返回 0（回退到第一页）。 只读:不在接收者上落 Normalize 的写 — 共享 PageRequest(如全局默认值) 并发调 Offset/Limit 时是数据竞争(2026-09-06 复审修复)。
type PageResponse ¶
type PageResponse[T any] struct { Items []T `json:"items"` Total int64 `json:"total"` Page int `json:"page"` PageSize int `json:"page_size"` Pages int `json:"pages"` }
PageResponse 是全库统一的分页响应信封。
此前 data/gormx（JSON "list"）与 data/crud（JSON "items"）各有一个 字段名/JSON 契约不同的泛型分页结构，导致 API 契约分叉；两者已统一 为本类型的类型别名，新代码直接使用 pagination.PageResponse。
字段取舍说明：数据字段名采用 items（与 handler/crudh 的 REST 契约 一致），pages 保留 gormx 语义（总页数，向上取整）。
type Policy ¶ added in v0.25.2
type Policy struct {
// DefaultPage 是非法页码（<= 0）时归一化到的页码。
DefaultPage int
// DefaultPageSize 是非法页长（<= 0）时归一化到的页长。
DefaultPageSize int
// MaxPageSize 是页长上限；< 0 表示不限上限。
MaxPageSize int
// OverMax 是页长超上限时的处理语义。
OverMax OverMaxPolicy
}
Policy 是服务级分页口径——把「默认页长 / 上限 / 超限语义」从包级常量里提出来， 让每个服务声明自己的口径，而不是各写一份归一化逻辑。
零值退回包级默认（DefaultPage / DefaultPageSize / MaxPageSize / OverMaxClamp）， 因此 `Policy{}` 与包级常量口径完全一致。
字段语义：
- DefaultPage：<= 0 时取包级 DefaultPage。
- DefaultPageSize：<= 0 时取包级 DefaultPageSize。
- MaxPageSize：== 0 时取包级 MaxPageSize；< 0 表示**不限上限**（如「默认 20、不设上限」 的服务）；> 0 时为该服务的页长上限。
- OverMax：页长超上限时的语义；未知取值按 OverMaxClamp 处理。
例：默认 50、上限 200、超限回退默认（等价于把口径写死在服务里）：
Policy{DefaultPageSize: 50, MaxPageSize: 200, OverMax: OverMaxFallback}
例：默认 20、不限上限：
Policy{DefaultPageSize: 20, MaxPageSize: -1}
func (Policy) Normalize ¶ added in v0.25.2
Normalize 按本口径归一化页码与页长，返回归一化后的 (page, pageSize)。
规则：
- page <= 0 ⇒ 口径的默认页码。
- pageSize <= 0 ⇒ 口径的默认页长。
- pageSize 超上限 ⇒ 按 OverMax 语义处理：钳到上限（OverMaxClamp） 或回退到默认页长（OverMaxFallback）；口径不限上限时原样返回。
纯函数，不修改入参。
func (Policy) NormalizeLimit ¶ added in v0.28.0
NormalizeLimit 按「最多返回多少条」的口径归一化条数。
与 Normalize 的区别只在**口径维度**：Normalize 说的是「第几页、每页几条」 （两个参数）；本方法说的是「最多返回多少条」——**没有页的概念**，如工具的 limit 参数（语义是行数），或任何「只要前 N 条」的场景。
规则（页长档语义完全一致，字段复用 DefaultPageSize / MaxPageSize / OverMax， 不另起一套几乎一样的口径）：
- n <= 0 ⇒ 口径的默认条数。
- n 超上限 ⇒ 按 OverMax 语义处理：钳到上限（OverMaxClamp）或回退到默认条数 （OverMaxFallback）；口径不限上限时原样返回。
等价于 Limit(1, n)，但不必传一个恒为 1 的页码——把「第 1 页的页长」当「条数」 用是拧的：读代码的人会先愣一下才反应过来这里没有页。
Source Files