StopAsyncIteration 是异步迭代协议的正常终止信号，非需捕获的异常；async for 自动处理，仅在直接调用 anext() 或实现自定义 anext 时需显式应对。
StopAsyncIteration 是异步迭代器的正常结束信号，不是异常
很多人一看到 StopAsyncIteration 就下意识用 try/except 包裹 anext()，以为它像 StopIteration 那样需要“捕获处理”。但关键点在于：StopAsyncIteration 在标准 async for 语义中根本不需要手动捕获——它是 Python 异步迭代协议的终止标志，由解释器自动识别并退出循环。
手动捕获通常只出现在两种场景：你绕过了 async for（比如直接调用 anext()），或者你在实现自定义异步迭代器时需要主动抛出它。
直接调用 anext() 时必须用 try/except 处理
当你不使用 async for，而是显式调用 anext() 获取下一个值（例如做条件拉取、分页控制或超时等待），就必须自己处理 StopAsyncIteration。否则协程会因未捕获异常而崩溃。
-
anext()在迭代结束时**立即抛出**StopAsyncIteration，不会返回None或其他哨兵值 - 不能用
except Exception:模糊捕获，必须明确写except StopAsyncIteration: - 如果想提供默认值，应使用
anext(aiter, default)形式，而非 try/except
async def fetch_batch():
async for item in my_async_generator():
yield item
<h1>❌ 错误：没处理 StopAsyncIteration，且 anext 不接受 timeout 参数</h1><h1>value = await asyncio.wait_for(anext(aiter), timeout=1)</h1><h1>✅ 正确：用默认值避免异常</h1><p>value = await anext(aiter, None)
if value is None:
print("迭代已结束")</p><h1>✅ 或者显式捕获</h1><p>try:
value = await anext(aiter)
except StopAsyncIteration:
print("到头了")
在自定义 __anext__ 中不要随意 raise StopAsyncIteration
如果你实现了 __aiter__ 和 __anext__，要注意 StopAsyncIteration 的抛出时机必须严格对应“已无更多数据”。过早或过晚抛出都会破坏协议语义。
立即学习“Python免费学习笔记（深入）”；
- 不能在
__anext__中捕获其他异常后伪装成StopAsyncIteration（比如把网络错误转成它） - 不能在首次调用
__anext__就抛出（除非你的迭代器天生为空） - 若内部 await 的协程本身抛出
StopAsyncIteration（如嵌套调用另一个 aiter），不要原样 re-raise——应检查是否真到了末尾，否则可能掩盖真实问题
async for 本身已完全屏蔽 StopAsyncIteration，无需干预
这是最容易被误解的一点：只要用标准 async for 语法，Python 运行时会在底层自动捕获 StopAsyncIteration 并干净退出循环。你写的任何 except StopAsyncIteration: 在这里都永远不会执行。
async for item in my_async_generator(): # ✅ 安全，自动处理结束
process(item)
<h1>下面这段代码里的 except 永远不会触发</h1><p>async for item in my_async_generator():
process(item)
except StopAsyncIteration: # ⚠️ 这行无效，语法上甚至不允许
pass
真正该关注的是：确保你的异步生成器或迭代器在耗尽时**确实抛出 StopAsyncIteration**，而不是静默返回、卡住或抛出别的异常。否则 async for 会永远等下去。
复杂点往往藏在边界逻辑里——比如流式 HTTP 响应解析中，连接关闭、空 chunk、服务端 EOF 信号，哪一种该对应 StopAsyncIteration，哪一种该抛出 ConnectionError，得按协议语义严格区分。
