Фоновые задачи в веб-приложении

Минимальная связка выглядит так: в приложении создаётся один asynq.NewClient на тот же Redis, куда смотрит воркер-процесс, и хендлер внутри HTTP-запроса вызывает Enqueue. Ответ клиенту строится на TaskInfo, которую вернула постановка: info.ID — идентификатор задачи, info.State — её состояние на момент постановки. Статус ответа — 202 Accepted, а не 200 OK: код честно говорит, что запрос принят к исполнению, но результат ещё не готов. Собирать payload лучше из проверенных данных запроса, а не из сырого тела: хендлер валидирует вход, сериализует в JSON структуру и кладёт её в задачу — ровно как в четвёртом уроке. Важно, что между HTTP-ответом и исполнением нет никакой связи: клиент уходит с task_id, а узнать судьбу задачи сможет позже — через админ-ручку на Inspector из пятнадцатого урока или через собственную таблицу статусов, которую воркер обновляет после исполнения. Ошибка постановки — отдельный случай: Redis недоступен или очередь не существует, и это 5xx, потому что намерение сохранить не удалось. Правило хорошо масштабируется и по объёму: маленький проект ставит одну-две задачи из ручки, зрелый — десятки, но форма не меняется: хендлер всегда короткий, воркер всегда отдельно. Если в ручке появился HTTP-вызов к внешнему сервису, это кандидат на вынос в задачу: внешний сервис рано или поздно зависнет, и ручка зависнет вместе с ним.

Отложенность задаётся опциями постановки прямо в HTTP-хендлере — теми же, что в пятом уроке. ProcessIn(30*time.Minute) говорит «исполни не раньше, чем через полчаса»: так ставятся напоминания, повторные попытки оплаты через время, отложенная рассылка. ProcessAt(t) принимает конкретный момент времени — удобно, когда срок приходит из запроса, например «отправить отчёт к концу рабочего дня в часовом поясе клиента». Для веб-связки это особенно сильный приём, потому что таймер живёт не в приложении, а в Redis: клиент мог закрыть браузер, деплой мог перезапустить контейнеры — задача всё равно дождётся своего часа, потому что scheduled-состояние хранится в очереди, а не в памяти процесса. Никаких goroutine с time.Sleep в хендлере: спящий горутин умрёт вместе с процессом на первом деплое, а задача с ProcessIn переживёт что угодно. Комбинируйте опции свободно — ProcessIn с MaxRetry, TaskID с Queue: они складываются так же, как при обычной постановке. Практический нюанс: ProcessIn честно означает «не раньше», а не «ровно через» — задача станет pending в срок, но исполнится, когда дойдёт очередь и свободный воркер; закладывайте это в ожидания продукта и в тексты писем.

Пользователь дважды нажал «оплатить», сеть дёрнулась и мобильный клиент повторил запрос — и в обоих случаях платеж должен быть один. Обычная постановка каждый раз создаст новую задачу, поэтому для идемпотентных ручек задачу ставят с опцией asynq.TaskID(id): библиотека гарантирует, что в очереди живёт только одна задача с этим идентификатором, пока она не завершится и не будет удалена из completed. Повторная постановка с тем же ID вернёт sentinel-ошибку asynq.ErrTaskIDConflict — и это не сбой, а сигнал «такая задача уже принята». Хендлер проверяет её через errors.Is и отвечает клиенту как на успех: 200 со статусом already_accepted и тем же task_id. Повторный POST становится безопасным: первый запрос вернул 202 и запустил работу, второй — узнал, что работа уже в очереди. Такой подход дополняет уникальность из двенадцатого урока: Unique защищает от дубликатов по содержимому, TaskID — по явному идентификатору, который вы выбираете сами, чаще всего это ID заказа или платежа. Выбор идентификатора — решение архитектора: он должен быть осмысленным для бизнеса и достаточно долгим, чтобы не конфликтовать, а срок жизни совпадает с жизнью задачи в очереди, включая completed-хранение, о котором подробнее в двенадцатом уроке.

Web и воркер можно держать в одном процессе или развести. Монолитный вариант: asynq.Server запускается через Start(mux) рядом с HTTP-сервером в том же main — одним бинарем, одной конфигурацией, одним деплоем. Разделённый вариант: API-контейнер с Client и воркер-контейнер с Server общаются только через Redis. Монолит проще стартовать и отлаживать, но он связывает судьбы: тяжёлая фоновая работа делит CPU и память с ручками, а масштабировать придётся всё вместе — больше воркеров означает и больше без дела стоящих HTTP-инстансов. Разделённая топология дороже в эксплуатации — два деплоя, две конфигурации, два набора метрик, — зато воркеры масштабируются независимо: удвоение реплик воркера не трогает API, а релиз, ломающий только фоновые задачи, не отдаёт ручки. Graceful shutdown при этом одинаково важен в обоих вариантах: в монолите сигналы termination получают оба компонента сразу, в разделённом — каждый отдельно, и правила девятнадцатого урока действуют на каждый процесс свои. Практичный путь развития — начать с монолита и распасться на два процесса, когда фоновые задачи станут заметны в метриках: постановка задач при этом не меняется вообще, меняется только сборка main, потому что Client и Server общаются исключительно через Redis.

Контракт асинхронной ручки — три ответа. Первый: 202 с task_id при успешной постановке; тело минимальное — идентификатор и, при желании, время ожидания, если стоит ProcessIn. Второй: 200 с already_accepted при ErrTaskIDConflict — для клиента это тоже успех, просто работа была начата раньше. Третий: 5xx при ошибке постановки — Redis лежит или очередь не существует; клиенты и ретраи на уровне HTTP справятся с этим сами. Синхронный ответ с результатом работы из асинхронной ручки не получается: задача исполняется позже и в другом процессе, поэтому результат либо пишется в базу воркером, либо доступен через GetTaskInfo из пятнадцатого урока, либо доставляется webhook'ом. Отдельный вопрос — авторизация постановки: ручка, ставящая задачи, — это запись в вашу очередь, и защищать её нужно так же, как запись в базу; открытая ручка постановки превращается в насос чужих задач с вашими ретраями. То же касается ручки статуса: статус заказа отдаётся по правам на заказ, а не по знанию идентификатора из очереди — task_id не является паролем и в авторизации не участвует.