Python FastAPI应用如何为请求日志自动添加请求ID前缀

最适配FastAPI异步场景的方案，是结合*上下文变量（ContextVar）*与自定义日志过滤器，完全替代手动拼接字符串的写法，零侵入接入整个请求链路的日志输出。

具体实现步骤 #

1. 定义全局上下文变量存储当前请求的唯一ID
   Python 3.7+ 内置的ContextVar天然适配异步协程的上下文隔离，不会出现线程本地变量（ThreadLocal）在协程切换时串值的问题。

   import logging
   from contextvars import ContextVar
   import uuid
   
   # 定义上下文变量，设置默认值为"-"，避免非请求触发的日志场景报错
   request_id_ctx: ContextVar[str] = ContextVar("request_id", default="-")
   

2. 编写自定义日志过滤器，动态注入请求ID到日志记录中
   过滤器会在每条日志输出时，自动从上下文变量中读取当前请求对应的ID，写入日志记录的字段里，不需要手动传入。

   class RequestIdLogFilter(logging.Filter):
       def filter(self, record: logging.LogRecord) -> bool:
           # 读取上下文中的请求ID，注入到日志记录对象
           record.request_id = request_id_ctx.get()
           return True
   

3. 调整日志格式配置，把注入的请求ID字段加入输出模板
   比如将原本的日志格式改为包含request_id字段的模板，最终输出效果和手动拼接的格式完全一致：

   # 示例日志配置
   logging.basicConfig(
       format="%(asctime)s [%(request_id)s] %(levelname)s | %(module)s:%(lineno)d - %(message)s",
       level=logging.INFO,
   )
   # 给根日志的所有处理器挂载自定义过滤器
   root_logger = logging.getLogger()
   for handler in root_logger.handlers:
       handler.addFilter(RequestIdLogFilter())
   

4. 在FastAPI请求中间件中注入当前请求的ID到上下文
   中间件会在每个请求进入时，从请求头/查询参数/请求体中读取上游传入的request_id，写入上下文变量；请求处理完成后自动清理上下文，避免变量泄漏。

   from fastapi import FastAPI, Request
   
   app = FastAPI()
   
   @app.middleware("http")
   async def bind_request_id_context(request: Request, call_next):
       # 从请求头读取上游传入的请求ID，未携带则自动生成默认值
       # 如果request_id存在查询参数/请求体中，对应调整读取逻辑即可
       request_id = request.headers.get("X-Request-ID") or uuid.uuid4().hex[:12]
       # 将请求ID写入当前异步上下文
       context_token = request_id_ctx.set(request_id)
       try:
           response = await call_next(request)
       finally:
           # 请求处理完成重置上下文，避免后续请求复用上下文时残留旧值
           request_id_ctx.reset(context_token)
       # 可选：将请求ID写回响应头，方便下游服务关联链路
       response.headers["X-Request-ID"] = request_id
       return response
   

方案优势 #

• 零侵入：不需要在任意异步方法、工具类、业务模块的日志语句里手动拼接request_id，所有和当前请求链路关联的日志，都会自动带上对应前缀，原本需要写的logger.info(f"[{data['request_id']}] xxx")可以直接简化为logger.info("xxx")
• 适配异步场景：ContextVar和异步协程的执行上下文绑定，协程切换时不会出现不同请求的日志ID串混的问题
• 低维护成本：后续新增日志语句、新增业务方法时，完全不需要考虑请求ID的拼接逻辑，日志链路的上下文是全局统一注入的

关键注意事项 #

• 禁止用ThreadLocal存储请求ID：异步模式下单线程会并发处理多个请求，ThreadLocal无法隔离协程级别的上下文，必然出现ID串值的问题
• 过滤器必须挂载到所有实际输出日志的处理器上：如果单独配置了输出到文件、输出到日志平台的自定义Handler，没有挂载对应的过滤器，输出的日志会因为缺少request_id字段触发KeyError
• 必须在请求结束时重置上下文变量：否则复用的事件循环上下文会残留上一个请求的ID值，导致非当前链路的日志带上错误的ID

内容的提问来源于stack exchange，提问作者BBloggsbott