Интеграция с библиотеками¶

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

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

Архитектурная позиция QTasks¶

QTasks не стремится быть «центром мира» приложения. Он может выступать:

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

Это достигается за счёт минимального количества глобального состояния и строгой изоляции компонентов.

Минимизация глобального состояния¶

В архитектуре QTasks глобальные переменные используются осознанно и в ограниченном объёме.

Глобальная ссылка на приложение¶

Основная точка входа по умолчанию создаётся через:

app = QueueTasks()

При инициализации экземпляра приложения вызывается self._set_state(), в результате чего:

глобальная ссылка на приложение сохраняется в qtasks._state.app_main;
она используется как значение по умолчанию в тех местах, где явная ссылка на приложение отсутствует.

Важно отметить, что наличие app_main не является обязательным условием работы системы.

Во всех случаях, где это возможно:

задачи, объявленные через @app.task, получают ссылку на конкретный экземпляр app напрямую;
роутеры (A)syncRouter, подключённые через app.include_router(router), также используют явную ссылку.

Глобальная ссылка используется только в сценариях, где экземпляр приложения не был передан явно, например при использовании @shared_task().

Глобальный логгер¶

Помимо ссылки на приложение, в QTasks существует единая точка агрегации логирования.

При инициализации приложения в _set_state() также может быть создан глобальный логгер:

он сохраняется в qtasks._state.logger_main;
базируется на классе qtasks.logs.Logger.

По умолчанию логгер инициализируется следующим образом:

Logger(
    name=app.name,
    subname="QueueTasks",
    default_level=app.config.logs_default_level_server,
    format=app.config.logs_format,
)

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

Таким образом, логирование может быть:

централизованным — при наличии logger_main;
локальным — при отсутствии глобального логгера.

Архитектурные последствия для интеграций¶

Такой подход к глобальному состоянию даёт следующие преимущества:

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

Назначение этого раздела¶

Этот раздел закладывает архитектурную основу для всех последующих страниц, посвящённых конкретным интеграциям.

Далее будут рассмотрены:

особенности встраивания QTasks в другие фреймворки;
управление жизненным циклом приложения в сторонней среде;
типовые архитектурные паттерны интеграции.

Все они опираются на принципы, описанные на этой странице.