Table of Contents

扫描与游标契约(scan-cursors)

适用面:TierKv / TierVarKv / TierCollections(Hash/Set/ZSet)/ TierTimeSeries / TierQueue / TierLog / TierBlob 的读取遍历面——standalone 与副本档同一契约(副本 = read-local 透传)。 本文是四族扫描的统一游标契约单一真源;各产品文档与本页交叉引用,不再各自复述保证口径。

1. 两种遍历形态

形态 面 语义
全量流(IAsyncEnumerable 一次性枚举) TierKv ScanByPrefix/Range(+WithExpiry)、TierVarKv ScanByPrefixAsync、TierTimeSeries Range/RevRange、TierQueue ReadRangeAsync、TierLog ReadFromAsync/TailFollowAsync、TierBlob ListAsync 调用方逐条消费到流自然结束;无断点续传面(中断即重来)
分页游标((Items, NextCursor) 状态分页) TierHash HScanAsync、TierSet SScanAsync、TierZSet ZScanAsync 每页 count 上限;cursor = Empty 从头起;NextCursor = Empty 遍历完;凭 NextCursor 跨调用续传

两种形态的产出序与保证口径一致(见 §2)——分页游标只是把同一次遍历切成可续传的状态段。

2. 统一保证口径(有限保证)

全部扫描/遍历面 = Ring 记录追加序地址游标(TierKv 定长键的范围索引游标在字节线序上等价), 保证口径与 Redis SCAN 族同构的有限保证:

  1. 静态集无重无漏:遍历窗口内集合不变化时,产出不重不漏;存活条目恰好产出一次。
  2. 遍历窗口内新写入可不产出:地址序游标不回溯——扫描开始后写入的条目可能不出现 (快照游标语义,非实时视图)。需要「扫描起点一致性」的点读走 ReadPolicy 共识读(Kv 族)。
  3. 已删/重写条目跳过:墓碑不产出;同键重写换绑地址后按点查索引存活判定,仅新地址产出一次。
  4. 产出序 = 追加序(非业务全序):按记录追加地址序产出。TierKv 的 ScanByPrefix/Range 走范围索引(key 字节线序);ZSet 的确定性 (score, member) 全序遍历走 ZRange/ZRangeByScore 族(非游标面——段内按 ZSetEntryOrder 稳定化)。
  5. 游标生命周期:分页游标 = Ring 逻辑地址,易失锚——引擎重启后地址空间重建, 旧游标不可跨进程复用;域回收/截断推进 BeginAddress 越过游标后,旧游标不保证完整产出 (续传前比对新 BeginAddress,越线从头重扫)。
  6. 流式消费取消:全量流经 CancellationToken 逐条检查取消;分页游标单页内不可中断 (单页 ≤ count 有界)。

3. 副本档语义(applied 态流)

副本门面(TierKvReplica / TierVarKvReplica / Collections 副本等)的扫描 = read-local 透传 本地引擎(apply 追平即一致,零共识):

  • 扫描跨多键,无逐键线性化——产出为「本地已应用态」的流;流推进期间状态继续前进 (§2.2 快照游标语义的副本形态)。单键一致性读走 TryGet* 的 ReadPolicy 三档(裁定⑮)。
  • 副本扫描不做一致性等待、不进提案管道——follower 与 leader 扫描同一契约,延迟 = 复制滞后。
  • 双入口等价:直连 Builder 与 hub spec 委托是同一份装配代码(裁定③),扫描面行为逐位一致。

4. 装配前提与权限判定

  • TierKv 扫描前提 = TierKvOptions.WithRangeIndex(true)(范围索引缺省关——写放大 显式选择;副本档语义面同本地档,不静默强开,未启用时扫描 InvalidOperationException)。 TierVarKv 的有序索引为结构性组件,无装配开关。
  • hub 数据权限(W-perm 区域全含校验):扫描/订阅前缀参数按整区域裁决非单键—— 区域内任一键被 Deny 规则覆盖即整体拒绝(HubAccessPolicy.CheckRange/AuthorizeRange, 拒绝审计 authz_range_denied;漏判方向 fail-closed)。详见 hub-permissions.md; TierKv 定长键范围扫描的 [start, end) 区间按字节序区间整体判定。

5. 反模式

  • 拿扫描当轮询谓词:消费型调用反复执行后重验(订阅变更流 Watch 才是增量语义)。
  • 游标持久化:跨进程/跨重启复用分页游标(§2.5 易失锚)。
  • 假设业务全序:按追加序扫描后假设 (score, member) 全序(ZSet 全序遍历走 ZRange 族)。
  • 副本扫描当线性izable:逐键线性化不存在(§3)——一致性敏感判定用单键共识读。