Python自定义类怎么实现for循环迭代

题图：Python 自定义类迭代机制与协议流转概览

要在 Python 中让自定义类支持 for 循环，核心在于让该类遵循 Python 的迭代协议（Iteration Protocol）。最直接的标准做法是在类中定义 __iter__() 方法，让它返回一个迭代器对象。在现代 Python 编程中，最优雅、最不易出错的方式是在 __iter__() 中结合 yield 关键字将其写成生成器函数；而若需要精细的状态控制，也可以编写独立的迭代器类配合 __next__() 方法；此外，对于序列类容器，实现 __getitem__() 也能自动获得 for 循环的支持。理解这几种方式的机制差异与游标生命周期，是写出健壮自定义容器的关键。

一、for 循环底层究竟在寻找什么？

当我们书写 for item in obj: 这样一句直观的代码时，Python 解释器背后并不是直接读取 obj 的属性，而是经历了一套严密而平滑的协议寻址过程：

1. 获取迭代器：解释器首先执行内置函数 iter(obj)。它首先探查 obj 的类中是否定义了 __iter__() 方法。若存在，则直接调用 obj.__iter__()，并期待其返回一个合法的迭代器（Iterator）。
2. 序列协议降级兜底：如果类中没有 __iter__()，解释器不会立即放弃，而是回退检查是否存在 __getitem__() 方法。如果存在，Python 会自动构建一个内置的序列迭代器，从索引 0 开始逐一递增取值。
3. 逐项获取与退出机制：拿到迭代器后，解释器在每次循环开始时调用 next(iterator)（对应内部的 iterator.__next__()）。如果该方法返回数据，则赋值给循环变量并执行循环体；如果方法抛出 StopIteration 异常（或者在序列模式下捕获到 IndexError），解释器会自动将其静默吸收，无缝退出循环。

图 1：Python 解释器处理 for 循环时的底层调用分支与异常吸收流程

明确了这一底层逻辑后，我们可以发现：让自定义类支持 for 循环，本质就是为解释器提供一个能够不断产出数据并在终点主动发出终止信号的通道。

二、最推荐的方式：在 __iter__ 中使用 yield 生成器

在日常业务开发中，如果你封装了一个包含多项数据的集合类（如团队、购物清单、批量任务管理等），通过 yield 定义 __iter__() 是最简洁、最 Pythonic 的做法。

因为在 Python 语法中，任何包含 yield 关键字的函数都会被自动编译为生成器工厂。每次调用 __iter__() 时，它都会产生一个全新的生成器实例。生成器本身自带完整的迭代器行为（内部自动实现了 __next__，并在执行完毕时自动抛出 StopIteration），省去了我们手动计算游标指针和状态恢复的所有繁琐步骤。

完整实现示例

class DevTeam:
    def __init__(self, team_name):
        self.team_name = team_name
        self.members = []

    def add_member(self, name, role):
        self.members.append({"name": name, "role": role})

    def __iter__(self):
        # __iter__ 包含 yield，调用时直接返回一个全新的生成器迭代器
        for member in self.members:
            # 可以在 yield 产出前进行过滤、格式化或业务包装
            yield f"{member['name']} ({member['role']})"

# 验证执行
team = DevTeam("AI 平台研发组")
team.add_member("张三", "架构师")
team.add_member("李四", "后端工程师")
team.add_member("王五", "前端工程师")

# 第一次遍历
for person in team:
    print("团队成员:", person)

三、标准迭代器模式：分离容器与迭代器对象

有些时候，类的内部状态转移非常复杂，或者需要记录详细的单向行进轨迹，此时我们可以采用经典的迭代器设计模式：定义两个类，一个负责“装数据”（可迭代对象 Iterable），另一个负责“维护遍历进度”（迭代器 Iterator）。

根据 Python 的官方协议规范，一个合格的迭代器类必须满足两点：

• 实现 __next__(self)：返回下一个元素；当没有更多元素时，必须显式抛出 raise StopIteration。
• 实现 __iter__(self)：迭代器本身的 __iter__ 必须返回自身（return self），以便迭代器本身也能直接传给 for 循环或内置函数使用。

图 2：可迭代容器类与独立迭代器类的架构职责与状态隔离关系

面向对象标准实现代码

class BookShelf:
    """可迭代对象 (Iterable)：只负责保存书籍清单，不记录当前读到哪一本"""
    def __init__(self):
        self.books = []

    def append(self, book_title):
        self.books.append(book_title)

    def __iter__(self):
        # 关键点：每次请求迭代器时，都 new 出一个独立的游标对象
        return BookShelfIterator(self.books)


class BookShelfIterator:
    """迭代器 (Iterator)：持有数据引用，维护当前行进指针 cursor"""
    def __init__(self, books):
        self._books = books
        self._cursor = 0

    def __iter__(self):
        # 按照 Python 迭代协议，迭代器自身的 __iter__ 必须返回 self
        return self

    def __next__(self):
        if self._cursor >= len(self._books):
            # 元素耗尽，必须抛出 StopIteration 通知解释器终止循环
            raise StopIteration
        
        current_book = self._books[self._cursor]
        self._cursor += 1
        return current_book

# 验证多次遍历与独立性
shelf = BookShelf()
shelf.append("《深入理解计算机系统》")
shelf.append("《Fluent Python》")

print("--- 第 1 次遍历 ---")
for b in shelf:
    print(b)

print("--- 第 2 次遍历 ---")
for b in shelf:
    print(b)

四、基于序列协议的替代方案：__getitem__ 隐式迭代

除了显式的 __iter__，Python 还支持经典的序列协议。如果你的自定义类天生具有整数索引访问的需求（例如像自定义列表、向量或 PyTorch 中的 Dataset 数据集），你甚至不需要编写 __iter__，只要正确实现 __getitem__，类就会自动支持 for 循环。

代码实现

class DataRecords:
    def __init__(self, raw_data):
        self._items = list(raw_data)

    def __len__(self):
        return len(self._items)

    def __getitem__(self, index):
        # 关键点：当 index 越界时，必须抛出 IndexError
        # 如果捕获异常后返回 None 而不抛 IndexError，for 循环将陷入无限死循环！
        return self._items[index]

# 验证执行
dataset = DataRecords(["Sample_A", "Sample_B", "Sample_C"])

# 支持下标访问
print("第 0 号记录:", dataset[0])

# 自然支持 for 循环
for record in dataset:
    print("循环读取:", record)

图 3：三种实现方式的代码结构、状态管理与特性对比

五、三种实现路径横向对比

为了帮助大家在架构选型时做出最符合场景的决策，我们将上述三种实现形式的核心维度对比如下：

六、技术选型决策与开发避坑指南

在实际编码中，可以根据下图所示的决策路径快速锁定最合适的实现手段，并在上线前依照右侧清单进行自检：

图 4：自定义类实现迭代的选型决策树与自测验证清单

常见排错与注意事项

1. 不要用 return None 代替 StopIteration：在迭代器 __next__ 中，如果不抛出 StopIteration 而是返回 None，for 循环会认为本次产出的值就是 None，并将 None 持续传递给循环体，引发无穷无尽的死循环。
2. 善用委托转发：如果你的自定义类只是包装了一个内部已有的 list 或 dict，你甚至连 yield 都不需要写，直接在 __iter__ 中调用 return iter(self._internal_list)，将生成迭代器的任务直接委托给 Python 原生列表，运行速度最快且最不容易出错。
3. 免费获得的 Python 生态红利：一旦你的类正确实现了 for 循环支持，你将自动免费获得大量内置功能的支持——例如 list(my_obj) 强转、[x for x in my_obj] 列表推导式、*my_obj 参数解包，以及 sum(my_obj)、min(my_obj)、max(my_obj) 等聚合函数的直接调用。