Workers¶
Описание секции workers для фоновых воркеров.
Секция workers¶
Конфигурация фоновых воркеров.
workers:
- name: notification_bot
generator_type: telegram
- name: background_processor
generator_type: daemon
Поля¶
| Поле | Обязательно | Описание |
|---|---|---|
name |
Да | Имя воркера |
generator_type |
Да | Тип генератора: telegram или daemon |
generator_template |
Нет | Имя кастомного шаблона |
Типы воркеров¶
Telegram Bot¶
Telegram бот с поддержкой webhooks и polling.
Генерируемые обработчики¶
| Событие | Handler | Назначение |
|---|---|---|
| PreCheckoutQuery | PreCheckout |
Валидация платежа |
| SuccessfulPayment | Purchase |
Обработка платежа |
| CallbackQuery | CallbackQuery |
Callback от кнопок |
| Message | TextMessage |
Обработка текста/команд |
Генерируемая структура¶
internal/app/{app}/worker/telegram/{worker_name}/
├── router.go # Маршрутизация событий
├── handler/
│ └── handler.go # Обработчики (ваш код)
└── commands/
└── commands.go # Команды бота
Точки расширения: customize()¶
Сгенерированный воркер правится только ниже маркера «add your code after this
message», но кое-что проекту нужно поменять внутри сгенерированного Run(), роутера
и реестра команд. Всё это делается из одного места — метода customize(), который
Create() зовёт на свежесконструированном воркере, до Init и Run.
По умолчанию customize() промотирован из встроенного EmptyCustomizer и ничего не
делает. Проект объявляет свой — метод на *Worker перекрывает промотированный:
// internal/app/worker/telegrambot/dispatch.go — ваш файл в пакете воркера
func (w *Worker) customize() {
// Свои команды — в реестр воркера
w.AddCommands(
telegram.Cmd{
Name: CmdHelp,
Private: true,
Handler: func(ctx context.Context, h any, params string) (telegram.Response, error) {
return h.(*handler.Handler).Help(ctx, params)
},
},
)
// Хуки пакета — здесь же
updateHandler = (*Worker).dispatchUpdate
updateHandlerIdle = updatesIdle
unknownCommandHandler = func(ctx context.Context, w *Worker, rd telegram.RequestData) {
w.clearStaleDialogState(ctx, rd.Actor.ID)
}
}
Файл может быть и своим файлом пакета, и секцией ниже disclaimer-маркера в
psg_telegram_gen.go — regenerate эту правку не трогает.
Команды. Реестр команд — поле воркера (w.cmds), а не package-global
cmdMaps, наполняемый из init(): порядок инициализации пакетов на него не влияет,
и два воркера в одном процессе не делят один набор команд. Команды генератора
(generatedCommands() в psg_const_gen.go) Create() добавляет первыми, затем
зовёт customize() — команда проекта с тем же Name перекрывает сгенерированную.
Хуки пакета. Переназначаются из customize(), не из init(): в сгенерированных
проектах init() запрещён линтером (gochecknoinits).
| Хук | По умолчанию | Зачем переназначать |
|---|---|---|
updateHandler = (*Worker).handleUpdate |
лог апдейта, JobStarter, разбор его ошибок — апдейты строго по одному |
разложить апдейты по очередям (например, по автору), чтобы одна долгая команда не держала всех пользователей |
updateHandlerIdle = func() bool { return true } |
GracefulStop ждёт только пустой канал апдейтов |
дождаться, пока переназначенный обработчик закончит начатое |
unknownCommandHandler = func(ctx, w, rd) {} |
неизвестная команда только логируется | сбросить состояние диалога пользователя, чтобы старая кнопка не оставила его на полушаге |
Обработчик по умолчанию пишет в лог апдейт целиком; если в сообщениях бота бывают
секреты (токены, пароли), переназначенный обработчик должен логировать только updateID.
JobStarter для неподдержанных типов апдейта пишет в лог только updateID и тип.
Проекты, зарегистрированные до появления
customize(), наполнялиcmdMapsиз своегоinit(). Миграция — в DEPRECATION.md.
Daemon¶
Фоновый демон для периодических задач.
Генерируемая структура¶
internal/app/{app}/worker/daemon/{worker_name}/
├── worker.go # Основной воркер
└── handler/
└── handler.go # Логика обработки (ваш код)
Подключение воркеров к приложению¶
Воркеры подключаются через секцию applications:
workers:
- name: notification_bot
generator_type: telegram
- name: background_processor
generator_type: daemon
applications:
# Выделенный воркер instance
- name: worker
workers: [notification_bot, background_processor]
transport: [sys] # Системные endpoints для метрик
# Или комбинированное приложение
- name: monolith
transport: [api, sys]
workers: [notification_bot]
Жизненный цикл воркера¶
┌────────────────────────────────────────────┐
│ ИНИЦИАЛИЗАЦИЯ │
│ 1. Создание воркера │
│ 2. Инициализация зависимостей │
└────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ ЗАПУСК │
│ 1. Запуск в отдельной горутине │
│ 2. Telegram: подключение к API │
│ 3. Daemon: запуск цикла обработки │
└────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ РАБОТА │
│ - Telegram: обработка событий от бота │
│ - Daemon: выполнение периодических задач │
└────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────┐
│ ЗАВЕРШЕНИЕ │
│ 1. Graceful shutdown │
│ 2. Завершение текущих операций │
│ 3. Освобождение ресурсов │
└────────────────────────────────────────────┘
Конфигурация через OnlineConf¶
Telegram Bot¶
| Путь | Описание |
|---|---|
{service}/worker/telegram/{name}/token |
Bot token |
{service}/worker/telegram/{name}/webhook_url |
Webhook URL (опционально) |
Daemon¶
| Путь | Описание |
|---|---|
{service}/worker/daemon/{name}/interval |
Интервал выполнения |
{service}/worker/daemon/{name}/enabled |
Включен/выключен |
Конфигурация таймеров daemon worker через переменные окружения¶
Два таймера внутреннего цикла daemon worker'а можно переопределить через env vars
(полезно для goat-тестов и проектов с use_envs: true). Если переменная не задана
или не парсится, используется дефолт.
| Env var | Дефолт | Описание |
|---|---|---|
WORKER_{NAME}_NEW_CYCLE_TIMEOUT |
10s |
Пауза между итерациями цикла, когда GetTasks вернул nil |
WORKER_{NAME}_ERROR_TIMEOUT |
10s |
Пауза после ошибки в GetTasks |
{NAME} — имя воркера в верхнем регистре. Значение должно парситься через
time.ParseDuration (например, 500ms, 1m30s).
Пример: для воркера с именем supervisor ускорить goat-тесты можно так:
Пример полной конфигурации¶
main:
name: notification-service
logger: zerolog
git:
repo: github.com/myorg/notification-service
module_path: github.com/myorg/notification-service
rest:
- name: sys
generator_type: template
generator_template: sys
port: 9090
version: v1
workers:
- name: telegram_bot
generator_type: telegram
- name: email_sender
generator_type: daemon
drivers:
- name: telegram
import: pkg/drivers/telegram
package: telegram
obj_name: TelegramDriver
applications:
- name: notifier
workers: [telegram_bot, email_sender]
transport: [sys]
driver: [telegram]