YANG 列表分页：游标不是数据快照

摘要

第 13 版草案明确规定 where、sort-by、locale、direction、offset 或 cursor、limit 的处理顺序，并把 sublist-limit 留给下层集合。
这些机制能证明一次分页请求如何构造、从何处继续，却不能单独证明排序是全序、NACM 视图未变化、多个后端共享同一时点，或所有嵌套数据已经取全。

分页最容易制造的一种错觉，是把“下一页从正确位置开始”误读成“下一页仍属于刚才那份数据”。前者是位置连续性，后者是时间一致性。draft-ietf-netconf-list-pagination-13 把前者表达得相当精确，但没有声称提供后者。真正可靠的运营记录，首先要尊重这条边界。

草案第 13 版于 2026 年 7 月 6 日提交。IETF Datatracker 当前把它列为 NETCONF 工作组的活跃 Internet-Draft，目标为 Standards Track，工作组状态是 In WG Last Call，带有 Revised I-D Needed - Issue raised by WGLC 标签，IESG 状态为 I-D Exists。当前 YANG Validation 面板汇总显示三项错误；可见的 pyang 与 yanglint 输出都指向模块文本同一处附近的反斜线换行/转义问题。这只能说明现行文稿及验证工具的状态，不能推导某个实现、部署或真实页面已经出错。

草案固定的是提问方式

处理链从 where 开始。服务器先以 XPath 1.0 表达式确定候选集合，再用 sort-by 选择排序字段；locale 为该排序提供语言区域语境。随后，direction 与 offset 或 cursor 共同确定遍历方向和起点，limit 最后限制目标列表返回多少条。sublist-limit 不控制目标列表，而是限制每条结果内部的后代 list 与 leaf-list。

使用游标时，客户端以 cursor=first 初始化遍历，并在这一步提交 where、sort-by 和 locale。服务器生成的 next 与 previous 链接承载最初的查询语境；后续请求只能调整 limit 与 sublist-limit。因此，客户端不能在中途悄悄换一个过滤器或排序字段，再把两段结果称为同一次遍历。

这是对“问题”的完整保护，不是对“答案所依据的世界”的冻结。草案没有定义快照标识、统一读取时间、事务编号、跨后端修订向量或一致性屏障。下一次请求可以原封不动地复现问题，同时面对已经发生变化的数据。

offset 与 cursor 互斥。offset 只是跳过若干条记录；边界之前新增或删除对象后，相同数字会指向不同的逻辑位置。游标是客户端不可解读的底层索引或键，能让服务器自己决定如何续接，通常比纯计数更稳健。但它只描述边界，不支配其他对象的增删与排序键变化。

RESTCONF 伴随草案进一步写明：服务器不保留关于下一页、上一页或其游标的有状态信息。续页链接不是被预留结果集的票据，而是一条稍后重新执行的指令。无状态性有利于扩展，也恰恰说明不能把链接当成快照证明。

排序字段不一定形成全序

若没有 sort-by，使用 YANG 列表自身的顺序。指定字段后，没有该字段值的条目排在有值条目之后。locale 不能脱离 sort-by 使用；客户端不指定时，服务器自行选择，并通过 YANG 元数据把实际采用的 locale 返回。

记录 locale 很重要，因为它消除了一个隐性的机器默认值。但 BCP 47 标签并没有同时声明排序库、Unicode 数据版本、规范化方法和同值时的判定规则。两个联邦后端都接受相同的语言标签，仍可能把重音、大小写或等价字符放在不同位置。

草案还明确没有次级排序。两个接口可能同名，两条路由可能具有同一度量，多个资源也可能共享一个时间戳。分页边界若落在这个同值组中，稳定顺序就依赖没有出现在请求里的内部判别项。重启、换节点或升级索引后，同值项可重新排列，而主排序字段仍然完全正确。

因此，证据系统必须保存服务器实际用于破同值的键，或明确承认这里只得到偏序。只写“按名称排序”不足以证明某个边界可以被重现，更不能证明跨页没有重项或漏项。

能力声明与运行事实是两层证据

config false 列表常常庞大、实时而且查询成本高。第 13 版通过 RFC 9196 的 system-capabilities 模型，让服务器按节点声明 constrained、列出可用的 indexed 子节点，并说明是否支持 cursor-supported。对受约束列表，任意 XPath 可以被禁用，过滤与排序只能引用索引节点，表达式也不能穿过子列表继续下钻。

这让能力协商更诚实：客户端可以在提交昂贵查询之前知道服务器宣称支持什么。不过，声明某节点有索引，并不能证明这次请求确实走了该索引、索引已追上最新状态，或所有参与构造 operational 视图的数据源处于同一版本。RFC 9196 的能力本身还可能随硬件、许可证或运行条件改变，所以每一页都应绑定当时的能力集身份。

RFC 8525 的 YANG Library content-id 解决的是模块与模式集合的身份。它能证明客户端用哪套结构解释数据，却不是数据内容的版本号。把它视为快照 ID，就像把字典版本当成用该字典描述的现场照片。

NACM 会改变可见集合

RFC 8341 的 NACM 可以按主体限制操作和内容。相同的 where 实际运行在该主体被允许看到的集合上。如果翻页期间组成员、规则或对象权限变化，第二页的候选集合也随之变化，即使游标仍有效、查询语句完全相同。

BTW 已有关于 RFC 9865 SCIM 游标的文章，核心是持有游标不能延续已经撤销的访问权。本篇不重复那一问题。这里关心的是：即使每一页都重新做了正确授权，两次不同的授权视图也未必能拼成一份一致清单。逐页合法不等于跨页完整。

因此要为每个请求保留主体、NACM 策略身份、匹配规则与有效视图。策略发生变化时，结果应被描述为“在两种授权视图下取得的页面”，而不是悄悄抹平差异，声称获得了一张完整列表。

operational 数据不会为分页暂停

RFC 8342 区分 intended 与 operational 等数据存储。operational 视图包括已应用配置和系统状态，还可能汇集多个来源。路由持续收敛，计数器不断增加，接口会上下线，租约会过期。分页让这片变化的表面能够被读取，却没有让它停止变化。

假设第一页结束在排序键 m。一个原来位于 m 之前的对象把键改成 z，它可能在后续页面再次出现；原来在后面的对象改成 a，则可能彻底越过游标而未被看见。删除会让 offset 多跳一条，插入会导致重复。即使游标稳定地依附某个对象键，也不能冻结其他对象或同步多个联邦后端。

若底层系统能提供共同快照或修订向量，应把它与每一页绑定。若不能，就应保存各页和各来源的观测时间，检查重复、缺口与边界倒退，并把最终产物标注为一个时间窗内的遍历。时间窗清单仍可用于运营；把它包装成单一时点事实才是证据错误。

顶层取全不代表子列表取全

limit 约束目标 list 或 leaf-list。sublist-limit 单独约束结果对象中的下层集合。服务器可以用 remaining 返回正整数，也可以诚实地给出 unknown。因此，取全所有设备并不能证明每台设备的接口、地址或路由也已经取全。

每个被截断的子列表都会分叉出自己的证据链：父对象身份、查询语境、续页游标、响应哈希、剩余数量或未知状态。只记录顶层完成、丢弃这些分支，就是把容器完整性误当成内容完整性。最终证明结构应是一棵树，而不是一条游标链。

逐页证据封套与汇总记录

运营方可以在草案之外建立更强的证明。每一页保存：认证主体与 NACM 策略身份；数据存储；YANG Library 内容身份；能力集身份；所有参数；请求与响应哈希；游标谱系；返回对象键及排序值；remaining 注释；服务器时间；参与后端及其修订；所有错误。

另建一份汇总记录，专门检查重复键、预期缺口和边界倒退，比较前页最后一个排序元组与后页第一个元组，标出策略、能力、locale 或来源版本变化，并给结果定性：共同快照、有限不一致读取，还是变化期间的连续观测。

这些是运营证据设计，不是第 13 版已经强制服务器提供的功能。实时数据并非总能、也并非总应被冻结。高质量决策的关键，是让结论与仪器相称。游标可靠地说明下一次应从哪个位置继续；它没有替整个数据集记住同一个时刻。

第一方资料

游标记住了位置，却不知道那一刻

为何重要

摘要

草案固定的是提问方式

排序字段不一定形成全序

能力声明与运行事实是两层证据

NACM 会改变可见集合

operational 数据不会为分页暂停

顶层取全不代表子列表取全

逐页证据封套与汇总记录

第一方资料

档案背景详情

Strategic Circle

Leadership Alliance

Strategic Circle 专属简报

Leadership Alliance 简报