loggeradapter 是最轻量可靠的上下文注入方式，因其为标准库原生机制，不依赖第三方、不污染全局、不改变调用习惯，仅需封装 logger 即可自动注入上下文字段。
为什么 LoggerAdapter 是最轻量又可靠的上下文注入方式
因为它是标准库原生支持的机制，不依赖第三方、不污染全局状态、不改变日志调用习惯。你只需要在每次获取 logger 时套一层适配器，后续所有 logger.info()、logger.error() 都会自动带上你传入的上下文字段。
常见错误是试图在 Formatter 里硬塞变量，或者用 threading.local 手动维护上下文——前者无法跨线程/协程传递，后者容易泄漏、难清理、和异步框架（如 asyncio）冲突。
使用场景：Web 请求 ID、用户 ID、任务批次号这类“一次请求/任务生命周期内固定”的字段；不适合存高频变动的局部变量（比如循环里的 i）。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 始终用
LoggerAdapter的extra参数传字典，不要直接改logger.extra（它不存在） - 避免在
extra中传可变对象（如 dict、list），防止被后续日志修改影响输出 - 如果用
structlog或loguru，别硬套这个方案——它们有自己更自然的绑定方式
import logging
logger = logging.getLogger("myapp")
adapter = logging.LoggerAdapter(logger, {"request_id": "abc123", "user_id": 42})
adapter.info("login succeeded") # 输出自动含 request_id 和 user_id
filter 方法能解决跨模块/跨线程上下文丢失问题吗
能，但必须配合 LogRecord 动态注入，且只对当前 handler 生效。它的核心价值不是“加字段”，而是“按需补字段”——比如你在中间件里把 request_id 存到了 threading.local，就可以用 filter 在每条日志生成前把它捞出来塞进 record。
容易踩的坑：
- 忘记在
filter()里返回True，导致日志被静默丢弃 - 在多线程环境里误用全局变量或未初始化的
threading.local属性，造成上下文串扰 - filter 中做耗时操作（如查数据库、发 HTTP 请求），拖慢整个日志链路
性能影响很小，但兼容性要注意：asyncio 任务中 threading.local 不起作用，得换 contextvars.ContextVar。
import logging import threading _local = threading.local() <p>class ContextFilter(logging.Filter): def filter(self, record): record.request_id = getattr(_local, "request_id", "unknown") return True # 必须返回 True，否则日志被过滤掉
用 contextvars 支持 asyncio 场景下的上下文穿透
这是 Python 3.7+ 唯一推荐的异步上下文方案。它比 threading.local 更底层、更安全，能跨 await 边界保留值。但注意：它不会自动注入到日志 record，必须和 Filter 或 LoggerAdapter 配合使用。
典型错误是以为声明了 ContextVar 就万事大吉——没在 record 上显式赋值，formatter 依然看不到。
使用场景：FastAPI、Starlette、Tornado 异步服务；或任何用了 async/await 且需要日志带 trace_id 的地方。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 定义
ContextVar时给默认值（如ContextVar("request_id", default="")），避免LookupError - 在请求入口（如中间件）调用
var.set(value)，不要在日志调用点重复 set - filter 中用
var.get()取值，别用var.reset(token)——那是清理用的，不是读取用的
import contextvars
import logging
<p>request_id_var = contextvars.ContextVar("request_id", default="")</p><p>class AsyncContextFilter(logging.Filter):
def filter(self, record):
record.request_id = request_id_var.get()
return TrueFormatter 模板里怎么安全引用注入的字段
用 %(request_id)s 这种老式字符串格式语法，不要用 f-string 或 {request_id}。因为 logging 模块内部用的是 % 格式化，其他写法会直接报 KeyError 或静默忽略字段。
容易被忽略的点：
- 字段名必须和你注入到
extra或record中的 key 完全一致（大小写、下划线都不能错） - 如果字段可能为
None，模板里写成%(request_id)s会炸，要先在 filter 或 adapter 里转成字符串（如str(var.get() or "")） - 自定义 formatter 继承
logging.Formatter时，别重写format()去手动拼接——破坏了 lazy evaluation，失去性能优势
兼容性上，%(xxx)s 写法从 Python 2.7 到 3.12 全版本有效，最稳。
formatter = logging.Formatter(
"%(asctime)s %(name)s %(levelname)s [req=%(request_id)s] %(message)s"
)事情说清了就结束。关键不在“怎么加字段”，而在于字段生命周期是否和你的执行模型对齐——同步用 threading.local，异步必须用 contextvars，混用会出不可预测的空值或错值。
