Python 的上下文管理

Wed, 26 Aug 2026 00:00:00 +0800

一次请求经过网关、订单服务、库存服务和数据库时，链路追踪系统需要用 trace ID、span ID 等信息把各段调用关联起来。跨服务时，这些信息通常放在 HTTP traceparent、gRPC metadata 或消息头中；请求进入 Python 服务后，日志、指标和下游客户端仍要随时读到当前链路信息。

最直接的办法是显式传参：

def handle_request(trace_id: str) -> None:
    load_user(trace_id)
    create_order(trace_id)

调用链一长，trace_id 就会穿过许多本来不关心它的函数。全局变量也不合适，因为并发请求会覆盖彼此的值。threading.local() 能隔离线程，却分不清同一事件循环线程上的多个 asyncio Task。

Python 3.7 根据 PEP 567 引入 contextvars，用来保存“属于当前执行上下文”的状态。日志函数可以直接读取当前 trace ID，调用链不必层层转发它；asyncio 在切换 Task 时也会切换对应的 Context，避免请求之间串值。

contextvars 的作用域止于当前 Python 进程。跨进程、跨服务的传播仍要由追踪库把完整的 W3C Trace Context 注入载体，在接收端提取后再写入本地 Context。

本文先从公开 API 建立行为模型，再用 CPython 3.14.2 解释不同并发场景为何表现不同。源码固定在 CPython commit df793163d5821791d4e7caf88885a2c11a107986。对象字段、缓存和 C 函数属于这一版 CPython；其他 Python 实现只需遵守公开语义。

1. `contextvars` 的设计语义#

ContextVar 不是保存当前值的容器，而是 Context 映射中的键。这一点决定了后面的所有行为。

Contextvars on Yeqown

Python 的上下文管理

1. contextvars 的设计语义#

1. `contextvars` 的设计语义#