在 Python 3.7 之前，开发人员完全依赖 threading.local() 来存储特定请求的数据，如用户会话或数据库连接。然而，asyncio 的普及揭示了一个根本缺陷：线程本地存储在同一事件循环线程上运行的所有协程之间是共享的。当一个异步任务让出控制时，另一个任务可能无意中访问或修改第一个任务的孤立状态，从而导致安全漏洞和数据损坏。PEP 567 引入了 contextvars，以提供独立于操作系统线程的逻辑执行上下文隔离，这一概念借鉴了 C# 和 Erlang 中的类似机制。
在同步的 Python 中，每个 HTTP 请求通常在自己的线程上运行，这使得 threading.local() 足以存储请求上下文。在异步架构中，数千个并发请求可能会多路复用到一个由事件循环管理的线程上。如果两个异步任务交错执行——一个在 await 处暂停，而另一个恢复——它们共享同一个线程本地字典。如果没有机制在任务切换时快照和恢复上下文，全球状态在逻辑上不同的操作之间泄漏。这会导致竞争条件，其中任务 A 的身份验证令牌对任务 B 可见，或者数据库事务边界在无关请求之间模糊。
Python 实现 ContextVar 作为存储在线程状态中的不可变地图的键。每个异步任务保持对其自身 Context 对象的引用——这是一个持久的数据结构，修改时创建新版本而不是更改共享状态。当 asyncio 在 await 处暂停任务时，它捕获当前上下文；在恢复时，它恢复该上下文，确保 ContextVar.get() 返回与该特定任务绑定的值，即使操作系统线程可能已经发生变化。这种写入时复制语义保证了隔离而无需锁定开销。
import contextvars import asyncio request_id = contextvars.ContextVar('request_id', default='unknown') async def process_task(task_name): # 为该特定任务上下文设置值 token = request_id.set(task_name) try: await asyncio.sleep(0.01) # 让出控制，其他任务可以运行 current = request_id.get() print(f"Task {task_name} reads: {current}") finally: request_id.reset(token) # 恢复前一个上下文 async def main(): # 在同一线程上并发运行两个任务 await asyncio.gather(process_task('Alpha'), process_task('Beta')) asyncio.run(main())
一个构建高吞吐量 API 网关的团队从线程化的 Flask 应用程序迁移到异步的 FastAPI 服务。他们发现在负载下，存储当前用户的身份验证中间件随机将用户 A 的身份分配给用户 B 的请求。最初的调试表明存在竞争条件，但日志显示即使在单个工作进程的部署中，也会发生分配。根本原因是 asyncio 的协作式多任务处理，其中一个请求处理程序在数据库调用期间让出控制，允许另一个处理程序在同一线程上运行并继承线程本地存储。
团队最初尝试通过 threading.get_ident() 将全局字典键控，假设这会隔离请求。这种方法提供了一种从旧代码库的简单迁移，而没有引入外部依赖。然而，在 uvicorn 与 asyncio 下，同一线程顺序处理多个请求，导致字典保留之前请求的过时数据，并造成特权提升错误，即在无关请求之间身份验证会话不正确地保持。
他们将每个函数签名重构为接受 context 字典参数，将其传递到中间件到数据库层的整个调用栈中。这种显式数据流消除了隐藏状态，并在同步和异步边界之间有效。然而，这需要大规模重构，影响数千个函数，并打破期望全局配置对象的第三方库集成，同时导致生成的代码冗长极大增加了维护负担和开发者错误的风险。
团队采用 contextvars.ContextVar 来存储经过身份验证的用户对象，允许中间件在请求进入时设置变量，而下游函数通过 .get() 访问它，而不会污染函数签名。这种方法不需要架构的彻底改造，并在并发任务之间提供自动隔离，尽管它需要仔细管理 reset() 令牌，以防止在长时间运行的进程中内存泄漏。此外，调试变得更加困难，因为状态隐含在执行上下文中，而不是在堆栈跟踪中可见。
他们最终选择 contextvars，因为原型表明这仅需修改中间件层，避免了显式上下文传递所需的大规模重构。通过将请求处理程序包装在 try/finally 块中，以确保令牌被重置，他们防止了内存泄漏，同时保持函数签名简洁。该网关现在每个工作进程可处理 50,000 个并发连接，而不会出现请求之间的数据泄漏，团队将每个实例的操作系统线程数从 100 降至 4，内存使用量减少了 80%，并将整体吞吐量提高了 300%。
为什么 threading.local() 在异步代码中失败而在线程代码中有效？
在线程化的 Python 中，操作系统抢占式调度线程，每个线程保持其自身的 C 栈和 PyThreadState 结构。threading.local() 将变量映射到该操作系统级线程标识，确保隔离。在 asyncio 中，事件循环协作式调度在单个线程上的任务，使用队列；当一个任务让出控制时，循环立即在同一线程上运行另一个任务，而不切换 PyThreadState。因此，threading.local() 对两个任务看到相同的键，导致状态泄漏。Contextvars 通过在 PyThreadState 内维护上下文映射的堆栈，在任务切换期间交换，创建独立于操作系统线程的逻辑隔离。
如果忘记重置 ContextVar 令牌会发生什么？
ContextVar.set() 返回一个 Token 对象，表示先前的状态，必须将其传递给 reset() 以恢复先前的值。如果你忽略这一点——例如，通过省略 try/finally 块——变量会在预期范围之外保留其值。在长时间运行的异步服务器中，这会导致内存泄漏，旧请求上下文在上下文链中不断累积，如果上下文未得到适当恢复，随后的任务可能会继承过时的值。与在函数返回时消失的传统栈变量不同，上下文变量在执行上下文中持续存在，直到显式重置或直到任务结束，使清理成为必要。
上下文变量如何传播到子任务和线程？
当使用 asyncio.create_task() 时，子任务会自动接收父任务的当前上下文的副本，确保上下文变量在异步调用图中自然流动。然而，当使用 concurrent.futures.ThreadPoolExecutor 或 loop.run_in_executor() 时，可调用对象在一个默认情况下上下文为空的不同操作系统线程中执行。候选人常常假设上下文像线程本地存储那样跨线程边界传播，但 contextvars 专门用于逻辑异步上下文。要在线程间传播值，必须明确捕获上下文，使用 contextvars.copy_context()，并通过 context.run() 在其中运行函数，或者将变量作为参数手动传递。