一个异步消费者最难写的部分，往往不是处理消息，而是退出。业务服务收到停止信号，生产者不再投递新任务，消费者却还在等待一个永远不会到来的队列元素；于是工程师给每个工作协程发送取消信号，结果一部分已经取出的工作尚未提交，另一部分正在等待入队，系统表面退出，后台状态却无法对账。
Python 3.13 为 asyncio.Queue 增加了 shutdown 方法和 QueueShutDown 异常。这个变化不在吞吐量，而在生命周期：生产者可以明确知道队列已经关闭，消费者也可以在队列取空后自然退出。它让以前依赖私有哨兵值的方案多了一条正式路径，但也引入一个容易误判的选项：立即关闭，并不等于所有业务工作已经完成。
本文只讨论 Python 3.13 及以上版本的 asyncio.Queue。线程间通信的 queue.Queue 有同名但不同异常类型的接口，不能把两者混用。下面用可运行的小程序解释优雅关闭、强制关闭、任务计数以及如何把这套规则接进真实服务。
一、旧办法为什么总要往队列里塞一个特殊值
以前的常见写法是由消费者无限等待 get，结束时由生产者投递一个空对象或特殊字符串，表示不再有工作。这套做法可以运行，却存在隐含契约：每个消费者都要收到一个结束信号，而结束信号本身也占用队列容量。三名消费者只投递一个结束信号，另外两名仍可能永远挂起；多投递结束信号，则又得控制这些标记不要被当成正常业务记录。
当队列设置了 maxsize，事情更麻烦。一个等待 put 的生产者可能已经卡在队列满的地方；关闭流程如果只通知消费者，生产者并不知道自己应该停止等待。另一个危险在于有人简单地 cancel 所有 worker，忽略那些已经取到手、却尚未调用 task_done 的项目。此时 join 的未完成计数无法归零，退出阶段可能一直等下去。
这里有两个概念必须分开。第一是拒绝新的任务，第二是等待旧任务处理完成。只保证第一项，会漏掉在途工作；只保证第二项，新的生产者仍可能继续塞任务。真正可维护的退出流程，需要先建立明确的入口封闭边界，再确认队列里所有已接受的工作是否处理完，最后才回收消费者协程。
shutdown 给队列增加了官方的关闭状态，不需要在数据里注入伪装成工作的退出标记。队列关闭以后，新 put 会直接收到 QueueShutDown 异常；等待队列空位的 put 也会被唤醒并收到同样异常。对生产者而言，拒绝是明确结果，而不是无限等待。这是比“某个地方约定发一个特殊值”更可靠的生命周期信号。
二、默认关闭并不丢弃已经入队的任务
正常的 shutdown 调用等价于给这个队列挂上“停止收件，但继续处理存量”的牌子。关闭以后，队列不会再接受新工作；消费者仍能继续 get 已经排队的项目。只有存量全部取走，后续 get 才会抛出 asyncio.QueueShutDown，告诉消费者可以结束循环。
这件事有一个容易忽略的细节：队列是否为空，与所有任务是否已经处理完，是两种不同状态。消费者调用 get 之后，队列大小立即减少；但业务可能还在执行网络请求、写文件或者提交数据库事务。只看到 qsize 为零，并不能说明这笔工作完成了。等待实际处理完成，依赖的是 task_done 配合 join，而不是 empty。
因此，正常关闭时建议按顺序执行三个动作：通知队列停止接收新项目，等待 join 确认已接受的项目全部完成，然后等待消费者自然结束。最后一步看似多余，却决定了协程能否在 get 上正确退出，避免留下等待中的后台任务。这三步描述的是生命周期顺序，不是三个可以随意互换的函数。
生产者必须对 QueueShutDown 有预期。一旦接到它，调用方就应该把“本次任务未入队”作为明确结果，交给上游重试、记录或者拒绝，而不是吞掉异常之后说“提交成功”。一个异步接口能不能准确区分“接收成功”和“业务执行成功”，会直接决定后续的回执设计是否可信。
三、一段能直接运行的正常停机程序
下面示例只使用标准库。两个消费者同时处理八个数字任务，队列容量设为二；全部入队后停止接收新任务，等待八项处理完，再等待消费者退出。代码通过断言检查处理数量，不依赖人为观察日志来判断完成。
import asyncio
async def worker(queue, completed):
while True:
try:
item = await queue.get()
except asyncio.QueueShutDown:
return
try:
await asyncio.sleep(0.01)
completed.append(item)
finally:
queue.task_done()
async def main():
queue = asyncio.Queue(maxsize=2)
completed = []
workers = [
asyncio.create_task(worker(queue, completed))
for _ in range(2)
]
for number in range(8):
await queue.put(number)
queue.shutdown()
await queue.join()
await asyncio.gather(*workers)
assert sorted(completed) == list(range(8))
print("done:", len(completed))
if __name__ == "__main__":
asyncio.run(main())
这里的 finally 很重要，它让消费者在已经成功取出一条记录后，无论处理代码正常返回还是抛出普通异常，都可以平衡队列的未完成任务计数。但 finally 并不意味着业务天然成功。假设工作内容是付款、写入数据库或向外部接口发请求，操作失败时仍要决定是否记录失败、重试或转入待处理表。task_done 的含义只是“这一次从队列取出的项目已结束处理责任”，绝不是“最终业务结果已经达成”。
示例中之所以可以直接调用 task_done，是因为处理过程仅是短暂等待和追加内存列表，没有真实业务的持久化要求。进入生产环境时，必须把持久化与确认顺序设计清楚。例如，需要先成功写入结果记录，再认为本次处理完成；如果业务失败，也要明确写下失败结果，避免在成功与失败之间留下不可见的灰色地带。
不要把正常退出和强制取消混为一谈。这里的消费者不是被外部 cancel 赶走的，而是在队列完成存量工作、变为空以后，通过 QueueShutDown 自然离开循环。若中间有其他系统信号打断整个 asyncio.run，仍须针对应用的外层任务管理处理取消与清理。队列关闭方法不会替应用自动完成全部资源释放。
四、immediate=True 是紧急停止，不是优雅完成
shutdown 的 immediate 参数默认是 False。设为 True 后，尚未被消费者取走的排队项目会被直接移走，等待 get 的消费者会收到 QueueShutDown；被阻塞的 put 同样会被拒绝。更关键的是，队列的未完成计数会扣除被移走项目所对应的数量，join 可能因此提前返回。
这意味着：join 在立即关闭模式下不再承诺“原先提交的每项工作都真正执行”。官方文档明确提醒，立即关闭会破坏通常的 join 不变量。它提供的是快速终止队列等待关系的能力，而不是业务补偿能力。已经被消费者取出的在途项目，也不会因为调用 shutdown 就凭空中止执行，应用仍须自行管理这些工作协程。
下面是一段最小实验。队列里放了尚未处理的项目，直接立即关闭；随后的 join 可以返回，但没有任何消费者执行过那条工作。代码特意展示入队之后立刻强制关停的语义，说明为什么不能仅凭 join 返回就写成功回执。
import asyncio
async def main():
queue = asyncio.Queue()
queue.put_nowait("invoice-001")
queue.shutdown(immediate=True)
await queue.join()
assert queue.empty()
try:
await queue.put("invoice-002")
except asyncio.QueueShutDown:
print("new work rejected")
print("join returned; work was not executed")
if __name__ == "__main__":
asyncio.run(main())
适合使用立即关闭的场景通常有明确的放弃语义：测试环境快速拆除、无须保留的临时缓存加工任务、外层已经决定整体回滚的执行阶段。若队列装的是订单、支付通知或者不可重复执行的发布任务，应该特别谨慎。调用成功不代表这些项目已经安全落盘，也不代表外部系统已接受取消。需要业务级停机，就必须先记录哪些项目处于排队、执行中、成功、失败或待补偿状态。
注意 immediate 不是一种“更快的正常关闭”。它改变了完成条件，改变的是系统对于未处理工作可否被丢弃的承诺。在真实项目里，默认先使用普通关闭；只有在清楚接受什么损失时，才考虑立即关闭。这不是性能建议，而是数据一致性约束。
五、join、task_done 与任务成功不是一回事
理解 Queue 最容易踩坑的地方，就是把三个数字混在一起：当前排队数、未完成任务数以及业务成功数。当前排队数随 put 和 get 变化；未完成任务数随 put 与 task_done 变化；业务成功数却必须由应用自己的存储和业务确认来决定。Python 不可能知道某笔 HTTP 请求实际在服务端是否提交，也无法仅凭本地协程结束就判断远端结果。
| 观察信号 | 能说明什么 | 不能说明什么 |
|---|---|---|
| qsize 为零 | 当前没有待取出的项目 | 在途任务已经完成 |
| join 返回 | 正常模式下已平衡未完成计数 | 外部服务确认成功 |
| task_done 调用 | 本次取出的项目已结算计数 | 业务没有失败 |
| shutdown 完成 | 队列进入拒绝新任务状态 | 所有消费者已经退出 |
| immediate 模式的 join 返回 | 队列计数满足结束条件 | 未执行的项目都被处理 |
如果消费者取到项目后忘记调用 task_done，join 可能长期等待。如果重复调用 task_done，未完成计数可能越界并引发 ValueError。将 task_done 放入与一次成功 get 对应的 finally，是保持队列计数可靠的基础习惯；但对于有重试需求的业务，要区分“把原任务重新入队”和“确认原任务本轮结束”，保证每次成功 get 恰好对应一次 task_done。
另一个常见误解是，用任务计数构造业务幂等。比如一个发布工作由于网络超时而重试，在两个进程中都执行了提交，queue.join 再精确也不能阻止平台出现两篇文章。幂等需要在业务侧额外建立任务标识、提交尝试记录和平台回读验证。Queue 管的是消费者的工作分派与生命周期，它不替代数据库事务，不提供分布式锁，也不提供平台级一次性提交保证。
因此，当监控系统显示“所有任务已完成”，至少要解释这是什么口径：是队列 join 已返回，是每项处理函数都写出了终态，还是业务平台真的完成了验收。不同口径之间的缺口，往往就是线上“程序说处理完了，用户却没收到结果”的根源。
六、真正接入服务时，先管住生产者再关闭队列
上述简单示例里，所有任务都是主协程直接投递的，因此生产者何时停止非常清楚。真实服务可能同时接收 WebSocket 消息、定时器任务、HTTP 请求或数据库变更通知。关闭时不能只对队列调用 shutdown，然后假装其他入口都停止了。应该首先让入口层拒绝新的业务请求，或者等待上游生产者有序退出，再关闭队列，避免在切换边界出现“请求看起来接收了，但没有进入队列”的情况。
例如，服务收到停止信号后，先把健康检查改为不再接受新流量，等正在处理的入口请求结束；接着对内部队列调用普通 shutdown，让消费者消化存量；然后 await join，最后 await gather 所有 worker。完成后才关闭数据库连接、文件句柄和日志输出。这种顺序在多组件服务中尤其重要，因为上层连接若提前断开，消费者可能已经没有地方写处理结果。
反过来，如果一上来就取消所有工作协程，排队工作可能没有人消费，处于执行中的项目可能在某个 await 上收到取消异常。最终既无法证明任务处理完成，也无法证明它从未开始处理。需要在故障场景中强制停止时，应保留明确的中断回执，而不是把中断包装成成功结束。对于不可重复的任务，特别要坚持“先查远端终态，再决定是否补偿”。
普通关闭还不意味着等待可以无限长。若某个消费者调用外部接口始终无响应，join 也可能一直无法返回。服务可以为整体停机设置超时预算，在预算耗尽后升级到独立故障处理流程；但不能直接使用 immediate=True 将未完成项目抹掉，又在日志里记录“全部成功”。超时代表未知或失败，必须和完成状态区分。
七、上线前用四组故障场景做验收
第一组检查正常关闭：投递固定数量的项目，关闭队列，等待 join，确认每项都产生业务回执、消费者全部退出。第二组检查拒绝新工作：关闭之后调用 put 和 put_nowait，确认它们抛出 QueueShutDown，同时检查等待空位的生产者能被唤醒。第三组检查在途任务：让消费者取到项目以后延迟处理，确认队列虽然变空，join 仍然等待对应的 task_done。第四组检查强制关闭：保留尚未被取出的项目，然后调用 immediate=True，验证 join 可能在工作未执行时返回，并且应用不会把这种情况标记为成功。
测试里还应专门覆盖异常路径。让某个消费者在处理期间抛异常，检查是否仍然平衡 task_done，以及失败结果有没有进入正确的业务回执。让最后一个消费者退出后再尝试获取数据，确认不会再出现永远等待的协程。把消费者数量从一个扩到多个，看是否出现只退出部分消费者的问题。此前依赖哨兵对象的代码迁移时，也应测试正常工作数据恰好等于旧哨兵值的边界情况。
对监控来说，建议至少分开记录“已接收”“正在处理”“成功”“失败”“关闭拒绝”五种状态。队列长度可以当作流量压力指标，不能替代业务成功率。停机日志里应记录关闭模式和时间、当时的在途任务数、最终回执数及仍然未知的任务数。这些信息比一句“优雅退出完成”更有追查价值，也方便下次恢复时避免重复执行。
最后记住这条判断：shutdown(False) 的目标是让队列不再接收新任务，同时允许旧任务正常消化；shutdown(True) 的目标是尽快解除等待关系，不能再保证所有排队项目都执行过。两者不是一快一慢的性能开关，而是两种不同的数据承诺。真正稳健的异步服务，会把队列状态、工作协程状态和业务终态分开设计，停机时才能知道自己到底完成了什么。
参考资料：Python 3.13 标准库 asyncio Queue 官方文档，docs.python.org/3.13/librar… 标准库线程队列文档，docs.python.org/3.13/librar…
