Python如何让所有日志消息自动携带API请求载荷中的UUID

核心思路是把请求维度的UUID存在请求上下文隔离的全局存储里，再给日志模块加统一过滤器，输出日志时自动从上下文读取UUID拼到日志内容中，全程不需要在函数调用链路里显式传参，完全没有代码侵入。

方案1：Python 原生contextvars（兼容同步/异步、多线程场景，首推） #

Python 3.7 引入的contextvars模块天生做了上下文隔离，不同请求的协程、线程不会互相污染变量，是Python生态实现链路追踪上下文传递的标准方案。

实现步骤 #

1. 定义全局上下文变量存储请求UUID

import uuid
from contextvars import ContextVar
# 初始化上下文变量，无请求时默认值为空字符串
request_uuid: ContextVar[str] = ContextVar("request_uuid", default="")

2. 在Flask请求入口统一写入UUID，不需要向业务层传递

from flask import Flask, request
app = Flask(__name__)

@app.before_request
def inject_request_uuid():
    # 优先从请求头/请求载荷取上游透传的UUID，没有则自动生成
    req_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())
    # 将UUID写入当前请求的独立上下文
    request_uuid.set(req_id)

3. 给日志添加统一过滤器，所有日志输出时自动携带UUID，不需要每个日志语句手动拼接

import logging

class UUIDLogFilter(logging.Filter):
    def filter(self, record):
        # 从上下文读取当前请求的UUID，挂载到日志记录对象上
        record.request_uuid = request_uuid.get()
        return True

# 为日志实例绑定过滤器，配置统一输出格式
app.logger.addFilter(UUIDLogFilter())
log_formatter = logging.Formatter("%(asctime)s - %(levelname)s - [ReqID:%(request_uuid)s] - %(message)s")
for handler in app.logger.handlers:
    handler.setFormatter(log_formatter)

4. 业务代码完全不需要传递UUID参数，直接正常写逻辑打日志即可

def call_bar():
    app.logger.info("执行call_bar逻辑")   

def call_foo():
    app.logger.info("执行call_foo逻辑")    
    call_bar()

@app.route("/test")
def flask_view():
    app.logger.info("请求进入视图函数")
    call_foo()
    return "success"

最终输出的每一行日志都会自动带上当前请求的UUID，不管函数嵌套多少层都不需要修改函数传参，维护成本为0。

方案2：Flask 自带g对象（仅适合纯同步Flask场景） #

如果项目是传统同步部署的Flask应用，没有异步视图、gevent协程、手动开线程的逻辑，也可以直接用Flask提供的请求全局对象g存储UUID，实现逻辑更简单：

from flask import g

@app.before_request
def inject_uuid():
    g.request_uuid = request.headers.get("X-Request-ID") or str(uuid.uuid4())

class FlaskUUIDFilter(logging.Filter):
    def filter(self, record):
        # 无请求上下文时（比如离线脚本、启动初始化阶段）返回空值避免报错
        try:
            record.request_uuid = g.request_uuid
        except RuntimeError:
            record.request_uuid = ""
        return True

注意：该方案不兼容异步视图、协程调度、手动新开线程/进程的场景，这类场景下g对象会丢失上下文，优先选择contextvars方案。

落地注意事项 #

• 如果请求内需要手动新开线程执行逻辑，要使用contextvars.copy_context().run(目标函数)的方式启动线程，否则新线程内无法读取到对应请求的UUID
• 如果集成了Celery等异步任务框架，下发任务时需要把UUID序列化传入任务参数，在任务执行入口重新写入contextvars，即可保证异步任务日志也能关联原请求UUID
• 调用下游微服务时，可以把UUID放到HTTP请求头X-Request-ID中自动透传，实现跨服务的全链路日志关联
• 禁止用普通全局变量存储UUID，多线程/协程场景下不同请求的UUID会互相覆盖，导致日志串号

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