4. 常见分页策略概览

在构建 REST API 时，分页是控制数据流量的核心手段。不同的分页策略在性能、一致性和实现复杂度上各有取舍。本节将系统梳理四种主流分页方案：基于偏移量分页、基于游标分页、基于键集分页和基于时间戳分页，帮助你在服务边界设计中做出合理选择。

4.1 四种策略核心对比

4.2 基于偏移量分页

偏移量分页是最传统、最直观的分页方式。客户端通过 page（页码）和 size（每页条数）参数请求数据，服务端计算 OFFSET = (page - 1) * size 后执行查询。

// Go 示例：偏移量分页查询
func ListUsers(ctx context.Context, page, size int) ([]User, int64, error) {
    offset := (page - 1) * size
    var total int64
    db.Model(&User{}).Count(&total)

    var users []User
    result := db.Offset(offset).Limit(size).Find(&users)
    return users, total, result.Error
}

4.3 基于游标分页

游标分页使用一个不透明的字符串（游标）来标记当前页的最后位置。客户端在后续请求中携带该游标，服务端解码后直接定位到对应记录之后的数据。游标通常经过 Base64 编码，对客户端隐藏内部实现细节。

// Go 示例：游标分页查询
func ListUsersByCursor(ctx context.Context, cursor string, limit int) ([]User, string, error) {
    var users []User
    query := db.Order("id ASC").Limit(limit + 1)

    if cursor != "" {
        decodedID, _ := decodeCursor(cursor) // 解码游标获取最后记录的 ID
        query = query.Where("id > ?", decodedID)
    }

    result := query.Find(&users)
    if result.Error != nil {
        return nil, "", result.Error
    }

    var nextCursor string
    if len(users) > limit {
        nextCursor = encodeCursor(users[limit-1].ID) // 编码新游标
        users = users[:limit]
    }
    return users, nextCursor, nil
}

4.4 基于键集分页

键集分页（Keyset Pagination）是游标分页的一种特例，它直接暴露排序列的值作为分页锚点。客户端通过 after_id 或 since 参数指定上一页最后一条记录的排序列值，服务端利用数据库索引直接跳转到该位置。

-- SQL 示例：键集分页查询
SELECT id, name, created_at
FROM users
WHERE id > 1000  -- 上一页最后一条记录的 ID
ORDER BY id ASC
LIMIT 20;

键集分页要求排序列必须唯一且有序。通常使用自增主键或业务唯一键（如订单号）作为排序列。如果排序列存在重复值，会导致数据丢失或重复。

4.5 基于时间戳分页

时间戳分页适用于按时间维度排序的数据集，如日志、事件流、交易记录等。客户端通过 before 或 after 参数指定时间范围，服务端利用时间索引高效过滤。

// Go 示例：时间戳分页查询
func ListEvents(ctx context.Context, after time.Time, limit int) ([]Event, error) {
    var events []Event
    result := db.Where("event_time > ?", after).
        Order("event_time ASC").
        Limit(limit).
        Find(&events)
    return events, result.Error
}

4.6 四种策略选择决策树

4.7 策略选择速查表