求适用于仅可单次迭代集合的优质API及相关行为规范

嗨，这个问题问得很到位，刚好我对这类单次迭代的集合（常称为“消耗型迭代器”或者“一次性集合”）有不少了解，来给你梳理下：

这类集合的核心特点是数据不可复用、迭代即消耗，适配的API通常围绕“惰性处理”和“明确状态管理”设计：

• 惰性流处理API：几乎所有主流语言都有这类原生或标准库支持，比如Java的Stream、Python的生成器（generator）、C#的IEnumerable（当底层绑定单次数据源时）。它们的操作（过滤、映射、聚合）都是惰性执行，不会提前缓存全量数据，完美匹配分页网络API的代理场景——每一次迭代才触发下一页数据的拉取。
• 专门的一次性集合工具：部分第三方库提供了明确的单次迭代封装，比如Guava的ForwardingIterator（允许你自定义迭代耗尽后的行为），或者Python的itertools系列工具，比如itertools.islice可以安全截取单次迭代的部分内容，避免误触重复遍历。
• 自定义带状态的迭代器：如果没有现成工具，你可以手动封装迭代逻辑，维护一个isConsumed状态标记。第一次迭代完成后标记为已消耗，后续操作按你的需求处理（比如抛出异常）。

业界并没有绝对统一的强制规范，但有几个被广泛认可的处理方式：

1. 静默返回空集合：这就是你当前遇到的情况，很多分页API代理集合会采用这种方式——因为第二次迭代时，分页游标已经走到末尾，没有更多数据可拉取，所以表现为空。好处是不会打破上层代码“迭代空集合不报错”的默认预期，但缺点是容易让开发者误以为集合本身为空，增加排查问题的成本。
2. 抛出明确异常：这也是你偏好的方式，它完全符合“快速失败（fail-fast）”的设计原则，能让开发者立刻意识到这个集合是一次性的，避免误用。比如Java中部分自定义迭代器会抛出IllegalStateException，明确提示“集合已被消耗，无法再次迭代”。这种方式在需要严格避免误用的场景下更推荐。
3. 重置并重新拉取数据：这种方式最少见，因为会额外消耗网络资源，而且两次迭代可能得到不同的结果（如果API数据更新了），只有在特定业务场景（比如允许重复查询最新数据）下才适用。

如果是你自己实现这个分页API代理集合，我强烈建议采用抛出异常的处理方式，它能更早暴露误用问题，降低后续调试成本。如果是使用第三方库，可以查看它的文档，有些库会提供配置项让你切换迭代耗尽后的行为。

内容的提问来源于stack exchange，提问作者Ben Clifford