企业官网建设流程全解析

• 数据库
• 文档数据库
• 后端

本文基于 CouchDB 官方 RFC 文档 014-pagination.md 展开，完整解读该提案为解决 FoundationDB 存储引擎事务限制而引入的书签式分页方案：从动机、适用端点、核心查询参数（page_size、bookmark）、响应字段（first/previous/next）到逐条实现语义与request_limits配置，并结合当前仓库源码说明该方案在chttpd模块中的落点与现状，帮助读者掌握一套服务端驱动、客户端无需自行维护翻页逻辑的分页接口设计。

背景与动机：为什么需要服务端分页方案

RFC 开篇即给出了提案的核心驱动力：引入 FoundationDB 作为存储引擎。FoundationDB 对事务的持续时间和大小都有硬性限制，因此必须找到一种方式限制返回给客户端的数据量。

一个最直接的“解法”是设置limit的最大值，将客户端可请求的行数封顶。但 RFC 明确指出这种方案的致命缺点：它会迫使客户端在应用代码中自行编写翻页逻辑。而现有的基于limit+skip/键游标的分页方式在客户端侧逻辑相当复杂，存在不少需要处理的边界情况（corner cases），例如：

• 翻页过程中数据库发生变化（新增/删除文档）导致基于skip的偏移错位；
• 客户端需要自行记忆“上一页最后一条”的位置并在请求中回传；
• skip值过深时性能急剧退化。

为此，RFC 014 提出引入一套书签式（bookmark-based）分页机制：由服务端在响应中返回不透明（opaque）的书签令牌，客户端只需把令牌原样带回请求即可定位到下一页/上一页，无需理解其内部结构，也无需重复携带初始查询参数。

术语定义

RFC 对关键术语给出了严格定义：

• bookmark：一个不透明令牌，包含检索被书签化页面所需的全部信息。客户端 MUST NOT 依赖该令牌的具体格式（即服务端可以随时更换编码方式而无需通知客户端升级）。

文档采用 RFC 2119 的需求语言规范，其中 "MUST"、"MUST NOT"、"SHALL"、"SHOULD"、"MAY"、"OPTIONAL" 等关键词具有规范性含义。

适用范围：哪些端点纳入分页，哪些暂缓

RFC 将新增书签分页机制应用于所有“查询类”端点。第一步（first step）中，以下端点被明确排除在范围之外，且 RFC 给出了逐条理由：

纳入范围的端点共有 4 个：

• {db}/_all_docs
• {db}/_all_docs/queries
• {db}/_design/{ddoc}/_view/{view}
• {db}/_design/{ddoc}/_view/{view}/queries

概括来说，核心思路是三件事：

1. 新增page_size查询字段，用于控制每页行数，同时作为“客户端期望分页式响应”的标记；
2. 在响应体中新增first、previous、next字段，其中包含书签部分（即带 bookmark 查询键的 URI 片段）；
3. 新增bookmark查询字段，用于按书签检索指定页。

实现提案：四步落地路径

RFC 的Implementation proposal部分给出了清晰的四步实施路径，这部分是工程落地的主干，值得逐条理解。

1）新增可选查询字段bookmark

在以下 4 个端点上添加新的可选查询字段bookmark：

• {db}/_all_docs
• {db}/_all_docs/queries
• {db}/_design/{ddoc}/_view/{view}
• {db}/_design/{ddoc}/_view/{view}/queries

客户端把上一次响应中next/previous/first返回的书签令牌作为bookmark参数传回，即可直接定位对应页。

2）新增可选查询字段page_size

page_size承担双重职责：

• 设定每页返回的行数；
• 作为模式开关——只要设置了page_size，请求就走上分页端点（paginated endpoint）的代码路径；未设置则沿用旧代码路径。这一设计保证了向前兼容：存量客户端完全不感知新机制。

3）按端点可配置的最大行数限制

新增按端点可配置的最大上限（per-endpoint configurable max limits），用于约束分页响应的页大小。RFC 给出的示例配置为：

[request_limits] _all_docs = 5000 _all_docs/queries = 5000 _all_dbs = 5000 _dbs_info = 5000 _view = 2500 _view/queries = 2500 _find = 2500

可以看到，_all_docs类端点允许单页最多 5000 行，而视图/查找类端点（_view、_find）上限为 2500 行——视图查询涉及 JS 函数执行，单页成本更高，上限相应更保守。

4）响应体新增书签字段

分页响应中追加如下字段：

"first": "12345678945621321689", "previous": "983uiwfjkdsdf", "next": "12343tyekf3"

三个字段分别指向：第一页、上一页、下一页对应的书签。客户端只需把令牌拼入bookmark查询参数发起新请求即可跳转。

语义细则：分页行为的完整规则集

RFC 的Semantics of the implementation一节是整个提案最核心的规范性内容，逐条定义了分页行为的边界。这里完整梳理：

请求与参数层面

• 仅 GET 方法支持分页。
• 当提供bookmark字段时，不使用延迟响应（delayed responses）。
• 当指定page_size且其值低于最大限制时，不使用延迟响应。
• 当bookmark字段与其他查询字段同时存在时，返回 400——即书签请求必须“纯净”，防止客户端携带与新令牌矛盾的过滤条件。
• 当page_size超过该端点最大限制时，返回 400。

默认值推导规则

page_size的默认值按两级推导：

1. 如果请求提供了limit，且该limit小于default.ini中该端点在request_limit下配置的值，则page_size默认取limit；
2. 否则，page_size默认取default.ini中该端点在request_limit下配置的值。

换言之，limit与page_size共存时以用户显式limit为准（只要不超限），完全未指定时回落到服务端配置上限。

翻页终止与边界

• 一旦达到limit（请求指定的总行数上限），最终响应中不再携带next书签。
• previous/next/first三个键均为可选，在“没有意义”的场景（如第一页没有previous、末页没有next）下会被省略。
• 当底层对 FoundationDB 的调用返回的行数少于page_size时，响应中同样不携带next书签——这是判定数据已取完的最主要信号。

skip的限制

skip查询参数的最大值被限制为：page_size与request_limit配置值中较小者。这从机制上杜绝了“超大 skip 深度翻页”带来的性能陷阱，也印证了书签方案对skip分页的替代定位。

批量查询端点的特殊语义

对_all_docs/queries与{db}/_design/{ddoc}/_view/{view}/queries这类批量查询端点，RFC 定义了更精细的规则：

• 使用page_size时，指定的 limit 应用于请求中提供的查询数量（即一次批量请求里能带多少条查询）；
• 这类端点返回的总行数不应超过提供的page_size或配置的最大限制（取较小者）——即限制的是整批查询结果的总行数，而非单条查询。

请求体中甚至可以为每条查询分别携带各自的书签：

{"queries": [ {"bookmark": "bookmarkForQuery1PageL"}, {"bookmark": "bookmarkForQuery2PageM"}, {"bookmark": "bookmarkForQuery3PageN"} ]}

并且，_all_docs/queries与视图/queries端点返回的每一个书签，都可以单独提交给对应的_all_docs或{db}/_design/{ddoc}/_view/{view}端点来继续翻页。这保证了批量端点与单端点在分页状态上的互通：客户端既可以整批继续，也可以拆开逐条继续。

事务语义

分页请求受 FoundationDB 事务超时约束。RFC 说明这一点通过“在 FDB 调用中不提供{restart_tx, true}选项”来实现——即分页查询不会像某些长事务路径那样自动重启事务，事务超时即失败，从而强制单次请求保持在事务限制之内。这正是分页方案服务于 FDB 引擎约束的直接体现。

已知限制（Limitations）

RFC 坦率地列出了方案的两个固有限制：

1. URI 长度约束：响应中的first/next/last键以“包含 bookmark 查询键的路径”形式表示。这意味着书签令牌的大小会直接计入总 URI 长度，并受最大 URL 长度（约 2000 字符）的限制。由此推导出一个重要的设计禁令：书签中不能存放keys列表（因为键集合可能很大，会让 URI 膨胀超限）。这也是为什么启用分页时不支持 POST 方法——POST 请求可以携带keys数组体，而分页后的书签请求必须能装进 GET URI。
2. 流式响应无法回退错误码：理想情况下，当流式（streaming）版本端点返回的行数超过request_limit配置时，服务端希望能返回 400 告诉客户端。但流式响应在发送第一字节时 HTTP 返回码已经发出，无法再改为 400——这是 HTTP 协议与流式输出之间的天然矛盾。

配置：request_limits配置段

页大小上限通过default.ini（或其他ini配置文件）中的request_limit段进行配置：

[request_limits] _all_docs = 5000 _all_docs/queries = 5000 _all_dbs = 5000 _dbs_info = 5000 _view = 2500 _view/queries = 2500 _find = 2500

需要注意 RFC 中一个细节：正文配置段名写作request_limits，而语义章节中称为request_limit段——两者指代同一按端点配置上限的机制。该配置同时服务于page_size的默认值推导与最大值校验两处语义。

结合仓库源码看方案现状

结合当前仓库的代码结构，可以对 RFC 的落地现状与周边实现补充几点观察：

• 受影响模块：RFC 明确本次变更影响的模块为chttpd，查询请求的分发入口位于 chttpd_handlers.erl 与 chttpd.erl。分页的开关判断、400 校验与响应字段注入，从影响面看都应落在该层。
• 当前主干尚未实现该功能：在整个仓库范围内检索不到request_limits配置段，Erlang 源码中也不存在page_size查询参数的解析逻辑；发行配置 default.ini 中同样没有该段。因此可以判断，截至当前仓库版本（main分支），RFC 014 描述的书签分页仍处于提案/待实现状态，文章所述的语义与配置应视为目标设计而非现存行为。
• “书签”概念在仓库中已有先例：全文检索搜索（dreyfus / nouveau）早已采用 bookmark 参数实现跨页检索，相关实现可见 dreyfus_bookmark.erl、nouveau_bookmark.erl，其 API 文档见 search.rst。搜索端点的书签是不透明编码（客户端不依赖其格式），与 RFC 014 对_all_docs/视图分页书签的定义精神一致，可作为理解该令牌化设计的参照。
• 相关端点的现有文档：_find端点文档 find.rst 中已出现 bookmark 相关内容，说明书签参数在 Mango 查询路径上已有铺垫，未来_find纳入request_limits上限（配置示例中_find = 2500）与既有机制是衔接的。

从源码结构看，该 RFC 的实施路径将与搜索侧既有的书签编解码基础设施存在复用空间，而chttpd层需要新增的主要是模式判断（是否走分页路径）、参数互斥校验与响应字段封装。

Roadmap 与关键变更

Roadmap

RFC 给出了分阶段路线：

1. 按本文档完成初始实现；
2. 制定API 版本化（API versioning）提案并据此实现该特性——这解释了为何_all_dbs/_dbs_info暂时排除：它们的响应类型需要从列表变为对象，属于破坏性变更，必须借助版本化 API；
3. 为_changes端点单独制定提案；
4. 实现启用分页的_all_dbs与_dbs_info版本（借助版本化 API 特性将响应类型改为对象）。

关键变更清单

• 新增配置段（request_limits）；
• 新增查询字段（bookmark、page_size）；
• 响应体新增字段（first、previous、next）；
• 对客户端请求行数实施严格上限约束。

RFC 声明：无 HTTP API 新增（N/A）、无 HTTP API 弃用（N/A），安全模型无变化。

总结

RFC 014 的价值在于把“分页状态”从客户端迁移到了服务端：客户端只需持有并回传不透明书签令牌，不再需要自行维护skip偏移、游标位置等易错逻辑；而服务端借助page_size上限与 FDB 事务约束（不提供{restart_tx, true}），把单次请求的数据量严格框定在 FoundationDB 事务限制之内。其设计要点可归纳为四条：

1. 不透明书签 + 仅 GET：令牌格式与客户端解耦，同时以 URI 长度约束倒逼出“书签内禁存 keys、禁用 POST”的规则；
2. page_size双职责：既是页大小又是分页模式开关，未设置时完全走旧代码路径，保证兼容；
3. 端点级上限配置：[request_limits]段按端点差异化配置（5000/2500），并参与page_size默认值推导与 400 校验；
4. 批量查询的按查询书签：/queries端点支持每条查询携带独立书签，且批量端点返回的书签可回落到单端点继续翻页。

由于该 RFC 当前仍处于提案阶段（仓库中尚无对应实现），对关注 CouchDB 4.0 演进路线的读者而言，这份文档定义的分页语义——尤其是参数互斥规则、终止信号（无next书签）与事务超时行为——是预判未来客户端应如何编写分页代码的最权威依据。

• 数据库
• 文档数据库
• 后端