Threading.local 用于创建线程局部存储，使每个线程拥有独立变量副本以避免数据竞争；它通过线程内独立字典实现，不支持跨线程传递，协程中需改用 contextvars。
threading.local 是 python 中用于创建线程局部存储（Thread-Local Storage, TLS）的对象，它让每个线程拥有自己独立的变量副本，互不干扰。这在多线程环境下避免数据竞争、保存线程上下文（如请求 ID、数据库连接、用户信息等）非常实用。
为什么需要 threading.local
普通全局变量或函数内变量在多线程中是共享的，容易引发状态混乱。比如 Web 框架中想为每个请求记录唯一 trace_id，若用全局变量，多个线程会互相覆盖；而用 threading.local，每个线程读写的是自己的副本，天然隔离。
基本用法：创建和访问线程局部变量
只需实例化一个 threading.local() 对象，然后像操作普通对象一样给它动态设置属性即可。不同线程对同一属性的读写完全独立：
- 主线程设置
local_data.name = "main"，子线程设置local_data.name = "worker1"，彼此互不影响 - 子线程首次访问未定义的属性会触发
AttributeError，需先赋值或用getattr(local_data, 'attr', default)安全获取 - 局部变量仅在当前线程生命周期内有效；线程结束后，对应数据自动回收（无需手动清理）
典型使用场景示例
常见于需要“每线程单例”或“线程上下文透传”的地方：
立即学习“Python免费学习笔记（深入）”；
- Web 请求追踪：在中间件中为每个请求生成唯一 request_id，并存入 local，后续日志、数据库操作均可直接取用
- 数据库连接管理：每个线程维护自己的数据库连接对象，避免连接被其他线程误关或复用
- 临时缓存或配置切换：例如测试时为某线程启用 debug 模式，不影响其他线程行为
注意事项与常见误区
threading.local 不是魔法，理解其机制能避开坑：
- 它不是线程安全的“锁”，而是靠 Python 解释器在每个线程中维护独立字典实现，本身无同步开销
- 不能跨线程传递 local 对象或其属性（因为另一线程根本看不到这些值）
- 不要在 local 对象上直接存可变对象（如 list、dict）并期望线程间隔离——虽然引用是隔离的，但若多个线程修改同一个 list 内容，仍可能出问题；应确保每次赋值都新建对象，或用不可变类型
- 协程（如 asyncio）中 threading.local 失效，因协程常在同一线程内切换；此时应改用 contextvars 模块