可迭代对象设计：Python工程思维解析

本文深入剖析了Python中可迭代对象设计的核心工程原则，强调可迭代对象与迭代器必须严格职责分离——__iter__ 每次都应返回全新迭代器而非 self，否则会导致多次遍历静默失败，违背PEP 234契约；同时厘清了 StopIteration 的正确抛出时机与方式、__contains__/__len__/__iter__ 各自不可替代的作用，以及生成器函数在简洁性与重用性之间的权衡取舍，直击日常开发中大量隐蔽却致命的状态管理陷阱，帮你写出真正健壮、可组合、符合Python生态预期的容器类。

为什么 __iter__ 返回迭代器，而不是直接返回 self

因为可迭代对象（Iterable）和迭代器（Iterator）在语义和生命周期上必须分离。常见错误是让类同时实现 __iter__ 和 __next__ 并在 __iter__ 里返回 self，这会导致多次遍历失败——比如在 for 循环、list()、sum() 中重复使用同一个对象时，第二次调用就直接空了。

正确做法是：每次调用 __iter__ 都新建一个独立的迭代器实例。这个迭代器内部持有当前状态（如索引、游标），而可迭代对象本身只负责“生成”它。

• 适用场景：range、dict.keys()、自定义数据容器（如树、链表）
• 性能影响：新建对象开销极小，远小于状态错乱带来的逻辑 bug
• 兼容性：符合 PEP 234，所有标准库函数（如 itertools.chain）都依赖这一契约

StopIteration 该由谁抛、什么时候抛

只能由迭代器的 __next__ 方法抛，且仅在“真的没有下一个元素”时抛。不能靠计数预判，也不能在初始化或 __iter__ 里抛。

常见错误包括：在 __next__ 开头就检查 if self.index >= len(self.data) 然后抛，但没处理空数据或边界变化；或者误把 IndexError 当 StopIteration 捕获并吞掉，导致无限循环。

• 安全写法：在取值后立即判断是否越界，再决定返回还是抛 StopIteration
• 不要在生成器函数里手动 raise StopIteration —— return 就够了，否则会触发 RuntimeWarning
• 协程或异步迭代器（__aiter__/__anext__）中，对应抛的是 StopAsyncIteration

如何让自定义类支持 in、len() 和解包而不重复实现

支持 in 查找靠 __contains__，支持 len() 靠 __len__，支持解包（如 a, b = obj）靠 __iter__。三者互不替代，也不能靠其中一个自动推导另一个。

典型坑是：只实现了 __iter__ 就以为 in 会自动变快——其实默认回退到逐个 __next__ 对比，时间复杂度 O(n)；而自己写 __contains__ 可以用哈希、二分或索引优化到 O(1) 或 O(log n)。

• __len__ 必须返回非负整数，返回负数会引发 ValueError
• 解包要求对象可迭代且长度明确（否则报 ValueError: not enough values to unpack）
• 如果底层数据支持快速查找（如 set 或带索引的 dict），别省那几行代码，直接实现 __contains__

用生成器函数代替手写迭代器类真的更“工程”吗

绝大多数情况下是的，但前提是逻辑不依赖外部状态重入或并发访问。生成器函数（含 yield）本质是语法糖，Python 自动帮你管理了 __iter__ 和 __next__，还内置了状态挂起/恢复机制。

容易被忽略的点是：生成器对象不可重用。调用一次 list(gen()) 后，再次传给 sum(gen()) 就是空的——因为它不是可迭代对象，而是迭代器。所以若需要多次遍历，得包装一层类，或每次调用生成器函数重新创建。

• 适合场景：一次性数据流（日志行、API 分页结果）、简单变换（map 类逻辑）
• 不适合场景：需暂停/恢复多个独立遍历（如双指针算法）、需共享内部缓存（如预加载下一页）
• 调试难点：生成器内部变量无法在暂停时 inspect，不如类属性直观

真正难的不是写对，而是想清楚“这个对象的生命周期归谁管”——是调用方每次要新拿一个，还是它自己能反复交出新迭代器。这点一旦错，下游所有 for、list()、itertools 组合都会静默失效。

好了，本文到此结束，带大家了解了《可迭代对象设计：Python工程思维解析》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！