自定义迭代器设计：从数据结构解耦到遍历协议实战

我在几个项目里被迭代器的问题卡过不止一次，最近一次是在做一个自定义数据结构的遍历模块时，发现调用方代码为了迁移数据结构居然要改几百行。回头复盘整个设计过程，其实根本问题不在迁移，而在于一开始就没有把“遍历”这个动作从数据结构里抽出来。

这篇文章我想把自定义迭代器的设计思路完整梳理一遍，包括两个核心问题：迭代器到底解决什么、设计时该做哪些关键取舍。如果你正在写一个稍微复杂一点的数据结构，或者想让业务代码跟存储结构解耦，这篇内容应该能帮你省掉不少弯路。

1. 自定义迭代器设计的核心思路与方案选型

1.1 迭代器解决的问题本质

迭代器本质上是一个“遍历协议”。它的职责不是存储数据，而是提供一个统一的、与具体数据结构无关的访问通道。我更喜欢把它理解成“数据结构的遥控器”：你不需要知道电视机内部怎么接线，只需要按遥控器上的按钮就能完成频道切换。

在工程实践中，迭代器最典型的应用场景有这几类：

• 业务方需要顺序访问集合，但不想暴露内部存储细节
• 业务方需要多种遍历方式，比如正序、逆序、跳步、条件过滤
• 数据结构本身结构复杂，比如树、图、自定义链表，遍历逻辑不适合散落在业务代码里
• 需要把遍历行为与数据结构分离，方便后续替换存储实现

拿一个具体的场景来说，我之前做过一个多级分类树，业务方经常要遍历所有叶子节点。如果不用迭代器，业务方就要自己写递归，然后每一层递归都依赖树节点内部字段名。后来树节点从数组子节点改成了哈希表子节点，业务方的递归代码全部报废，这就是遍历逻辑没有封装带来的代价。

1.2 为什么需要把遍历逻辑单独抽象出来

很多开发者习惯直接给数据结构写一个 getAll() 方法，返回一个完整列表。这种做法在小规模数据上没什么问题，但一旦数据量上来，或者数据结构变得复杂，问题就很明显了：

第一，内存压力。一次性返回所有元素意味着你必须在内存里构建一个完整副本。如果数据有几百万条，每次遍历都要做一次全量复制，这在服务端处理大量日志数据时是致命的。

第二，无法表达复杂遍历状态。比如你要遍历一个无限序列，或者遍历一个边遍历边过滤的数据流，一次性返回的方案根本做不到。

第三，遍历策略无法灵活切换。正序、逆序、条件过滤这些策略如果写死在 getAll() 里，你就得不断给数据结构添加新方法，最后数据结构会越来越臃肿。

把遍历逻辑抽象成独立的迭代器之后，数据结构和遍历算法可以独立演变，这是典型的“策略模式”思想。你只需要给数据结构添加一个特性：它能生产出迭代器，至于这个迭代器内部是怎么实现遍历的，数据结构完全不关心。

1.3 迭代器设计的核心原则

在设计自定义迭代器时，我总结出三个核心原则：

原则一：迭代器状态独立。迭代器自己维护遍历状态，不依赖外部变量的修改。也就是说，同一个集合可以同时存在多个互不干扰的迭代器，各自独立推进。

原则二：接口行为明确。迭代器必须有一组清晰明确的操作语义，比如“获取当前元素”“移动到下一个”“判断是否结束”，这些语义必须对调用方透明，不能有歧义。

原则三：异常路径清晰。迭代器一定要定义好边界行为：空集合怎么处理、已经遍历完再访问会怎样、遍历过程中集合被修改会怎样。这些看起来是细节，实际是线上问题的主要来源。

2. 自定义迭代器的关键技术点与分类

2.1 不同能力等级的迭代器分类

不是所有迭代器都需要做成长得一模一样。按照能力等级，迭代器通常可以分成几个层次：

• 单向迭代器：只能从头到尾单向移动，每次调用 next() 前进一步。这是最基础的迭代器类型，适合链表、生成器这类只能顺序访问的数据结构。
• 双向迭代器：支持 next() 和 prev() 两种移动方式，可以从两个方向遍历。C++ STL 里 list 容器的迭代器属于这一类。
• 随机访问迭代器：支持直接跳跃到任意位置，不仅限于相邻移动。数组的迭代器就是典型代表，你可以直接 it + 5 跳过五个元素。

在设计中，给迭代器定义能力边界很重要。我见过不少代码把迭代器能力无限放大，最后接口设计得异常复杂，调用方反而不知道该用哪个方法。

设计铁律：按最小能力设计，只提供当前场景必需的遍历能力，能力需要扩展时再补充，而不是一开始就堆叠功能。

2.2 迭代器的访问语义：值还是引用

这是设计迭代器时最容易忽略但又影响最大的一个决策点。

如果你设计的是值语义迭代器，每次访问元素都会返回一个副本。好处是安全，调用方修改返回结果不会影响数据结构内部状态；坏处是性能开销大，尤其当元素对象很大时，每一次取值都伴随一次拷贝。

如果你设计的是引用/指针语义迭代器，访问返回的是元素的实际地址。好处是零拷贝，可以高效处理大数据对象；坏处是调用方可以通过迭代器修改集合内部数据，破坏了封装性，也可能产生悬垂引用。

在 Java 的 ArrayList 中，迭代器返回的是元素对象引用，所以如果你在遍历过程中修改元素内容，会直接影响集合内部。而 C++ STL 迭代器通过 operator* 返回的是引用，语义更接近指针。Python 的迭代器则直接返回对象本身，属于引用语义。

实操建议：如果元素是基本类型或小型不可变对象，优先使用值语义；如果元素是大对象且不希望在遍历中产生拷贝，使用引用语义，但要严格控制迭代器的生命周期，避免悬垂引用。

2.3 惰性求值：迭代器与普通列表的本质区别

迭代器最有价值的一点是支持惰性求值：元素不是一次性全部计算出来，而是每调用一次 next() 才计算下一个。

这个特性带来两个直接收益：

第一，低延迟启动。遍历一百万条数据时，普通方式要先构建好完整结果列表再返回，用户等待时间与数据量成正比；惰性求值方式几乎瞬间返回第一个元素，后续元素按需计算。

第二，可以表达无限序列。比如斐波那契数列、素数序列，这类无限序列根本无法用普通列表表示，只有迭代器能做到“随取随用”。

但惰性求值也有代价：错误被延迟暴露。如果是预生成列表，数据计算错误在生成阶段就会暴露；惰性求值则要等遍历到具体位置时才会触发错误，排查问题的定位成本更高。

2.4 迭代器与泛型算法的协同设计

一个好的迭代器设计，应该能和已有的泛型算法无缝配合，否则就失去了“解耦”的意义。

在 C++ 中，这就是 STL 算法的设计思路：std::find、std::sort、std::accumulate 完全不关心你传进来的是 vector、list 还是自定义数据结构，只要迭代器满足对应的能力要求，算法就能运行。

在 Python 中，这种配合体现在迭代器协议与内置函数的交互中：sum()、map()、filter()、sorted() 都接受可迭代对象。只要你的自定义迭代器实现了 __iter__ 和 __next__，它就能无缝使用这些内置函数。

设计迭代器时，一定要考虑它将来会怎么被使用。我个人的心法是：先写调用方的循环代码，再回头设计迭代器接口。如果调用方代码写起来自然流畅，说明接口设计合理；如果调用方要写一堆类型判断和强制转换，那一定是接口设计出了问题。

3. 不同语言中的自定义迭代器实现方案

3.1 Python 风格：生成器与迭代器协议

Python 的迭代器设计以简洁著称，核心协议只有两个方法：__iter__ 和 __next__。

__iter__ 返回迭代器对象自身，__next__ 返回下一个元素，没有更多元素时抛出 StopIteration 异常。这个设计非常优雅，把“迭代结束”这个状态用异常机制表达，调用方不用检查额外标志位。

实际写代码时，最推荐的方式是生成器函数，而不是手动定义一个迭代器类：

python复制def file_lines_iterator(file_path):
    with open(file_path, 'r') as f:
        for line in f:
            # 可以在每一行做清洗或过滤
            cleaned = line.strip()
            if not cleaned:
                continue
            yield cleaned

这种做法下，函数内部虽然写了 for 循环，但不会一次性读入全部行，而是每 yield 一次返回一行，文件读取和行清洗都是按需执行的。

不过如果遍历状态比较复杂，比如需要在遍历过程中记录位置信息、支持回溯，我还是建议定义成显式的迭代器类：

python复制class TreeNode:
    def __init__(self, value):
        self.value = value
        self.children = []

class TreeDepthFirstIterator:
    def __init__(self, root):
        self.stack = [root]

    def __iter__(self):
        return self

    def __next__(self):
        if not self.stack:
            raise StopIteration
        node = self.stack.pop()
        # 逆序压栈，保证遍历顺序是从左到右
        self.stack.extend(reversed(node.children))
        return node

Python 迭代器的一个实际坑：__iter__ 方法应该返回迭代器自身，如果写错返回了其他对象，for 循环会直接报 TypeError。

3.2 C++ 风格：STL 迭代器五件套

C++ 的迭代器设计比 Python 更重，因为它要同时满足泛型算法的类型推导需求。STL 约定自定义迭代器必须提供五个关联类型：

• iterator_category：迭代器能力分类标志
• value_type：迭代器指向元素的类型
• difference_type：两个迭代器之间的距离类型
• pointer：指向元素的指针类型
• reference：元素引用类型

写一个完整的 STL 风格迭代器非常繁琐，代码量很大，我这里用一个简化的数组迭代器来说明结构：

cpp复制template <typename T>
class ArrayIterator {
public:
    using iterator_category = std::random_access_iterator_tag;
    using value_type = T;
    using difference_type = std::ptrdiff_t;
    using pointer = T*;
    using reference = T&;

    explicit ArrayIterator(pointer ptr) : ptr_(ptr) {}

    reference operator*() const { return *ptr_; }
    pointer operator->() const { return ptr_; }

    ArrayIterator& operator++() { ++ptr_; return *this; }
    ArrayIterator operator++(int) {
        ArrayIterator tmp = *this;
        ++ptr_;
        return tmp;
    }

    ArrayIterator& operator--() { --ptr_; return *this; }
    ArrayIterator operator--(int) {
        ArrayIterator tmp = *this;
        --ptr_;
        return tmp;
    }

    ArrayIterator& operator+=(difference_type n) { ptr_ += n; return *this; }
    ArrayIterator operator+(difference_type n) const {
        return ArrayIterator(ptr_ + n);
    }

    difference_type operator-(const ArrayIterator& other) const {
        return ptr_ - other.ptr_;
    }

    reference operator[](difference_type n) const { return *(ptr_ + n); }

    bool operator==(const ArrayIterator& other) const { return ptr_ == other.ptr_; }
    bool operator!=(const ArrayIterator& other) const { return ptr_ != other.ptr_; }
    bool operator<(const ArrayIterator& other) const { return ptr_ < other.ptr_; }

private:
    pointer ptr_;
};

C++ 迭代器最常见的坑是迭代器失效。对 vector 来说，插入或删除元素会导致后面所有迭代器失效；对 unordered_map 来说，插入操作可能导致底层哈希表扩容，所有迭代器全部失效。排查这类问题需要仔细检查容器修改操作的位置。

3.3 Java 风格：Iterable 与快速失败机制

Java 的迭代器设计强调安全性，最引人注目的特征是快速失败（fail-fast）机制。

Java 集合内部维护一个 modCount 字段，每次结构性修改都会让这个计数器加一。迭代器构造时会记录当前的 modCount，每次调用 next() 时对比当前值和记录值，如果不一致就抛出 ConcurrentModificationException。

这样做的好处是能尽早暴露并发修改问题，避免出现不可预期的行为。但它也带来一个副作用：如果业务逻辑必须在遍历过程中修改集合，直接用迭代器就会抛异常。我见过不少初写 Java 的开发者踩这个坑，处理方式一般有两种：

• 使用 CopyOnWriteArrayList，它通过复制新数组来避免并发修改问题
• 在遍历时收集需要修改的元素，遍历结束后再统一修改

Java 迭代器设计还有一个关键点：Iterable 接口支持 for-each 语法糖：

java复制for (TreeNode node : myTree) {
    // node 直接可用
}

这要求自定义数据结构实现 Iterable<T> 接口，并返回一个 Iterator<T>。如果你实现的迭代器需要支持 remove() 操作，要注意 Java 迭代器的 remove() 语义是“删除刚刚遍历过的那个元素”，不是任意删除。

3.4 三种风格的对比与选型建议

选型建议很简单：如果你可以自由选择语言，Python 的生成器最适合快速实现，开发效率最高；如果你写的是底层库或者对性能敏感，C++ 的迭代器虽然难写，但能力最完善；如果是在企业级应用里处理集合数据，你大概率已经用了 Java 集合框架，自定义迭代器时要重点考虑并发修改问题。

4. 实操：设计一个二维矩阵螺旋遍历迭代器

4.1 需求定义与接口设计

先看一个完整实例：设计一个迭代器，对二维矩阵做螺旋遍历。比如一个 3x3 矩阵：

code复制1  2  3
4  5  6
7  8  9

螺旋遍历顺序是：1, 2, 3, 6, 9, 8, 7, 4, 5。

我们先定义一个简单的矩阵类：

python复制class Matrix:
    def __init__(self, rows, cols):
        self.rows = rows
        self.cols = cols
        self.data = [[0] * cols for _ in range(rows)]

    def __getitem__(self, pos):
        row, col = pos
        return self.data[row][col]

    def __setitem__(self, pos, value):
        row, col = pos
        self.data[row][col] = value

    def __iter__(self):
        return SpiralMatrixIterator(self)

接口设计我做了两个决定：

• Matrix 实现 __iter__，返回一个螺旋迭代器
• 螺旋迭代器自己维护遍历状态，不污染矩阵对象内部数据

这样调用方只需要写：

python复制for value in matrix:
    print(value)

4.2 螺旋迭代器实现

python复制class SpiralMatrixIterator:
    def __init__(self, matrix):
        self.matrix = matrix
        self.rows = matrix.rows
        self.cols = matrix.cols

        # 边界控制
        self.top = 0
        self.bottom = self.rows - 1
        self.left = 0
        self.right = self.cols - 1

        # 当前位置和方向
        self.row = 0
        self.col = 0
        self.direction = 0  # 0: 右, 1: 下, 2: 左, 3: 上

        # 是否开始
        self.started = False
        self.finished = False

    def __iter__(self):
        return self

    def __next__(self):
        if self.finished:
            raise StopIteration

        # 第一次调用，返回第一个元素
        if not self.started:
            self.started = True
            return self.matrix[self.row, self.col]

        # 根据当前方向尝试前进
        while True:
            if self.direction == 0:
                if self.col < self.right:
                    self.col += 1
                    return self.matrix[self.row, self.col]
                else:
                    self.top += 1
                    self.direction = 1
            elif self.direction == 1:
                if self.row < self.bottom:
                    self.row += 1
                    return self.matrix[self.row, self.col]
                else:
                    self.right -= 1
                    self.direction = 2
            elif self.direction == 2:
                if self.col > self.left:
                    self.col -= 1
                    return self.matrix[self.row, self.col]
                else:
                    self.bottom -= 1
                    self.direction = 3
            elif self.direction == 3:
                if self.row > self.top:
                    self.row -= 1
                    return self.matrix[self.row, self.col]
                else:
                    self.left += 1
                    self.direction = 0

            # 检查是否遍历完成
            if self.top > self.bottom or self.left > self.right:
                self.finished = True
                raise StopIteration

这里的核心思路是用四个边界变量（top、bottom、left、right）控制边界，每走完一条边就收缩边界并转向。

这个实现的巧妙之处在于：方向的切换发生在边界条件触发时，而不是每次遍历都做复杂的判断。实际测试时发现，对于 1 行 N 列的矩阵，top 和 bottom 会很快收缩并触发遍历结束条件，逻辑能正确退出。

4.3 边界条件测试

测试这一块不能偷懒，我列几个必须覆盖的场景：

python复制# 空矩阵场景：0 行 0 列
matrix = Matrix(0, 0)
print(list(matrix))  # []

# 单元素矩阵
matrix = Matrix(1, 1)
matrix[0, 0] = 42
print(list(matrix))  # [42]

# 单行矩阵
matrix = Matrix(1, 5)
for i in range(5):
    matrix[0, i] = i + 1
print(list(matrix))  # [1, 2, 3, 4, 5]

# 单列矩阵
matrix = Matrix(5, 1)
for i in range(5):
    matrix[i, 0] = i + 1
print(list(matrix))  # [1, 2, 3, 4, 5]

# 完整 3x3 矩阵
matrix = Matrix(3, 3)
value = 1
for r in range(3):
    for c in range(3):
        matrix[r, c] = value
        value += 1
print(list(matrix))  # [1, 2, 3, 6, 9, 8, 7, 4, 5]

边界测试的教训：单行和单列是最容易写错的场景，因为方向切换逻辑在走到边界时会被连续触发。没有测试覆盖的情况下，很容易出现越界访问或者死循环。

4.4 同场景下的另一个选择：状态机式遍历

这里可以对比另一种实现思路：把方向变化建模成状态机，每一步都基于当前状态和边界条件决策，逻辑上更清晰。伪代码参考：

python复制while True:
    if direction == RIGHT:
        # 往右走到边界，然后判断是否转向
        ...
    if direction == DOWN:
        ...

对比下来，我推荐前面那个收缩边界的方案，因为它把“边界收缩”和“方向切换”做了强绑定，逻辑更紧凑，出 bug 的概率更低。

5. 自定义迭代器常见坑与排查技巧

5.1 迭代器状态未彻底复位

场景：迭代器对象被复用，但之前遍历到一半的状态还残留在实例属性里。

这种问题在 Python 中尤其常见：定义迭代器类时，如果 __init__ 里没有初始化全部状态变量，而状态变量是在 __next__ 里第一次赋值的，那么第一次遍历完成后，状态变量残留了结束值，第二次复用时就不会进入正常逻辑。

排查方法：在 __init__ 里把所有状态变量全部显式初始化，不要依赖 __next__ 里的初次赋值。这条规则我建议直接写进团队的代码规范。

5.2 在遍历过程中修改集合导致行为异常

这是所有语言里共性最强的坑。Python 里你在 for x in my_list 的循环体内直接修改 my_list，经常会导致跳元素或无限循环。

比如：

python复制my_list = [1, 2, 3, 4, 5]
for x in my_list:
    if x == 3:
        my_list.remove(3)

这段代码可能出现的问题是：迭代器内部用索引跟踪位置，移除元素后索引指向了原位置的下一个元素，导致实际跳过了 4。

解决方案：

• 遍历时只收集要修改的元素，遍历结束后统一修改
• 使用复制列表遍历原始列表的副本
• 使用专门支持修改的迭代器接口

5.3 迭代器返回悬垂引用

这是 C++ 里比较典型的坑。如果迭代器的 operator* 返回的是指向临时对象的引用，而临时对象在表达式结束时就销毁了，那么调用方拿到的就是悬垂引用。

一个常见的错误写法：

cpp复制reference operator*() const {
    T tmp = some_calculation();
    return tmp;  // 临时对象生命周期结束，引用失效
}

设计迭代器时，只要涉及返回引用或指针，都必须严格确认指向的对象生命周期长于迭代器使用场景。如果无法保证，就老老实实返回值类型，用拷贝换安全。

5.4 性能问题：不必要的拷贝与重复计算

迭代器性能问题往往不是出现在 next() 调用本身，而是出现在每一次 next() 内部做的隐式操作。

• 每次 next() 都创建一个新对象
• 每次 next() 都执行一次不必要的深拷贝
• 每次 next() 都重新计算一遍与当前元素无关的中间量
• 每次 next() 都访问一次远程接口或数据库

如果是最后一种情况，一定要在迭代器内部做缓存或预取。我之前做过一个分页查询迭代器，每 next() 一次拉取一页数据，初始实现时没做预取，导致遍历时每个元素都要等待网络往返。预取一页之后，速度提升非常明显。

5.5 排查技巧速查表

排查迭代器问题，我的习惯是先加日志把每一次 next() 的关键状态都打印出来，比如行列坐标、当前方向、边界值。只要状态轨迹清晰了，问题定位就是几分钟的事。

最后再分享一个小技巧

关于自定义迭代器，我个人在实际操作中体会最深的一点是：先围绕调用方写代码，再设计迭代器的接口。

具体做法是，先写循环体：

python复制for item in my_custom_structure:
    do_something(item)

然后让这段代码跑通，再回头去设计迭代器的内部状态和移动逻辑。这样做的好处是，你永远知道迭代器的行为边界在哪里，不会出现“接口设计了一大堆，但调用方根本用不到”的情况。

调试迭代器的过程中，最容易被忽略的是空集合和单元素集合这两个极端场景。我在写矩阵螺旋迭代器的时候，就是在测试 1 行 N 列时发现方向切换逻辑有 bug。所以不管你的迭代器看起来多简单，这两个场景一定要覆盖。

整个设计过程下来，我觉得自定义迭代器的核心价值不在于“实现遍历”，而在于把行为从数据中抽离出来。数据结构可以自由变化，但遍历协议保持稳定，调用方代码就不会因为底层存储改变而大面积重写。这比任何设计模式名称都更实在。