GET接口分页设计：是否需返回总数据量及常见实现方案

是否需要返回总行数？ #

对于React Tables这类需要展示页码导航、总条数/总页数的前端组件，建议返回总行数。前端需要用总条数计算总页数（总页数 = 向上取整(总条数/每页条数)），同时也能让用户直观了解内容总量。如果是无限滚动类场景，可省略总条数，但传统分页模式下这是标准需求。

除计数表外的总行数实现方式 #

1. 窗口函数一次性获取数据与总数 #

利用PostgreSQL的COUNT(*) OVER()窗口函数，在查询数据的同时返回符合条件的总行数，无需额外执行计数查询，效率更高：

SELECT *, COUNT(*) OVER() AS total_count 
FROM posts 
ORDER BY created_at DESC 
OFFSET $1 -- (page-1)*per_page
LIMIT $2  -- per_page

返回结果中每一行都会携带total_count字段，前端只需取第一行的该值即可（所有行的total_count都相同）。如果接口有过滤条件（比如按分类查询），窗口函数会自动统计符合过滤条件的总行数，无需修改逻辑。

2. 两次独立查询 #

这是最直观的方案：一次查询当前页的数据，一次查询总行数。需要注意两个查询的过滤条件（如果有）必须完全一致：

-- 查询当前页数据
SELECT * FROM posts 
ORDER BY created_at DESC 
OFFSET $1 
LIMIT $2;

-- 查询总行数
SELECT COUNT(*) AS total_count FROM posts;

对于学校论坛这类数据量不大的场景，这种方式简单易维护，性能不会有明显问题。

3. 系统表估算总数（仅作参考） #

通过PostgreSQL的pg_class系统表获取表的近似行数，适合不需要精确总数的场景：

SELECT reltuples::bigint AS estimated_total 
FROM pg_class 
WHERE relname = 'posts';

注意：这个值是数据库的统计估算值，并非实时精确数，不适合React Tables需要精确总页数的场景。

分页接口的常见设计规范 #

• 请求参数：通常接收page（当前页码，默认1）和per_page（每页条数，默认10，建议限制最大值如50，防止恶意请求）。
• 响应结构：建议将数据和分页信息分离，示例JSON结构：

{
  "data": [
    {
      "id": 1,
      "title": "论坛帖子标题",
      "content": "帖子内容",
      "created_at": "2024-05-20T12:00:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_count": 123,
    "total_pages": 13
  }
}

• 性能优化提示：当数据量较大时，OFFSET会因扫描大量前置行导致性能下降，可改用游标分页（Keyset Pagination）：基于有序唯一字段（如自增id），通过WHERE id < 上一页最后一条id替代OFFSET，但这种模式下若需总页数，仍需配合计数查询。学校论坛数据量小，OFFSET方案足够使用。

内容的提问来源于stack exchange，提问作者Gareth T.