contextvars模块用于异步任务中安全管理上下文局部变量，使每个协程拥有独立变量副本；核心组件包括ContextVar（声明变量）、copy_context（获取上下文快照）和Context（执行环境）。
Python 的 contextvars 模块用于在异步任务或协程中安全地管理“上下文局部变量”，它解决了传统线程局部变量（threading.local）在 asyncio 中无法隔离的问题。核心目标是：让每个协程拥有自己独立的变量副本，互不干扰。
为什么需要 contextvars？
在 asyncio 应用中，多个协程可能并发运行于同一线程。若用全局变量或 threading.local，不同协程会意外共享或覆盖彼此的数据——比如用户身份、请求 ID、日志追踪号等需按请求隔离的状态。
而 contextvars 基于 Python 3.7+ 的上下文（Context）机制，每个协程自动绑定独立上下文，变量天然隔离。
三个核心组件：ContextVar、copy_context、Context
ContextVar：定义一个上下文变量，类似“变量声明”。它本身不存值，只提供 get() 和 set() 接口。
立即学习“Python免费学习笔记（深入）”；
- 初始化时可设默认值：
request_id = ContextVar("request_id", default=None) -
get()返回当前上下文中的值，未 set 过则返回默认值（或抛LookupError） -
set(value)返回一个 Token，可用于后续reset(token)恢复旧值
copy_context()：获取当前协程的上下文快照（Context 对象），常用于在子任务中显式传递上下文。
- 例如：在
asyncio.create_task()前调用ctx = copy_context()，再用ctx.run(coro)启动协程，确保子任务继承父上下文 - 注意：普通
create_task()默认会继承上下文，但跨线程或自定义执行器时需手动处理
Context：表示一次执行的上下文环境。它不可直接构造，只能通过 copy_context() 获取，并用 run(callable, *args) 在其中执行函数。
典型使用场景与写法
Web 请求生命周期中透传请求 ID
- 在 ASGI/HTTP 入口处（如 FastAPI middleware 或 Quart before_request）
request_id.set(generate_id()) - 后续任意深度的异步函数中，直接
request_id.get()即可拿到当前请求的 ID - 无需层层传参，也不依赖装饰器或中间件注入
避免 set 后忘记 reset 导致污染
- 推荐用
try/finally或上下文管理器封装： - token = var.set(value)
try:
# do something
finally:
var.reset(token)
与 logging 集成（添加 trace_id 到日志）
- 自定义
LogRecord工厂，读取request_id.get()并注入到 record 属性 - 配合
Formatter在格式串中使用%(trace_id)s，每条日志自动带上下文标识
常见误区与注意事项
-
ContextVar不是线程安全的替代品——它专为协程设计；多线程仍需threading.local或锁 - 不能在普通同步函数中可靠使用（除非你手动
copy_context().run()） - 变量值不会自动跨
await边界丢失，但若协程被取消或异常中断，未 reset 的 set 可能残留（建议 always reset） - 调试时可用
sys.get_coroutine_state()（3.12+）或打印contextvars.copy_context()查看当前上下文内容
