~/notes/omnigate-03-cursor-pagination-and-summary-consistency.md1412 字

项目实战Omnigate 网关开发学习笔记 · 03/03

Omnigate(三):游标分页如何保持明细与汇总一致

结合 useReportPage 和用量分析页,讲解服务端分页、前端分段展示、筛选重置及 as_of 查询上界的作用。

目录 5 节

网关记录会随着调用不断增长,请求追踪、用量分析和账本都需要面对持续增加的数据。把全部记录拉到浏览器,再筛选和切页,既增加传输与解析开销,也容易让统计口径依赖页面实现。

本篇聚焦 Omnigate 最近一轮控制台分页改造,先区分两种分页,再沿 useReportPage 看筛选、游标和汇总怎样对齐。

一、控制台的全量加载开始暴露问题

后端能处理请求,并不代表管理页面能长期承受数据增长。

请求追踪、用量分析和账本都是持续增长的数据。如果页面先把所有记录拉回来,再用前端数组筛选、汇总和切页,数据量一大,就会同时拖慢网络传输、JSON 解析、浏览器内存和表格渲染。

最近一轮调整,把这几类页面切换到已有的服务端分页能力,并让用量汇总由服务端计算。审计日志也接入服务端游标分页。

这里需要区分两种改动:

数据类型 当前处理方式 解决的问题
请求、用量、账本、审计明细 服务端分页 限制单次明细读取量和页面渲染量
API Key、模型组等配置列表 前端分段展示 限制同屏 DOM 数量

配置列表的前端分页仍然会持有已经取得的列表,它主要解决渲染压力,不能据此声称网络和内存也都变成了按页加载。后续如果配置规模继续增长,再补齐相应的服务端分页。

二、分页之后,统计口径更容易出错

页面只取一页后,有个很常见的错误:把本页的 Token 和成本相加,放到顶部当成全部用量。

这会导致统计随着翻页变化。用户明明没有修改筛选条件,只是点了下一页,“总成本”却换了一个数字。

Omnigate 的用量分析将明细和汇总分开读取:/user/usage/page 提供一页记录,/user/usage/summary 负责汇总。两者使用同一组筛选条件,并通过同一个 as_of 上界对齐查询范围。

这个上界用来避免查询明细和查询汇总之间新写入的数据被纳入不同范围;它并不等同于把所有数据冻结在一个长期数据库事务里。

前端的 useReportPage 集中维护筛选签名、各页游标和查询上界。筛选变化后,旧游标和旧汇总一起清空;继续向后翻页时使用已取得的游标,没有对应游标时可以回退到 offset。旧请求的迟到结果也会被忽略,避免覆盖新的筛选结果。

这些细节决定了页面能否准确回答三个问题:这批数据属于什么条件、截止到什么时候、顶部数字是否覆盖完整结果。

frontend/src/hooks/useReportPage.ts 的读取参数可以缩成下面这段:

const cursor = walk.current.cursors[page];
const result = await load(filters, {
  pageSize,
  cursor,
  offset: cursor ? 0 : Math.max(0, page - 1) * pageSize,
  asOf: walk.current.asOf,
});

walk.current.asOf = result.as_of;
if (result.next) {
  walk.current.cursors[page + 1] = result.next;
}

这是流程示意,完整 hook 还包含去抖、错误状态和旧响应处理。重点在于,页码只用于页面交互,后端继续读取的位置由游标决定,查询上界由 asOf 保持。

存储层的 RowCursor 包含时间和记录 ID。时间相同的多条记录需要 ID 继续确定位置,避免只用时间作为边界时漏读。筛选条件变化后,这个位置已经属于另一批数据,因此必须丢弃旧游标。

三、筛选改变后,旧响应不能覆盖新结果

分页状态重置之后,已经发出的旧请求仍然可能返回。如果不检查请求生命周期,旧结果就会覆盖新筛选下的页面。

useReportPage 在 effect 中维护取消标记。省略状态字段后的结构示意如下:

useEffect(() => {
  let cancelled = false;
  load(filters, paging).then(result => {
    if (cancelled) return;
    setState(result);
  });
  return () => { cancelled = true; };
}, [signature, page, pageSize, enabled]);

这段示意只表达生命周期判断,完整实现还处理去抖、返回字段映射和错误分支。setState(result) 不是原项目可直接替换的完整写法。

取消标记阻止旧结果写入,并不意味着网络请求已经被中断。它与清除游标解决不同问题:清除游标避免在新条件下继续旧位置,取消标记避免迟到数据覆盖当前结果。

四、从页面状态追到存储游标

建议先看 frontend/src/hooks/useReportPage.ts,再看 frontend/src/v2/pages/user/UserAnalysisPage.tsx 如何用相同条件请求明细和汇总,最后对照 crates/og-store/src/model.rs 中的 RowCursor。

截至 2026 年 10 月 6 日,这些读取路径和展示改动已进入仓库。本文没有重跑整个项目的测试,也没有测量生产负载。前端分段展示解决的主要是渲染量,服务端分页限制的是单次明细读取量,查询上界则用于对齐统计范围;评估效果时需要分别看这三个目标。

本系列对应仓库目前为私有,代码片段取自已核对的实现;删去的字段或流程已在相关段落注明。

系列阅读

上一章:Omnigate(二):流式响应的提交点与账号健康状态

  1. Omnigate(一):用 CIR 中间表示拆开协议转换
  2. Omnigate(二):流式响应的提交点与账号健康状态
  3. Omnigate(三):游标分页如何保持明细与汇总一致