分页是Golang REST API处理大量数据的关键技术，常用方式包括基于偏移量（Offset-Limit）和游标（Cursor-Based）两种。1. 偏移量分页通过page和page_size计算offset，适用于普通列表场景，实现简单但大数据量下性能差；2. 游标分页利用唯一有序字段（如时间或ID）作为 cursor，避免深度分页问题，适合高并发实时数据；3. 响应应统一包含分页元信息，如当前页、总数、是否有下一页及游标值；4. 最佳实践包括限制最大page_size、校验参数、建立索引、前端配合“加载更多”逻辑。选择方案需根据业务需求权衡。
在构建 Golang 的 REST API 时，分页是处理大量数据返回的常见需求。直接返回成千上万条记录会拖慢响应速度、增加内存消耗，甚至导致客户端崩溃。合理的分页机制能提升系统性能和用户体验。以下是几种常用的分页实现方式及实际操作建议。
基于偏移量的分页（Offset-Limit）
这是最直观的分页方式，适用于大多数场景。通过客户端传入 page 和 page_size 参数，服务端计算出跳过的记录数并限制返回数量。
URL 示例： GET /api/users?page=2&page_size=10
在 Golang 中处理逻辑如下：
立即学习“go语言免费学习笔记（深入）”；
type Pagination struct {
Page int `json:"page"`
PageSize int `json:"page_size"`
Offset int `json:"-"`
}
<p>func (p <em>Pagination) SetOffset() {
p.Offset = (p.Page - 1) </em> p.PageSize
}</p>数据库查询（以 SQL 为例）：
rows, err := db.Query(
"SELECT id, name FROM users LIMIT ? OFFSET ?",
pagination.PageSize,
pagination.Offset,
)
优点是实现简单，缺点是在大数据集下，OFFSET 越大查询越慢，因为数据库仍需扫描前面的数据行。
基于游标的分页（Cursor-Based Pagination）
适合高并发、实时性要求高的场景，比如消息流或时间线。它使用某个唯一且有序的字段（如创建时间、ID）作为“游标”，每次请求携带上一次返回的最后一条记录值。
URL 示例： GET /api/posts?cursor=1678901234&limit=10
Golang 处理示例：
func GetPosts(w http.ResponseWriter, r *http.Request) {
query := r.URL.Query()
cursorStr := query.Get("cursor")
limit := 10
if size := query.Get("limit"); size != "" {
limit, _ = strconv.Atoi(size)
}
<pre class='brush:php;toolbar:false;'>var cursor int64
if cursorStr != "" {
cursor, _ = strconv.ParseInt(cursorStr, 10, 64)
} else {
cursor = time.Now().Unix() // 默认为当前时间
}
rows, err := db.Query(
"SELECT id, title, created_at FROM posts "+
"WHERE created_at < ? ORDER BY created_at DESC LIMIT ?",
cursor, limit,
)
// ...处理结果，返回时带上新的 cursor（最后一条记录的 created_at）}
这种方式避免了 OFFSET 的性能问题，支持高效翻页，但不支持跳转到指定页码。
响应格式设计
无论哪种分页方式，API 响应应包含分页元信息，方便客户端控制翻页行为。
{
"data": [...],
"pagination": {
"current_page": 2,
"page_size": 10,
"total": 100,
"has_next": true,
"has_prev": false,
"next_cursor": "1678901200"
}
}
定义结构体统一输出：
type ResponseWithPagination struct {
Data interface{} `json:"data"`
Pagination PaginationMeta `json:"pagination"`
}
<p>type PaginationMeta struct {
CurrentPage int <code>json:"current_page"</code>
PageSize int <code>json:"page_size"</code>
Total int64 <code>json:"total"</code>
HasNext bool <code>json:"has_next"</code>
HasPrev bool <code>json:"has_prev"</code>
NextCursor string <code>json:"next_cursor,omitempty"</code>
}</p>最佳实践建议
- 对普通列表接口可采用 offset-limit，但要限制最大 page_size（如不超过 100）
- 高频访问或大数据量推荐使用游标分页，结合索引字段提升性能
- 始终校验分页参数，防止恶意请求（如 page=999999）
- 在 WHERE 和 ORDER BY 字段上建立合适索引，尤其是游标字段
- 前端展示时，游标模式更适合“加载更多”而非页码跳转
基本上就这些。选择哪种方式取决于业务场景和数据特性。合理设计能让 API 更稳定、响应更快。
