Компоненты: схемы данных¶

Эта страница описывает роль схем данных в архитектуре QTasks и правила их использования при взаимодействии компонентов.

Схемы данных — это основной механизм передачи информации между компонентами. Они формируют строгий, типизированный контракт, который заменяет прямой обмен объектами и состоянием выполнения.

Роль схем в архитектуре¶

Когда данные необходимо передать от одного компонента к другому, оба компонента обязаны придерживаться согласованной схемы данных.

Схемы:

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

Единственное исключение из этого правила — добавление задачи в Worker через контракт add, где данные передаются в виде параметров и преобразуются в схемы уже на стороне Worker.

Общие правила схем¶

Для всех схем данных в QTasks действуют единые архитектурные правила.

1. Строгая структурированность¶

Каждая схема должна быть dataclass-подобной структурой с явно заданными полями и типами. Это обеспечивает:

совместимость с mypy и другими инструментами типизации;
предсказуемость структуры данных;
однозначность контрактов между компонентами.

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

2. Сборка схем на стороне отправителя¶

Формирование схемы всегда происходит в компоненте-отправителе.

Это правило гарантирует, что принимающий компонент:

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

Исключение — Worker (add), который принимает параметры задачи и самостоятельно формирует соответствующие схемы.

3. Стабильность схем¶

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

Ключевые схемы QTasks¶

Ниже перечислены основные схемы, используемые в архитектуре QTasks, и их назначение.

QueueConfig¶

Схема конфигурации, используемая всеми компонентами, начиная с QueueTasks. Определяет базовые параметры работы системы и передаётся при инициализации компонентов.

Task¶

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

BaseTaskStatusSchema¶

Базовая схема статуса задачи. Используется для представления состояния задачи на отдельных этапах выполнения.

Производные схемы:

TaskStatusNewSchema;
TaskStatusProcessSchema;
TaskStatusSuccessSchema;
TaskStatusErrorSchema;
TaskStatusCancelSchema.

Основной потребитель этих схем — компонент Storage.

TaskExecSchema¶

Схема, содержащая информацию о задаче и функции её выполнения. Используется преимущественно Worker при подготовке задачи к исполнению и передаче в TaskExecutor.

TaskPrioritySchema¶

Схема добавления задачи в Worker. Хранит входные данные, переданные через add, а также приоритет выполнения.

Эта схема является точкой входа задачи в очередь выполнения Worker.

BaseTaskCls¶

Схема предварительно собранной задачи, представляющая альтернативный способ создания задачи.

Производные варианты:

AsyncTaskCls;
SyncTaskCls.

Такие схемы позволяют работать с задачей как с объектом вызова, а не через прямой вызов add_task.

InitsExecSchema¶

Схема для ивентовых функций, используемых в системе событий QTasks.

Пример использования — обработчики вида:

@app.events.on.worker_running

GlobalConfigSchema¶

Основная схема компонента GlobalConfig, предназначенного для хранения и распространения глобальных параметров.

По умолчанию реализация использует Redis как сервер хранения.

ArgMeta¶

Схема метаданных аргументов задачи.

Хранит:

имена аргументов;
значения;
позицию или ключ;
аннотации типов и вспомогательную информацию.

Используется преимущественно в TaskExecutor и плагинах, которым необходимо понимать структуру аргументов задачи.

Для плагинов ArgMeta передаётся как параметр в соответствующих триггерах.

Архитектурные инварианты¶

компоненты обмениваются только схемами данных;
схемы не содержат логики выполнения;
формирование схем происходит до передачи данных;
стабильность схем критична для совместимости компонентов и плагинов.

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