PostgreSQL 游标分页:从数据库到浏览器

实现一个 PostgreSQL、Node.js 与浏览器贯通的游标分页示例,拆解时间精度、大整数、租户校验、并发响应和快照边界,并明确已执行测试与待验证部分。

用户点了“加载更多”,列表却又出现刚看过的几条;翻到后面越来越慢;切换条件后,旧请求还把上一组结果塞回来。这三个问题通常分属数据库、接口和浏览器,却会在同一个分页组件里同时暴露。

本文实现一个按创建时间倒序浏览的多租户信息流:PostgreSQL 保存数据,Node.js 提供接口,浏览器逐页追加。重点不是换一个分页参数,而是把排序、精度、权限和异步状态连成一份可检查的契约。代码面向学习和本地验证,不包含生产登录系统,也没有声称完成数据库性能实测。

先决定用户究竟需要怎样翻页

后台财务报表经常需要“跳到第八十页”,信息流更常见的是“从刚才的位置继续看”。这两种交互不必使用同一种查询。前者保留页码与总数可能更合理;后者适合用上一页最后一条记录的排序键继续扫描。为了一个深页变慢的问题,把所有分页都替换成游标,往往会把复杂性转移到产品交互上。

这里选择后者,约定只有向后翻页;默认每页二十条,最多五十条;排序为创建时间倒序,同一时间按编号倒序;新增记录通过刷新查看。这个取舍意味着接口不提供总页数,也不承诺“第几页”。如果用户需要精确跳转,就应另建检索入口或接受额外的定位成本,而不是假装一个游标能直接算出任意位置。

OFFSET 的问题可以用五条记录说明。初始顺序是五、四、三、二、一,第一页取五、四;此时插入六,第二次偏移两条会取四、三,四重复了。如果改为“取排序键小于四的记录”,结果仍从三继续。PostgreSQL 文档同时提醒,LIMIT 必须配合确定的排序,较大的 OFFSET 仍需要服务端计算被跳过的记录。LIMIT 与 OFFSET 官方说明

这个例子不能推出游标分页永不重复或漏读。假如一条已经读过的记录被修改到更旧的创建时间,它可能再次落到后续范围;反过来,未读记录被移动到游标前方,就可能被错过。因此下面把创建时间视为写入后不变的业务字段。真正需要按“最后修改时间”排序的工单列表,必须接受数据移动,或者引入明确的快照机制。

数据模型先处理两个容易忽略的精度问题

把以下内容保存为 schema.sql,在独立测试库执行。不要直接用于已有生产表的结构迁移。

CREATE TABLE feed_items (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  tenant_id text NOT NULL,
  created_at timestamptz(3) NOT NULL DEFAULT clock_timestamp(),
  title text NOT NULL
);
CREATE INDEX feed_page_idx ON feed_items
  (tenant_id, created_at DESC, id DESC);
INSERT INTO feed_items(tenant_id, created_at, title)
SELECT 'demo', '2026-11-05T10:00:00Z'::timestamptz,
       'item-' || n FROM generate_series(1,7) n;

两个排序字段都不能为 NULL。这里用编号打破同一毫秒内的并列关系,避免只按时间排序时一页末尾切开一组记录。下一页的条件必须同时携带时间和编号,比较符号必须是严格小于,不能用小于等于,否则最后一条会重复。

还有一个很隐蔽的坑:PostgreSQL 时间戳可以比 JavaScript Date 更精细。如果库里保留微秒,驱动转为 Date 后丢掉尾数,再将它放进游标,边界就可能被移动。本文明确选用毫秒精度的 timestamptz(3),并由数据库格式化成固定 UTC 字符串。已有微秒级业务不能照抄这个降精度决定,应保留数据库原始精度并实现对应的序列化,不要用客户端日期对象悄悄截断。

编号也不能随手转成 Number。bigint 可超出 JavaScript 安全整数范围,因此接口和游标始终使用十进制字符串;仅在校验范围时使用 BigInt。浏览器不需要对编号做算术,只把它当稳定身份。这是数据契约的一部分,不能在前端类型定义里又改回 number。

联合索引首先放租户,再放排序列,匹配查询里的租户等值条件及时间范围。它不是所有查询的通用索引:如果之后增加状态筛选,低命中率可能导致扫描许多候选记录才能凑够一页。是否把状态放入索引,要根据查询组合和写入负担重新评估。官方文档解释了多列 B-tree 中前导等值条件与后续范围条件的作用。多列索引说明

游标应该包含什么,又不能承担什么

本文的游标包含版本、租户、上一条记录的时间和编号,以及十五分钟有效期。外层使用 HMAC 防止客户端修改内容;它并不加密,拿到游标的人仍能解码其中的数据。因此不要塞入邮箱、访问令牌或业务秘密,也不要把它当作登录凭证。

租户身份必须来自服务器已经验证的会话。示例为了能独立运行,把租户固定为 demo,并仅监听本机地址;上线时必须替换这个位置,不能直接信任客户端传入的 tenant 参数。即便游标签名正确,查询仍然要带上当前会话的租户条件,才能避免把“持有一个游标”误当成“有权读取对应数据”。

创建 cursor.mjs:

import { createHmac, timingSafeEqual } from 'node:crypto';
export function codec(key) {
  if (Buffer.byteLength(key) < 32) throw Error('weak key');
  const sign = s => createHmac('sha256', key).update(s).digest();
  return {
    encode(row, tenant, now = Date.now()) {
      const body = Buffer.from(JSON.stringify({v:1, tenant,
        t:row.created_at, id:row.id, exp:now+900000})).toString('base64url');
      return body+'.'+sign(body).toString('base64url');
    },
    decode(token, tenant, now = Date.now()) {
      try {
        if (token.length > 1024) throw Error();
        const parts = token.split('.');
        if(parts.length !== 2 || parts.some(p=>! /^[A-Za-z0-9_-]+$/.test(p))) throw Error();
        const [body, sig] = parts;
        const actual = Buffer.from(sig,'base64url'), expected = sign(body);
        if(actual.length !== expected.length || !timingSafeEqual(actual,expected)) throw Error();
        const p = JSON.parse(Buffer.from(body,'base64url').toString());
        if(p.v!==1 || p.tenant!==tenant || !Number.isSafeInteger(p.exp) || p.exp<=now ||
           typeof p.t!=='string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(p.t) ||
           !Number.isFinite(Date.parse(p.t)) || new Date(p.t).toISOString()!==p.t ||
           typeof p.id!=='string' || !/^[1-9]\d{0,18}$/.test(p.id) ||
           BigInt(p.id)>9223372036854775807n) throw Error();
        return p;
      } catch { throw Error('invalid_cursor'); }
    }
  };
}

先限制长度,再拆分格式并验签,最后验证结构和取值。签名比较前检查字节长度,是因为 timingSafeEqual 要求输入等长;整个请求处理也不能因此被宣称为完全恒定时间。这里利用的是 Node.js 内置 HMAC 与比较接口,没有自行设计密码算法。Node.js Crypto 文档

版本号为未来改变排序规则留出入口。例如以后改成“置顶优先、创建时间次之”,旧游标中的两个字段已不足以描述顺序,必须拒绝旧版本或者保持旧查询兼容,不能把它悄悄套进新规则。有效期同样是一项产品选择:短有效期方便撤销旧约定,但用户离开页面后可能需要刷新,前端必须明确解释。

这个最小示例每次返回下一页时延长有效期;它限制的是单个游标闲置时间,不是整个浏览会话长度。若业务要求整次遍历最多十五分钟,应在第一页产生固定的会话截止时间,并让后续游标继承它。生产密钥应由正式密钥管理系统提供并规划轮换,不能把演示测试字符串放进线上配置。

接口只拼接受控结构,参数继续交给数据库

使用 Node.js 24 与 pg 8 系列。示例使用 ES module 文件扩展名,不需要额外的框架。安装依赖后提交生成的锁文件,部署使用 npm ci,避免不同环境无意获得不同依赖。先准备独立测试数据库,再执行以下命令;DATABASE_URL 换成自己的本地测试连接,不要复制生产连接。

npm init -y
npm install pg@8 --save-exact
# 在终端设置本地测试库的 DATABASE_URL
psql "$DATABASE_URL" -f schema.sql
export CURSOR_KEY="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('hex'))")"
node server.mjs

创建 server.mjs,和前面的文件放在同一目录:

import http from 'node:http';
import {readFile} from 'node:fs/promises';
import pg from 'pg';
import {codec} from './cursor.mjs';
const key=process.env.CURSOR_KEY;
if(!key) throw Error('CURSOR_KEY required');
const c=codec(key), tenant='demo'; // local demonstration only
const pool=new pg.Pool({connectionString:process.env.DATABASE_URL,
  max:5, connectionTimeoutMillis:3000, statement_timeout:3000});
http.createServer(async(req,res)=>{
  const send=(status,data)=>{res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store'});res.end(JSON.stringify(data));};
  try {
    const u=new URL(req.url,'http://localhost');
    if(req.method!=='GET') return send(405,{error:'method_not_allowed'});
    if(u.pathname==='/') {
      const html=await readFile(new URL('./index.html',import.meta.url));
      res.writeHead(200,{'content-type':'text/html; charset=utf-8'});return res.end(html);
    }
    if(u.pathname!=='/api/feed') return send(404,{error:'not_found'});
    const raw=u.searchParams.get('limit')??'20';
    if(!/^[1-9]\d?$/.test(raw)) return send(400,{error:'invalid_limit'});
    const limit=Number(raw);
    if(limit>50) return send(400,{error:'invalid_limit'});
    let p=null;
    if(u.searchParams.has('after')) {
      try {p=c.decode(u.searchParams.get('after'),tenant);}
      catch {return send(400,{error:'invalid_cursor'});}
    }
    const values=p?[tenant,p.t,p.id,limit+1]:[tenant,limit+1];
    const boundary=p?'AND (created_at,id) < ($2::timestamptz,$3::bigint)':'';
    const take=p?'$4':'$2';
    const {rows}=await pool.query(`SELECT id::text,
      to_char(created_at AT TIME ZONE 'UTC',
      'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"') AS created_at,title
      FROM feed_items WHERE tenant_id=$1 ${boundary}
      ORDER BY feed_items.created_at DESC,feed_items.id DESC LIMIT ${take}`,values);
    const more=rows.length>limit, items=rows.slice(0,limit);
    send(200,{items,nextCursor:more?c.encode(items.at(-1),tenant):null});
  } catch(e) {console.error(e.code??e.name);send(503,{error:'temporarily_unavailable'});}
}).listen(3000,'127.0.0.1');

第一页和后续页采用两个明确分支,避免把大量可空条件堆到一个查询里。拼接的 boundary 与 take 都是程序内部常量,租户、时间、编号、数量仍通过参数传入;不要把这种写法误解成允许直接拼接用户的排序字段。node-postgres 官方明确支持参数化查询,同时说明标识符不能靠普通值参数替换。参数化查询说明

查询中的 ORDER BY 特意使用表名前缀,确保按原始时间戳和 bigint 排序。SELECT 已把编号转为文本、时间格式化为字符串;如果排序写成未限定的输出别名,编号可能按字符串次序排列,倒序时二可能排在十之前,破坏分页契约。参数边界和实际排序必须使用同一种数据库类型。

每次多取一条,只用来判断是否存在下一页,真正交付给客户端的仍是前 limit 条。下一页游标来自最后一条已交付记录,而不是多取的那条,否则多取的记录会被跳过。最后一页返回 null,空结果也返回 null,这使浏览器无需再根据“这一页是不是刚好满了”猜测结束状态。

行构造器比较按字段顺序推进,因此 (created_at,id) 小于上一条的二元组,正好对应两个字段共同倒序的后继范围。若以后改成时间倒序但编号正序,不能继续照搬同一个比较式,应该展开成符合混合排序方向的条件,并重新验证索引和边界。行比较规则

连接池限制、连接等待超时和语句超时是最基本的资源边界。示例把数据库故障统一返回临时不可用,不把 SQL、连接串或内部堆栈暴露给浏览器。实际服务还需要请求速率控制、可观察的错误编号、身份校验和按租户的资源预算。它们不能靠游标签名自动获得。

浏览器必须防止旧响应覆盖新列表

创建 index.html 后访问本机三千端口。页面不依赖前端框架,便于看清状态变化:

<!doctype html><html lang="zh-CN"><meta charset="utf-8">
<title>游标分页演示</title>
<button id="refresh">刷新</button><ul id="list"></ul>
<button id="more">加载更多</button><p id="status" role="status"></p>
<script type="module">
const list=document.querySelector('#list');
const more=document.querySelector('#more');
const status=document.querySelector('#status');
let cursor=null,busy=false,done=false,generation=0,controller;
const seen=new Set();
async function load(){
  if(busy||done)return;
  const mine=generation;busy=true;more.disabled=true;
  controller=new AbortController();status.textContent='加载中';
  try{
    const q=new URLSearchParams({limit:'3'});
    if(cursor)q.set('after',cursor);
    const r=await fetch('/api/feed?'+q,{signal:controller.signal});
    if(!r.ok)throw Error(r.status===400?'游标失效,请刷新':'加载失败,可重试');
    const data=await r.json();
    if(mine!==generation)return;
    for(const item of data.items){
      if(seen.has(item.id))continue;
      const li=document.createElement('li');li.textContent=item.id+' '+item.title;
      list.append(li);seen.add(item.id);
    }
    cursor=data.nextCursor;done=cursor===null;
    status.textContent=done?'已到末尾':'';
  }catch(e){if(mine===generation&&e.name!=='AbortError')status.textContent=e.message;}
  finally{if(mine===generation){busy=false;more.disabled=done;}}
}
more.onclick=load;
document.querySelector('#refresh').onclick=()=>{
  generation++;controller?.abort();cursor=null;done=false;busy=false;
  seen.clear();list.replaceChildren();load();
};
load();
</script></html>

这里有两道不同的防线。busy 阻止用户快速连点时并发请求同一页;generation 标识当前列表属于哪一轮刷新。刷新会中止旧请求,但仍然检查代际编号,因为请求中止和响应处理存在时序竞争。只有当前代际的响应才能追加记录、更新游标并解除加载状态。AbortController 提供取消异步请求的能力,但它不能替代应用层的状态判断。AbortController 说明

失败时保留原游标,因此重试仍从同一个位置开始;成功后才推进游标。游标失效时提示刷新,不能偷偷从第一页继续追加,否则页面会混合两次遍历。列表输出使用 textContent 而非把标题拼成 HTML,避免把文章标题之类的普通数据解释为可执行标记。

seen 集合只是一层展示保护,不能修复后端漏读,也不能保证长期无限滚动的内存稳定。真实产品应限制已渲染节点数量,必要时使用虚拟列表,并决定用户返回上一屏时是保留数据还是重新请求。示例选择把这些策略留在可见边界之外,而不是用一个“生产可用”标签掩盖它们。

测试结果与尚未验证的部分

本次在 Node.js 24.22.1 环境实际运行了七项游标单元测试:大整数和毫秒往返、载荷篡改、跨租户、到期、错误签名长度、签名正确但日期非法、过长输入,全部通过;server.mjs 语法检查通过。当前环境没有 PostgreSQL 客户端或服务,因此没有执行数据库查询、测量查询计划或完成浏览器端到端测试。本文不提供虚构的毫秒延迟或吞吐量结论。

以下为完整单元测试文件 cursor.test.mjs,可在同一目录运行 node --test cursor.test.mjs:

import {test} from 'node:test';
import assert from 'node:assert/strict';
import {codec} from './cursor.mjs';
const c=codec('test-only-key-with-at-least-32-bytes');
const row={id:'9007199254740993',created_at:'2026-11-05T10:00:00.123Z'};
const token=c.encode(row,'demo',1000);
test('round trip preserves bigint and milliseconds',()=>{const p=c.decode(token,'demo',2000);assert.equal(p.id,row.id);assert.equal(p.t,row.created_at);});
test('tampered body rejected',()=>assert.throws(()=>c.decode('A'+token.slice(1),'demo',2000)));
test('wrong tenant rejected',()=>assert.throws(()=>c.decode(token,'other',2000)));
test('expired rejected',()=>assert.throws(()=>c.decode(token,'demo',901000)));
test('malformed signature rejected',()=>assert.throws(()=>c.decode(token.split('.')[0]+'.a','demo',2000)));
test('invalid signed timestamp rejected',()=>assert.throws(()=>c.decode(c.encode({...row,created_at:'2026-02-30T00:00:00.000Z'},'demo',1000),'demo',2000)));
test('oversized cursor rejected',()=>assert.throws(()=>c.decode('a'.repeat(1025),'demo',2000)));

数据库联调时,建表脚本的七条记录拥有相同时间。每页三条的预期编号依次是七、六、五,再到四、三、二,最后是一。这能直接暴露遗漏第二排序键的问题。拿到第一页后再插入一条时间更晚的记录,继续使用旧游标,预期仍从四开始;刷新后才应在首屏看到新记录。这些是待执行的验收预期,不是本次实测结果。

还应删除第一页最后一条记录后再请求下一页。本文游标保存完整排序键,不依赖回查那条记录,因此边界仍可工作。相反,如果游标只保存 id,后端还要先查它的时间,那么删除就会导致续读失效。这个测试可以帮助团队决定游标保存身份还是保存位置,二者并不是同一个概念。

性能验证应在代表性的租户数据分布上执行 EXPLAIN (ANALYZE, BUFFERS),分别观察首屏、深处游标、低命中筛选以及冷暖缓存。重点看扫描行数、过滤掉的行数、排序节点和缓冲区读取,而不是只盯某一次总耗时。小表上优化器选择顺序扫描未必是错误;反之,出现索引扫描也不等于代价已经足够低。

游标解决了位置问题,但快照仍要另外设计

默认 Read Committed 下,两次查询可能看到不同的已提交数据。游标能稳定描述排序边界,却不会冻结整个集合。只在第一页记录一个最大时间,也不能阻止后来插入的历史时间记录出现在后续页,更不能阻止字段更新或权限变化。事务隔离说明

对普通信息流,这种语义通常可以接受:新内容刷新可见,已删除内容消失,权限收回立即生效。对审计导出却未必够用。若必须交付某一时刻的完整集合,应采用专用导出任务,在受控事务或已物化的数据集上生成结果;不要让浏览器长时间持有数据库事务等待用户点下一页,那会把用户停留时间变成数据库资源占用。

这个实现真正建立的是一条可审查的链路:数据库给出唯一排序,接口无损保存边界并校验归属,浏览器只消费当前列表的响应。每一层都明确自己的保证和局限,分页才不会在数据量、并发写入或交互变复杂时突然失去解释能力。是否采用它,最终取决于产品需要连续浏览还是随机跳页,以及业务是否需要快照;这些决定应先于“换成游标更快”的技术口号。

相关文章

评论

登录后即可参与讨论

暂无评论。