etcd v3.7 RangeStream 发布后 List 请求如何评估

etcd v3.7 发布 RangeStream 后，List 请求并不是把 Range 全部替换成“流式版”这么简单。判断标准只有一个：请求结果很大、客户端不需要排序或 revision 过滤，而且消费方能逐块处理。满足这三个条件，才值得把它放进灰度名单；否则继续使用普通 Range，改造收益可能小于兼容成本。

先确认：你的 List 真的是大结果集问题吗

先从访问日志或客户端埋点整理一份请求样本，至少记录 key 前缀、返回 key 数、响应字节数、P95/P99 延迟、客户端峰值内存和是否需要全量聚合。只有“服务端和客户端都不希望一次性缓存完整结果”的请求，才与 RangeStream 的目标相符。

例如，配置中心读取几十个小 key，切换到流式 RPC 不会自动减少业务层的聚合内存；而一次列出某个租户下数十万条索引 key，才值得重点评估。RangeStream 改变的是传输和消费方式，不会替你分页，也不会让单个 value 变小。

用四个边界筛掉不能直接切换的请求

官方 API 文档还说明，未显式设置 revision 时，服务端会在流开始时捕获最新已提交 revision，并让后续 chunk 复用它。因此它适合获得一个一致的范围视图，但不代表流期间能看到持续写入的新数据。

先用 etcdctl 对照普通 Range 和 --stream

可以在测试集群或只读灰度环境先对同一前缀做对照。下面的输出是格式示意，重点是比较结果集合和退出状态，不要把示例数字当成生产基线。

# 固定 v3 API，避免客户端误走旧协议
export ETCDCTL_API=3

# 普通 Range：作为结果集合基线
etcdctl --endpoints="https://etcd.example.test:2379" get --prefix "tenant/demo/" > /tmp/range.txt

# RangeStream：逐块接收同一前缀的结果
etcdctl --endpoints="https://etcd.example.test:2379" get --stream --prefix "tenant/demo/" > /tmp/stream.txt

# 只做示意性对照；生产环境应使用不会泄露 value 的专用统计程序
wc -l /tmp/range.txt /tmp/stream.txt

两次读取应使用相同的权限、前缀和测试数据。不要在流式命令上同时添加排序或 revision 过滤；官方文档明确列出这些限制，遇到 Unimplemented 时应把请求退回普通 Range 或改写查询目标。

如果是 Go 客户端，消费层有两种选择：收到一个 chunk 就解码并处理，或收齐后用 clientv3.GetStreamToGetResponse 组装成接近普通 Get 的响应。第一种才能真正降低客户端峰值内存；第二种主要解决 API 迁移，内存收益会打折。

发布后的灰度指标怎么定

不要只拿“首个 chunk 到达更快”作为结论。至少把以下四项放到同一张实验表：结果是否完整、P99 总耗时、客户端 RSS 峰值、流中断和重试次数。对业务还要补一项：逐块处理是否允许部分副作用。如果收到前两个 chunk 后业务已写入外部系统，第三个 chunk 失败就必须能幂等重试或回滚。

建议先挑一个无排序、无历史 revision、直连 etcd 的大前缀请求做 1% 灰度；完整 key 数与普通 Range 对齐，再逐步提高比例。任何一个核心指标恶化，先回退调用方式，不要同时升级 key 模型、权限和重试策略，否则很难定位变化来源。

常见问题

RangeStream 会不会读到多个 revision 的数据？

不会。未指定 revision 时，流开始会确定一个最新已提交 revision，后续 chunk 使用同一视图；但如果流异常结束，不能把已收到的片段当成完整成功结果。

结果小也应该统一使用 --stream 吗？

不建议。小结果集通常没有明显的缓冲压力，普通 Range 的接口更简单；统一切换只会扩大测试和兼容面。

经过 gRPC proxy 的 List 能直接打开 RangeStream 吗？

不能直接假设支持。etcd v3.7 API 文档明确说明 RangeStream 不支持 etcd gRPC proxy，应保留普通 Range 或调整网络拓扑后再评估。

最终清单可以很短：大结果集、无需排序、无需 revision 过滤、直连 KV、客户端能处理中断并具备幂等性，就进入灰度；其余请求保持原实现。这样评估的重点是“哪个 List 值得改”，而不是“发布了新 RPC 就全部迁移”。