Python contextvars Token 怎样撤销临时上下文修改

Python 的 contextvars 适合保存异步任务的上下文局部状态，但临时覆盖一个变量后，真正负责“撤销”的不是下一次 get()，而是 set() 返回的 Token。把这个 Token 传给同一个 ContextVar 的 reset()，就能恢复到这次 set() 之前的状态。

官方地址：https://docs.python.org/3/library/contextvars.html#contextvars.Token

最稳妥的规则是：一次 set() 保存一个 Token，一次临时操作对应一次 reset(token)，恢复动作放在 finally 中，并按嵌套的相反顺序执行。

先看 Token 和 reset 的对应关系

我在排查“局部设置了请求标识，后续代码却继续读到它”的问题时，最先会看是否只调用了 set()，却没有保留返回值。set(value) 返回的 Token 记录了这次修改之前的状态；如果变量此前没有值，Token 的 old_value 会指向 Token.MISSING。

下面这个最小片段只展示状态关系，不需要依赖异步框架：

from contextvars import ContextVar

request_mode = ContextVar("request_mode", default="normal")

def render_preview() -> str:
    # 保存 set 之前的状态，供 finally 中恢复。
    token = request_mode.set("preview")
    try:
        # 这段局部逻辑读取到临时值。
        return request_mode.get()
    finally:
        # 必须把同一个 Token 交给创建它的 ContextVar。
        request_mode.reset(token)

print(render_preview())
print(request_mode.get())

调用结束后，第二次读取会回到 normal。如果创建变量时没有设置默认值，那么 reset 后它会恢复为“未设置”，下一次不带默认参数的 get() 可能抛出 LookupError，这也是需要明确区分的结果。

嵌套修改要按相反顺序恢复

临时覆盖经常会发生嵌套：外层先把模式设为 batch，内层又把它改成 preview。每次 set() 都必须保存自己的 Token。恢复时先 reset 内层 Token，再 reset 外层 Token，才能逐层回到进入这段逻辑之前的状态。

from contextvars import ContextVar

mode = ContextVar("mode", default="normal")

def nested_override() -> str:
    # 外层修改必须拥有独立 Token。
    outer_token = mode.set("batch")
    try:
        # 内层修改再保存一个独立 Token。
        inner_token = mode.set("preview")
        try:
            return mode.get()
        finally:
            # 先撤销内层修改，回到 batch。
            mode.reset(inner_token)
    finally:
        # 最后撤销外层修改，回到 normal。
        mode.reset(outer_token)

print(nested_override())
print(mode.get())

这种写法的重点不是“把 Token 存到全局”，而是让 Token 的生命周期紧贴产生它的那次 set()。不要把一个 Token 交给无关的 ContextVar，也不要在已经 reset 后再次复用它；官方文档明确说明单个 Token 只能用于对应修改的一次恢复。

异常路径为什么必须保留 finally

如果临时逻辑中途抛出异常，直接把 reset() 写在业务语句之后并不可靠：异常会让那一行永远执行不到。把恢复动作放在 finally，可以把“无论成功还是失败都撤销临时状态”表达成代码结构。

from contextvars import ContextVar

trace_label = ContextVar("trace_label", default="outer")

def call_with_label(label: str) -> None:
    # 每次临时覆盖都生成与之配对的 Token。
    token = trace_label.set(label)
    try:
        # 真实项目中这里可能调用异步业务或抛出异常。
        raise RuntimeError("demo failure")
    finally:
        # 先恢复上下文，再让异常继续向上抛出。
        trace_label.reset(token)

try:
    call_with_label("inner")
except RuntimeError:
    # 异常处理代码看到的已经是 outer。
    print(trace_label.get())

要注意，finally 只负责恢复当前上下文的变量值，不会吞掉异常，也不会把不同线程或不同任务的 Context 合并。它解决的是局部修改的清理问题。

Python 3.14+ 可以让 Token 直接管理恢复

Python 3.14 起，Token 支持上下文管理器协议。也就是说，临时值可以写成 with variable.set(value)，离开 with 块时自动恢复，适合短小且边界清楚的覆盖场景。

from contextvars import ContextVar

format_mode = ContextVar("format_mode", default="plain")

def format_for_preview(text: str) -> str:
    # Python 3.14+ 会在离开 with 时自动 reset 对应 Token。
    with format_mode.set("preview"):
        return f"[{format_mode.get()}] {text}"

print(format_for_preview("hello"))
print(format_mode.get())

如果项目需要兼容更早的 Python 版本，继续使用显式的 token = set(...) 加 try/finally 更直观。无论采用哪种写法，都要保持“创建 Token 的变量负责恢复”这一约束。

几个容易误用的边界

• 忘记保存 Token：后续没有可靠的对应对象来恢复这次临时修改。
• 重复 reset：同一个 Token 不能重复用于恢复。
• 顺序颠倒：嵌套 set 应按后进先出的顺序 reset，避免跨层覆盖。
• 混用变量：Token 必须交给创建它的 ContextVar，不能凭变量名相似就替换。
• 误解作用域：reset 恢复的是当前 Context 中这次 set 之前的状态，不是全局变量回滚。

把这些边界放进代码评审清单后，contextvars 的临时覆盖就会从“调用后偶尔残留”的隐性问题，变成可以沿着 Token 配对关系定位的局部资源。

常见追问

没有默认值的 ContextVar reset 后会怎样？

如果 set 之前没有值，reset 会恢复为未设置状态；之后直接 get 可能抛出 LookupError，除非调用 get 时提供默认值。

一个 Token 能不能跨异步任务使用？

不要把它当成跨任务共享的撤销凭证。Token 绑定产生它的 ContextVar 和对应的上下文状态，应该在创建它的局部范围内完成 reset。

什么时候用显式 finally，什么时候用 with？

需要兼容 Python 3.14 之前版本，或希望明确看到清理动作时用显式 finally；确定运行环境支持 3.14+ 且临时范围很短时可以使用 with。