Payload и task ID: данные задачи

Asynq payload устроен предельно честно: второй аргумент asynq.NewTask — это []byte, и библиотека не делает предположений о его содержимом. Задача без данных передаёт nil; задача с данными чаще всего несёт JSON, который клиент собрал через json.Marshal из структуры с тегами. Стандарт сериализации не навязан, но JSON стал дефолтом по трём причинам: он читается в дашборде и redis-cli, выдерживает эволюцию полей и не требует ничего сверх encoding/json. Практика, которая никогда не подводит: рядом с конструктором задачи жить декодер — функция, принимающая *asynq.Task и возвращающая распакованную структуру с ошибкой. Конструктор и декодер образуют пару, которая прячет сериализацию от обеих сторон: клиент не знает про байты, воркер не знает про структуру постановки. Для задач без параметров это всё тоже работает — просто структура пустая, а теги не нужны. Задача в очереди — это тип и байты, больше ничего: t.Payload() у воркера вернёт ровно те же байты, что вернул Marshal у клиента, и никакая типизация не переносится между процессами сама — только через сериализацию.

Пакет tasks из предыдущего урока здесь работает на полную: клиент и воркер импортируют одни и те же структуры, и расхождение становится невозможным на уровне компилятора. Почему это принципиально, лучше всего объясняет rolling-деплой: воркеры старой версии ещё крутятся, клиент уже поставил задачи новым форматом. Если структуры общие и поля только добавлялись, старый воркер молча пропустит незнакомые ключи и выполнит задачу по старым правилам. Если же структуры дублировались в двух репозиториях, задача разваливается: клиент маршалит одно, воркер ждёт другое, и на дашборде растёт колонка ошибок Unmarshal. Отсюда рабочее правило: тип задачи, payload-структура, конструктор и декодер переезжают вместе; если клиент и воркер в разных сервисах, общий пакет выносят в отдельный модуль. Теги json — часть этого контракта, и их изменение проверяется тестом, как публичный API, потому что это он и есть. На практике общий пакет тянет за собой дисциплину: новое поле добавляется с omitempty и старый воркер его молча пропустит, а вот смена типа существующего поля — уже новый контракт, требующий согласованного релиза обеих сторон.

По умолчанию asynq генерирует ID задачи сам — непрозрачную строку, которая хороша для логов и дашборда, но не несёт бизнес-смысла. Опция asynq.TaskID("...") позволяет задать собственный идентификатор: строку, которую придумали вы. Главное свойство: ID уникален среди живых задач — тех, что лежат в pending, active, scheduled или retry. Повторная постановка с тем же ID, пока первая задача жива, вернёт ошибку ErrTaskIDConflict. Ошибку эту проверяют через errors.Is(err, asynq.ErrTaskIDConflict) и обрабатывают как штатную ветку дедупликации: первая задача уже живёт, ставить заново не нужно, — но залогировать конфликт стоит, чтобы отличать задуманную защиту от случайной коллизии ID. Это превращает TaskID в примитивный инструмент дедупликации: ID вида report-100500 гарантирует, что двойной клик в интерфейсе, повторный вебхук или два воркера, обрабатывающих одно событие, не поставят отчёт дважды. Важная оговорка: после завершения задачи её ID освобождается, и TaskID — не вечный замок, а защита на время жизни задачи. Для «не ставить одинаковые задачи в принципе» существует отдельная опция Unique со сроком годности — ей посвящён урок про уникальные задачи.

TaskInfo — это отчёт о постановке, а не о выполнении, и его полезно понимать поле за полем. ID — строка-идентификатор: ваша, если задали TaskID, или сгенерированная asynq; собственный ID и TaskInfo.ID при этом совпадают, и эта проверка бесплатна. Queue — куда задача попала фактически, а не куда вы надеялись. MaxRetry — число попыток, зафиксированное опцией или дефолтом: сразу видно, что осталось от стандартных 25 после ваших настроек. Retried показывает, сколько попыток уже сделано: после постановки он нулевой и растёт по мере жизни задачи, если читать её через Inspector; рост Retried при живой задаче — самый дешёвый способ увидеть, что хендлер падает системно, а не разово. LastErr и LastFailedAt сообщают последнюю ошибку и время сбоя — по ним воркерные логи связываются с задачей без grep по миллионам строк. Есть и State — текущее состояние вроде pending, scheduled или active; словарь состояний пригодится в уроках про Inspector и asynqmon. Логировать info при постановке я приучил всю команду: три поля в логе постановки стоят дешевле часа расследований «а поставилась ли задача вообще». Единственное, чего TaskInfo не умеет, — предсказывать будущее: успешность выполнения в нём не появится, потому что постановка об исполнении не знает ничего.

Вариативные опции — второй способ говорить с asynq после payload: задача описывает «что делать», опции описывают «как обещаем». MaxRetry(n) задаёт число попыток: по умолчанию их 25, что для письма после невалидного адреса — расточительство, а MaxRetry(3) или даже 0 обрезает лишнее; весь механизм повторов разбирается в шестом уроке. Queue(name) отправляет задачу в именованную очередь — critical, default, low; воркер читает их с весами, о которых рассказывает урок про очереди и приоритеты. ProcessIn(d) и ProcessAt(t) откладывают запуск — им посвящён следующий, пятый урок. Unique(dur) делает постановку уникальной на срок — тема урока про уникальные задачи. Timeout и Deadline ограничивают жизнь хендлера, Retention удерживает завершённую задачу в дашборде. Опции комбинируются свободно, а их перечисление в коде читается как обещание: «три попытки, в очередь reports, отложить на полчаса». Порядок опций в вызове не имеет значения — asynq собирает их в вариантный срез и применяет по смыслу, поэтому читайте перечисление как список характеристик, а не как конвейер шагов.