1. 从一次线上遍历事故说起Java 迭代器模式到底解决什么问题很多人第一次接触 Java 迭代器模式Iterator Pattern是在for (String s : list)这种语法糖里。编译器帮你把增强 for 循环翻译成Iterator的hasNext()和next()调用你几乎感觉不到它的存在。可一旦你开始写自己的容器类或者需要在遍历过程中安全地删除元素迭代器模式就从「背景板」变成了必须正面处理的核心设计。我遇到过一个很典型的问题团队里有人写了一个固定容量的环形缓冲区对外只暴露get(int index)和size()。调用方为了遍历直接写for (int i 0; i buf.size(); i)。看起来没问题直到有人需要在遍历时按条件移除元素于是出现了下标错位、元素被跳过、甚至IndexOutOfBoundsException。根因不是代码写得差而是这个容器没有提供统一的遍历抽象——它把内部存储结构数组下标暴露给了调用方调用方就得自己维护遍历状态一旦容器内部结构调整所有调用点都要跟着改。迭代器模式要解决的就是这件事把「遍历状态」从容器里剥离出来交给一个独立的迭代器对象持有。容器只负责存数据迭代器负责记录「我现在走到哪了」。这样带来三个直接好处。第一调用方不需要知道容器底层是数组、链表还是树只需要拿到一个Iterator就能用同一套hasNext()/next()逻辑遍历。第二同一个容器可以同时开多个迭代器各自维护各自的游标互不干扰。第三遍历算法可以替换正序、倒序、按条件过滤都可以是不同的迭代器实现而容器本身不用动。在 Java 集合框架里这套思想已经落地得很彻底。Collection接口继承了IterableIterable定义了iterator()方法List、Set、Queue各自提供具体迭代器。ArrayList用内部类Itr实现LinkedList用ListItrHashMap用HashIterator。它们都遵循同一个契约hasNext()判断是否还有元素next()返回下一个元素并推进游标remove()删除最近一次next()返回的元素。但真实项目里光会用 JDK 自带的迭代器还不够。你可能会遇到这些场景自定义数据结构需要支持for-each需要在遍历时按业务规则过滤需要倒序遍历一个只提供正序迭代器的容器或者需要把多个容器的遍历统一成一个接口。这些都需要你自己实现Iterable和Iterator。这篇内容就围绕「Java 迭代器模式实战」展开。我会先讲清楚Iterator接口的契约和hasNext/next/remove的行为边界然后带你写一个自定义Iterable容器给出可复制的配置片段再演示在 IDE 里验证遍历行为的完整步骤。过程中会结合 TaoToken 的统一 Key 和 API 通道让 AI 辅助生成迭代器代码、排查遍历异常。如果你正在写自己的集合类或者被ConcurrentModificationException折腾过这篇应该能帮你把迭代器模式真正落地。2. 前置准备用 TaoToken 统一 Key 接入 AI 辅助生成迭代器代码在开始写自定义迭代器之前先把手头的 AI 编码辅助通道理顺。我试过在多个 IDE 插件、多个模型之间来回切换最烦的就是每个工具都要单独配 Key、单独记 Base URL改一个模型要动好几处配置。TaoToken 的思路是提供一个统一的 API 通道你只需要维护一个 Key 和一个 Base URL就能在模型对话、Coding Plan、API Keys 等不同入口之间复用。先明确几个地址后面配置会反复用到。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 基础地址是https://taotoken.net/api这个不加 UTM 参数。如果你要管理 Key去 API Keys 页面要验证模型是否通用模型对话页面如果是长期编码或 Agent 场景看 Coding Plan。这里要强调一点TaoToken 在这里的角色是「AI 辅助编码的通道」不是替代你的 IDE 或编译器。迭代器代码最终还是要落到你的 Java 工程里由 JDK 编译执行。AI 帮你做的是生成模板、解释报错、补全边界判断而不是替你运行程序。配置的核心是三件套Base URL、API Key、Model ID。无论你用的是 Cline、Claude Code 还是其他支持 OpenAI 兼容协议的工具这三项都是必须的。Base URL 填https://taotoken.net/apiAPI Key 从控制台生成Model ID 根据你实际使用的模型填写。下面给一个通用的 JSON 配置片段你可以直接复制到支持 OpenAI 兼容格式的客户端配置里{ base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model: 你的ModelID, temperature: 0.2, max_tokens: 4096 }如果你用的是 Claude Code 这类工具配置方式会略有不同通常需要设置环境变量或写入 settings 文件。核心还是那三件套只是字段名不一样。比如在 Claude Code 的配置里你会看到ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这样的字段Base URL 同样指向 TaoToken 的 API 地址Key 用你生成的统一 Key。为什么要用统一 Key因为迭代器模式的实战往往涉及多轮对话先让 AI 生成一个基础Iterator实现再让它补上remove()的边界处理然后针对ConcurrentModificationException做排查。如果每换一个工具就要重新配一次上下文就断了。统一 Key 让你在模型对话、Coding Plan、API 调用之间共享同一套凭证切换成本低很多。还有一点值得提醒生成迭代器代码时建议把temperature调低比如 0.2 左右。迭代器涉及游标状态、边界判断、并发修改检测这些逻辑对准确性要求高温度太高容易生成看似合理但边界错误的代码。低温度下模型更倾向于输出确定性的、符合契约的实现。准备好 Key 和 Base URL 之后你就可以在 IDE 里让 AI 帮你生成Iterator骨架了。下一节我会给出完整的可复制配置和自定义迭代器实现包括hasNext、next、remove三个方法的行为约定。3. 可复制配置自定义 Iterable 与 Iterator 完整实现这一节给出可以直接复制到 Java 工程里的迭代器实现。我会先写一个固定容量的SimpleList容器实现IterableString然后提供一个内部类迭代器完整实现hasNext()、next()、remove()。这个实现会遵循 JDK 的迭代器契约包括remove()只能在next()之后调用一次、遍历中修改容器要抛ConcurrentModificationException。先看容器接口和实现。为了让for-each能用容器必须实现IterableT并返回IteratorTimport java.util.Iterator; import java.util.NoSuchElementException; import java.util.ConcurrentModificationException; public class SimpleListT implements IterableT { private Object[] elements; private int size; private int modCount; public SimpleList(int capacity) { if (capacity 0) { throw new IllegalArgumentException(capacity must be positive); } this.elements new Object[capacity]; this.size 0; this.modCount 0; } public void add(T element) { if (size elements.length) { throw new IllegalStateException(container is full); } elements[size] element; modCount; } public int size() { return size; } SuppressWarnings(unchecked) public T get(int index) { if (index 0 || index size) { throw new IndexOutOfBoundsException(index: index); } return (T) elements[index]; } Override public IteratorT iterator() { return new SimpleIterator(); } private class SimpleIterator implements IteratorT { private int cursor; private int lastRet; private int expectedModCount; SimpleIterator() { this.cursor 0; this.lastRet -1; this.expectedModCount modCount; } Override public boolean hasNext() { return cursor size; } Override SuppressWarnings(unchecked) public T next() { checkForComodification(); if (cursor size) { throw new NoSuchElementException(); } T value (T) elements[cursor]; lastRet cursor; cursor; return value; } Override public void remove() { if (lastRet 0) { throw new IllegalStateException(remove() called before next()); } checkForComodification(); System.arraycopy(elements, lastRet 1, elements, lastRet, size - lastRet - 1); elements[--size] null; cursor lastRet; lastRet -1; modCount; expectedModCount modCount; } private void checkForComodification() { if (modCount ! expectedModCount) { throw new ConcurrentModificationException(); } } } }这段代码有几个关键点需要解释。cursor是游标指向下一个要返回的元素下标lastRet记录最近一次next()返回的元素下标初始为 -1表示还没调用过next()。remove()的第一件事就是检查lastRet 0如果是说明调用方在next()之前就调了remove()直接抛IllegalStateException。这是 JDK 迭代器的标准行为很多自己写的迭代器会漏掉这个检查。expectedModCount是并发修改检测的核心。容器每次结构性修改add、remove都会让modCount自增。迭代器创建时记录当时的modCount每次next()和remove()前都对比一次。如果发现不一致说明迭代器遍历期间容器被外部修改了抛ConcurrentModificationException。这就是为什么你在遍历ArrayList时调用list.remove()会报错而调用iterator.remove()不会——后者会同步更新expectedModCount。remove()里的System.arraycopy做元素前移然后size--把最后一个位置置空帮助 GC。注意cursor lastRet这一步删除当前元素后后面的元素前移游标要回退到被删位置这样下一次next()才能正确返回前移过来的元素。lastRet重置为 -1保证remove()不能连续调用两次。如果你用 AI 辅助生成这段代码可以把上面的实现作为参考让模型帮你补全注释或生成单元测试。配置上把 Base URL 设为https://taotoken.net/apiKey 用你的统一 KeyModel ID 按实际填写。在模型对话里贴出你的容器代码问「这个迭代器的 remove 在连续调用两次时会怎样」模型会基于契约给出分析。下面再给一个倒序迭代器的实现展示「同一容器多种遍历方式」这个迭代器模式的核心优势public IteratorT reverseIterator() { return new IteratorT() { private int cursor size - 1; private int lastRet -1; private int expectedModCount modCount; Override public boolean hasNext() { return cursor 0; } Override SuppressWarnings(unchecked) public T next() { if (modCount ! expectedModCount) { throw new ConcurrentModificationException(); } if (cursor 0) { throw new NoSuchElementException(); } T value (T) elements[cursor]; lastRet cursor; cursor--; return value; } Override public void remove() { if (lastRet 0) { throw new IllegalStateException(); } if (modCount ! expectedModCount) { throw new ConcurrentModificationException(); } System.arraycopy(elements, lastRet 1, elements, lastRet, size - lastRet - 1); elements[--size] null; if (lastRet cursor) { cursor--; } lastRet -1; modCount; expectedModCount modCount; } }; }倒序迭代器的remove()里游标调整逻辑和正序不同如果被删元素在游标左侧游标要减一。这个细节很容易写错建议用单元测试覆盖。4. 验证请求与成功结果在 IDE 中跑通 hasNext/next/remove 行为代码写完了接下来要在 IDE 里验证行为是否符合预期。我习惯用 JUnit 写一组测试覆盖正常遍历、边界情况、并发修改、remove 语义这四类场景。下面给出完整的测试代码你可以直接复制到src/test/java下运行。import org.junit.jupiter.api.Test; import java.util.Iterator; import java.util.NoSuchElementException; import java.util.ConcurrentModificationException; import static org.junit.jupiter.api.Assertions.*; public class SimpleListTest { Test void shouldIterateAllElementsInOrder() { SimpleListString list new SimpleList(4); list.add(aa); list.add(bb); list.add(cc); list.add(dd); StringBuilder sb new StringBuilder(); for (String s : list) { sb.append(s).append( ); } assertEquals(aa bb cc dd , sb.toString()); } Test void shouldThrowWhenNextBeyondEnd() { SimpleListString list new SimpleList(2); list.add(x); IteratorString it list.iterator(); assertTrue(it.hasNext()); assertEquals(x, it.next()); assertFalse(it.hasNext()); assertThrows(NoSuchElementException.class, it::next); } Test void shouldRemoveCurrentElement() { SimpleListString list new SimpleList(4); list.add(aa); list.add(bb); list.add(cc); list.add(dd); IteratorString it list.iterator(); while (it.hasNext()) { String s it.next(); if (bb.equals(s)) { it.remove(); } } assertEquals(3, list.size()); assertEquals(aa, list.get(0)); assertEquals(cc, list.get(1)); assertEquals(dd, list.get(2)); } Test void shouldThrowWhenRemoveBeforeNext() { SimpleListString list new SimpleList(2); list.add(a); IteratorString it list.iterator(); assertThrows(IllegalStateException.class, it::remove); } Test void shouldThrowWhenRemoveTwice() { SimpleListString list new SimpleList(2); list.add(a); list.add(b); IteratorString it list.iterator(); it.next(); it.remove(); assertThrows(IllegalStateException.class, it::remove); } Test void shouldThrowOnConcurrentModification() { SimpleListString list new SimpleList(4); list.add(aa); list.add(bb); list.add(cc); IteratorString it list.iterator(); it.next(); list.add(dd); assertThrows(ConcurrentModificationException.class, it::next); } }跑完这组测试你应该看到全部通过。如果某个用例失败对照报错信息定位。比如shouldRemoveCurrentElement失败大概率是remove()里游标调整写错了shouldThrowOnConcurrentModification失败说明expectedModCount没有在add时更新或者checkForComodification没被调用。除了单元测试我还建议在main方法里手动跑一遍观察控制台输出。下面这段代码模拟了「遍历中删除偶数位置元素」的场景public class IteratorDemo { public static void main(String[] args) { SimpleListString list new SimpleList(6); list.add(aa); list.add(bb); list.add(cc); list.add(dd); list.add(ee); list.add(ff); System.out.println(before: size list.size()); IteratorString it list.iterator(); int index 0; while (it.hasNext()) { String s it.next(); if (index % 2 1) { it.remove(); System.out.println(removed: s); } index; } System.out.println(after: size list.size()); for (String s : list) { System.out.println(remaining: s); } } }预期输出是before: size6依次removed: bb、removed: dd、removed: ff最后after: size3剩余aa、cc、ee。如果你看到ConcurrentModificationException检查remove()里是否更新了expectedModCount。验证过程中如果遇到报错可以把异常栈贴到模型对话里让 AI 帮你分析。TaoToken 的模型对话入口支持直接粘贴代码和报错Base URL 用https://taotoken.net/apiKey 用统一 Key。对于迭代器这类契约性强的代码AI 在解释ConcurrentModificationException触发条件时通常比较准确。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth 对照这一节整理实战中容易遇到的几类报错分两部分一部分是迭代器代码本身的逻辑错误另一部分是接入 TaoToken 时可能出现的配置错误。两类问题经常混在一起因为你在 IDE 里让 AI 生成代码时如果通道不通会先看到接入报错误以为是代码问题。先看迭代器代码的常见错误。第一类是NoSuchElementException通常是在hasNext()返回 false 之后还调next()。检查你的循环条件确保next()只在hasNext()为 true 时调用。第二类是IllegalStateException: remove() called before next()说明remove()前没有调用next()或者连续调了两次remove()。第三类是ConcurrentModificationException说明遍历期间容器被外部修改或者你的remove()没有同步expectedModCount。第四类是元素被跳过或重复通常是remove()后游标没有正确回退。再看接入侧的报错。如果你在配置 AI 辅助工具时看到401 Unauthorized先检查 API Key 是否正确、是否过期、有没有多余空格。Key 从 API Keys 页面生成复制时注意不要带上换行。如果看到local proxy failed或类似的连接错误检查 Base URL 是否写成了https://taotoken.net/api注意结尾不要多加斜杠也不要误填成官网首页地址。如果看到reading choices相关的解析错误通常是响应格式和客户端预期不一致检查 Model ID 是否填写正确以及客户端是否按 OpenAI 兼容格式解析。下面用表格对照几类典型报错和排查方向报错关键词可能原因排查动作401 UnauthorizedKey 错误或过期重新生成 Key检查空格和换行local proxy failedBase URL 配置错误确认填https://taotoken.net/apireading choicesModel ID 不匹配核对 Model ID确认客户端协议OAuth 相关报错认证方式选错改用 API Key 方式检查字段名ConcurrentModificationException遍历中外部修改容器改用iterator.remove()NoSuchElementExceptionnext 越界检查 hasNext 判断IllegalStateExceptionremove 时机错误确保 next 后只调一次 remove关于 OAuth有些工具默认走 OAuth 流程但 TaoToken 的接入方式是 API Key。如果你在配置里看到 OAuth 相关字段把它关掉或忽略改用api_key字段。Claude Code 这类工具可能需要设置ANTHROPIC_API_KEY和ANTHROPIC_BASE_URLBase URL 同样指向 TaoToken 的 API 地址。还有一个容易忽略的点迭代器的remove()和容器的remove()不是一回事。SimpleList如果对外暴露了remove(int index)调用方在遍历时调它就会触发ConcurrentModificationException。正确做法是遍历时只用iterator.remove()。这个区别在 AI 生成的代码里有时会被混淆建议生成后人工检查一遍。如果你在排查过程中需要查文档接入文档入口在 TaoToken 的 doc 页面。排障和接入相关的问题优先看 API Keys 和接入文档验证模型是否通用模型对话长期编码或 Agent 场景看 Coding Plan。6. 把迭代器模式用起来从自定义容器到统一遍历接口迭代器模式的价值在你自己写容器的时候体现得最明显。JDK 的ArrayList、LinkedList、HashMap已经把迭代器实现得很完善你直接用就行。但当你需要写一个环形缓冲区、一个分页数据源、一个树形结构或者一个需要按业务规则过滤的集合时就得自己实现Iterable和Iterator。我在项目里用迭代器模式解决过一个分页遍历的问题。数据源每次只能拉一页但调用方希望像遍历普通集合一样处理。做法是写一个PagedIterable内部维护当前页码和页内游标hasNext()判断当前页是否还有元素或是否还有下一页next()返回元素并在页末自动拉取下一页。调用方只需要for (Item item : pagedIterable)完全不用关心分页细节。这就是迭代器模式「封装遍历算法」的直接收益。另一个场景是多容器统一遍历。假设你有多个数据源有的来自数据库有的来自缓存有的来自文件。你可以为每个数据源实现一个Iterator然后用一个CompositeIterator把它们串起来对外只暴露一个迭代器。调用方拿到这个迭代器后遍历逻辑完全一致不需要为每个数据源写不同的循环。如果你想让 AI 帮你生成这类迭代器建议把接口契约先写清楚再让模型补实现。比如告诉它「hasNext()在游标越界时返回 falsenext()在越界时抛NoSuchElementExceptionremove()在next()前调用抛IllegalStateException」。契约越明确生成的代码越可靠。TaoToken 的统一 Key 让你在模型对话、Coding Plan、API 调用之间共享同一套配置Base URL 固定为https://taotoken.net/api不用反复切换。最后给一个实用建议写自定义迭代器时优先用内部类实现。内部类可以直接访问容器的私有字段不需要暴露get(int index)这类方法封装性更好。JDK 的ArrayList.Itr就是这么做的。如果你的迭代器需要独立于容器存在再考虑抽成单独的类。迭代器模式本身不复杂难的是把hasNext、next、remove三个方法的边界行为处理干净。把这篇里的SimpleList实现和测试用例跑一遍再对照ArrayList的源码看一遍基本就能掌握。遇到报错时先分清是代码逻辑问题还是接入配置问题再对症排查。