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