Python threading.local 是什么？线程本地变量适合什么场景？

简化版

threading.local() 用来创建线程本地存储：同一个属性名在不同线程里有不同值，互不影响。它适合保存请求上下文、数据库连接、用户信息等“和当前线程绑定”的状态，但在线程池和异步框架里要谨慎，避免上下文残留或用错模型。

普通全局变量被所有线程共享，需要锁保护；线程本地变量看起来像全局对象，但每个线程看到的是自己的副本。典型用法是：

import threading

local = threading.local()

def handle(user_id):
    local.user_id = user_id
    process()

process() 可以从 local.user_id 读取当前线程的用户 id，而不需要层层传参。但这种隐式状态会降低可读性和可测试性。在线程池中线程会复用，用完后要清理；在 asyncio 中应优先考虑 contextvars，而不是 threading.local。

多线程程序有时需要“每个线程一份状态”。例如 Web 服务器一个线程处理一个请求时，请求 id、用户 id、数据库连接可以和当前线程绑定。直接用全局变量会被其他线程覆盖，函数参数层层传递又很繁琐。

Thread A -> user_id = 1
Thread B -> user_id = 2

如果 user_id 是普通全局变量，B 会覆盖 A。threading.local 则让 A 和 B 看到不同的 user_id。

local = threading.local()
local.value = 1

这段代码设置的不是一个全局共享属性，而是当前线程关联的属性。另一个线程访问 local.value 时，如果它没有设置过，会发现属性不存在。

local 对象
  Thread A storage: value=1
  Thread B storage: value=2

同一个 local 对象内部按线程隔离存储。它解决的是“状态隔离”，不是“并发计算加速”。

锁保护全局变量适合多个线程共同修改同一份状态；线程本地变量适合每个线程有自己的状态。两者不是替代关系。

需求	适合
全局计数器累加	Lock
每线程数据库连接	threading.local
每请求上下文	threading.local / contextvars
多线程共享缓存	Lock + dict

如果业务需要汇总结果，线程本地变量不能自动合并；你仍然要在安全位置收集每个线程结果。

线程池会复用线程。一次请求设置的 local.user_id，如果处理结束后不清理，下一个复用同一线程的请求可能读到旧值。这是线上很难排查的坑。

Thread-1 处理 user=1 -> local.user_id=1
Thread-1 复用处理 user=2 -> 忘记设置时读到 1

所以在线程池中使用线程本地变量时，要在请求开始设置，在 finally 中清理。

try:
    local.user_id = user_id
    handle()
finally:
    if hasattr(local, "user_id"):
        del local.user_id

线程本地变量不是自动请求本地变量；线程复用时必须考虑清理。

threading.local 按线程隔离；contextvars 按执行上下文隔离，更适合 asyncio。异步程序里多个协程运行在同一个线程，如果用 threading.local，它们可能看到同一份线程状态。

asyncio 单线程:
  task A
  task B
  共享同一个 thread local

因此 FastAPI、aiohttp 等异步框架里，request id 这类上下文通常用 contextvars，而不是 threading.local。

老式同步 Web 框架、每线程一个请求模型，可以用线程本地变量保存 request 或 db session。现代代码更推荐显式传参、依赖注入或 contextvars，减少隐式全局状态。

同步多线程 -> threading.local 可用
异步协程 -> contextvars
清晰业务函数 -> 显式参数更好

不要为了少传一个参数就滥用线程本地变量。它提高局部便利性，但会牺牲可读性和测试透明度。

threading.local 记成“同名属性，每线程一份”。它适合同步多线程里的上下文隔离，但线程池要清理，异步协程要换 contextvars。回答时把“隔离状态”和“保护共享资源”分开，就不会把它误说成锁。