Краткий ответ

ContextVar хранит значение в контексте текущей асинхронной задачи, поэтому разные задачи могут иметь независимое состояние даже внутри одного потока. Локальная переменная потока привязана к потоку, а не к задаче, и при переключении между задачами может привести к смешению данных разных запросов.

Исторический контекст

Традиционный способ хранить контекст выполнения — локальные переменные потока, например через threading.local(). Такой подход хорошо соответствует модели, где один запрос обслуживается отдельным потоком, но плохо подходит для асинхронного кода: множество задач могут последовательно выполняться в одном потоке.

ContextVar появился как механизм контекстно-локального состояния, учитывающий переключение асинхронных задач. Он решает проблему передачи общих для текущего запроса данных без добавления явного аргумента во множество функций.

Постановка проблемы

Предположим, приложение хранит идентификатор запроса, пользователя или трассировочный идентификатор в локальном состоянии. При использовании локальной переменной потока две корутины, выполняющиеся в одном потоке, могут перезаписать одно и то же значение.

Это приводит к трудноуловимым ошибкам: лог одной операции получает идентификатор другой, политики авторизации видят чужого пользователя, а диагностические данные становятся недостоверными. Дополнительная опасность — состояние может остаться установленным после завершения запроса, если его не восстановить явно.

Подробное решение

ContextVar связывает значение с текущим контекстом выполнения. В асинхронной программе контекст обычно переносится вместе с задачей, поэтому при переключении между задачами каждая из них снова видит собственное значение переменной.

import asyncio
from contextvars import ContextVar

request_id = ContextVar("request_id", default=None)

async def handle(value):
    token = request_id.set(value)
    try:
        await asyncio.sleep(0)
        print(request_id.get())
    finally:
        request_id.reset(token)

asyncio.run(asyncio.gather(handle("A"), handle("B")))

В примере обе корутины могут выполняться в одном потоке, но вывод каждой содержит собственный идентификатор. set() возвращает токен, с помощью которого значение восстанавливают через reset(); это особенно важно при вложенном изменении контекста и при повторном использовании одного выполнения.

Локальная переменная потока не различает такие задачи: для неё обе корутины находятся в одном потоке и используют одно хранилище. Поэтому threading.local() допустима для действительно потокового состояния, но не должна использоваться как универсальное хранилище контекста запроса в асинхронном приложении.

ContextVar не делает произвольные объекты потокобезопасными и не заменяет синхронизацию общего изменяемого ресурса. Кроме того, изменение объекта, находящегося внутри значения переменной, остаётся обычным изменением этого объекта; изоляция относится к привязанному значению, а не автоматически к его внутреннему содержимому.

Ситуация из практики

Сервис добавляет request_id в логи. Первый вариант использует локальное состояние потока: он прост и привычен, но при обслуживании нескольких асинхронных запросов одним worker-потоком один запрос может изменить значение, пока другой ожидает завершения операции ввода-вывода.

Передача request_id явным параметром надёжна и прозрачна, но требует менять сигнатуры большого числа функций. Локальная переменная потока сохраняет удобство неявного доступа, однако не соответствует границам асинхронных задач.

Выбран ContextVar с установкой значения на границе обработки запроса и восстановлением по токену в finally. Это сохраняет удобный доступ к контексту, изолирует параллельные задачи и предотвращает утечку значения в окружающий код. Для фоновых задач, создаваемых отдельно от запроса, контекст следует проверять особенно внимательно: нельзя предполагать, что такая задача должна автоматически наследовать контекст родителя.

Что кандидаты часто упускают

1. Что произойдёт, если не вызвать `reset()` после `set()`?

Значение останется установленным в текущем контексте до последующего изменения или завершения его жизненного цикла. В долгоживущем коде это может привести к тому, что последующие операции получат устаревший идентификатор или другой контекстный признак.

reset(token) восстанавливает предыдущее значение, включая корректную работу вложенных установок. Поэтому стандартный шаблон — сохранить токен, выполнить работу в try и восстановить состояние в finally.

2. Изолирует ли ContextVar изменяемый объект, помещённый в него?

Нет. Если в переменную положить один общий список или словарь, разные задачи могут ссылаться на тот же объект и изменять его содержимое.

Изолируются привязки переменной к контекстам, а не копируются автоматически все объекты внутри значения. Для независимого состояния нужно создавать отдельный объект для каждого контекста либо использовать подходящую синхронизацию.

3. Всегда ли новая асинхронная задача получает пустой контекст?

Нет. При стандартном создании задачи контекст обычно копируется из контекста, в котором задача создаётся. Это означает, что задача может унаследовать значения родителя, но последующие изменения её контекста не должны рассматриваться как изменение контекста родительской задачи.

Для фоновых задач важно осознанно выбирать контекст: наследование может быть полезным для трассировки запроса, но опасным для данных, которые не должны переживать границу запроса. При необходимости задачу создают с явно выбранным контекстом или очищают нежелательные значения.

Почему для состояния текущего запроса в асинхронном Python коде используют ContextVar, а не локальную перем...