数据分析agent (七）：contextvars 模块上下文request_id

from contextvars import ContextVar





request_id_ctx_var=ContextVar("request_id",default="1")

print(request_id_ctx_var)
# <ContextVar name='request_id' default='1' at 0x0000016735053E70>
print(request_id_ctx_var.get())
# 1

这段代码使用了 Python 标准库 contextvars 模块，创建了一个名为 request_id 的上下文变量（Context Variable），并设置了默认值为 "1"。

代码解析：

python

from contextvars import ContextVar

# 创建一个上下文变量，键名为 "request_id"，默认值为字符串 "1"
request_id_ctx_var = ContextVar("request_id", default="1")

它的核心作用：

ContextVar 是 Python 3.7 引入的特性，主要用于在**异步编程（asyncio）**中安全地存储和传递数据。

它的最大特点是：每个异步任务（Task）或线程都有自己独立的数据副本，互不干扰。

典型应用场景：

这段代码通常用于 Web 后端服务（如 FastAPI、Flask 等），用来追踪请求：

1. 日志追踪（Request Tracing） ：
   当一个 HTTP 请求进入服务器时，生成一个唯一的 UUID，存入这个变量。后续在这个请求生命周期内调用的所有函数、甚至跨越多层异步调用，都可以通过 request_id_ctx_var.get() 获取到当前请求的 ID，从而方便在日志中追踪同一个请求的完整链路。
2. 多租户数据隔离 ：
   在 SaaS 系统中，用来存储当前请求的 tenant_id，确保异步操作时不会查到其他租户的数据。

基本用法示例：

# 获取当前上下文中的 request_id（如果没设置过，则返回默认值 "1"）
current_id = request_id_ctx_var.get()
print(current_id)  # 输出: "1"

# 设置新的值
token = request_id_ctx_var.set("req-abc-123")

# 再次获取
print(request_id_ctx_var.get())  # 输出: "req-abc-123"

# 恢复之前的值（通常在请求结束时清理上下文）
request_id_ctx_var.reset(token)

在实际的企业级项目（尤其是 Python 异步 Web 项目，如 FastAPI、Tornado、aiohttp 等）中，ContextVar 扮演着**"异步上下文数据传递"**的核心角色。

它的出现主要是为了解决一个痛点：在多线程中可以用全局变量或线程局部变量（threading.local）存数据，但在 Python 的异步协程（asyncio）中，多个协程可能在同一个线程里交替运行，传统的线程局部变量会失效，导致数据错乱。

在实际项目中，它通常被用于以下 4 个核心场景：

1. 全链路请求追踪（Request Tracing）与日志（最常见）

在微服务或复杂的 Web 后端中，一个用户请求可能会触发几十个内部函数调用。如果想在日志中把这一系列调用串联起来，就需要一个全局唯一的 request_id。

• 传统做法的痛点 ：需要把这个 request_id 作为参数，一层一层地传递给每一个函数。如果函数签名改变，所有调用链都要改，极其繁琐。
• ContextVar 的做法 ：在请求刚进入中间件（Middleware）时，生成 UUID 并 set 到 ContextVar 中。后续无论调用多深的函数，只要 get() 就能拿到这个 ID。
• 实际效果 ：配合日志库（如 logging），可以自动在每一行日志前加上 [req_id: abc-123]，排查线上 Bug 时一目了然。

2. 多租户数据隔离（SaaS 系统）

在 SaaS（软件即服务）架构中，多个租户（公司/客户）共用一个数据库连接池。

• 实际应用 ：在请求进来时，把当前的 tenant_id 存入 ContextVar。当底层执行 SQL 查询时，底层的 ORM 或数据库驱动会自动从 ContextVar 中读取 tenant_id，并自动在 SQL 后面追加 WHERE tenant_id = ?。
• 好处 ：极大地防止了"数据越权"（A 公司看到了 B 公司的数据），并且不需要在每一个业务函数里手动传递 tenant_id。

3. 数据库会话（DB Session）与事务管理

在异步 ORM（如 SQLAlchemy Async）中，管理数据库连接的生命周期是一个难题。

• 实际应用 ：使用 ContextVar 来绑定当前协程的数据库会话（Session）。确保在一个异步请求处理过程中，无论经过多少次 await 挂起和恢复，使用的始终是同一个数据库连接和事务上下文。
• 好处：避免了并发请求时，不同协程意外使用了同一个数据库连接导致的"脏数据"或"事务混乱"问题。

4. 用户身份与权限上下文（User Context）

• 实际应用 ：在鉴权中间件中验证 Token 后，将解析出的 current_user 对象存入 ContextVar。后续的业务逻辑（如保存创建人、校验操作权限）可以直接从 ContextVar 中获取当前用户信息。
• 好处 ：业务代码变得非常干净，不需要到处写 get_current_user() 这样的依赖注入。

---

💡 总结对比

表格

场景	多线程时代 (Threading)	异步协程时代 (Asyncio + ContextVar)
数据隔离单位	线程 (threading.local)	协程任务 (ContextVar)
数据传递	隐式传递（同线程内共享）	隐式传递（同协程链路内共享）
并发安全性	线程切换时安全	协程 await 切换时绝对安全，互不干扰

简单来说，ContextVar 就是异步时代的"线程局部变量"。它让开发者在编写高并发、异步代码时，依然能够像写同步代码一样，优雅地使用"全局上下文"，而不必担心数据污染和参数传递的噩梦。

import uuid
import logging
from contextvars import ContextVar
from fastapi import FastAPI, Request
from starlette.middleware.base import BaseHTTPMiddleware

# ================= 1. 定义 ContextVar =================
# 创建一个专门用来存 request_id 的上下文变量，默认值为 "default"
request_id_ctx_var: ContextVar[str] = ContextVar("request_id", default="default")

# ================= 2. 自定义日志过滤器 =================
class RequestIdFilter(logging.Filter):
    """
    自定义过滤器：在日志输出时，自动从 ContextVar 中获取当前的 request_id
    """
    def filter(self, record):
        # 从当前协程的上下文中获取 request_id
        record.request_id = request_id_ctx_var.get()
        return True

# 配置日志格式，把 request_id 加进去
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s | [%(request_id)s] | %(levelname)s | %(message)s"
)
logger = logging.getLogger(__name__)
logger.addFilter(RequestIdFilter()) # 挂载过滤器

# ================= 3. 编写业务逻辑 =================
app = FastAPI()

def process_data(data: str):
    """模拟深层业务逻辑：注意这里并没有把 request_id 作为参数传进来！"""
    logger.info(f"正在处理数据: {data}")
    return f"Processed: {data}"

@app.get("/")
async def root():
    logger.info("收到根路由请求")
    result = process_data("Hello ContextVar")
    return {"message": result}

# ================= 4. 编写中间件拦截请求 =================
class RequestIdMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        # 为每个进来的请求生成一个唯一的 UUID
        request_id = str(uuid.uuid4())[:8]
        
        # 将 request_id 存入当前协程的 ContextVar 中
        request_id_ctx_var.set(request_id)
        
        logger.info("请求开始处理")
        response = await call_next(request)
        logger.info("请求处理完毕")
        
        return response

# 注册中间件
app.add_middleware(RequestIdMiddleware)

💡 运行效果

当你启动这个服务并访问 http://127.0.0.1:8000/ 时，控制台打印的日志会是这样的：

2024-05-20 10:00:01,123 | [a1b2c3d4] | INFO | 请求开始处理
2024-05-20 10:00:01,124 | [a1b2c3d4] | INFO | 收到根路由请求
2024-05-20 10:00:01,125 | [a1b2c3d4] | INFO | 正在处理数据: Hello ContextVar
2024-05-20 10:00:01,126 | [a1b2c3d4] | INFO | 请求处理完毕

🎯 核心亮点解析：

1. 隐式传递 ：process_data 函数完全不需要知道 request_id 的存在，也不需要接收它作为参数，就能在日志中自动带上。这在几十层嵌套的复杂业务中简直是"救命"的设计。
2. 绝对隔离 ：如果有 100 个用户同时并发访问这个接口，ContextVar 会保证每个协程都有自己独立的 request_id，日志绝对不会串线（比如 A 用户的请求日志里出现了 B 用户的 ID）。
3. 解耦 ：日志系统（logging）和业务代码完全解耦。你不需要在每一个业务函数里写 logger.info(f"[{request_id}] ...") 这种重复代码。

这就是 ContextVar 在真实企业级项目中最典型的用法。希望这个例子能帮你彻底搞懂它！