Первая задача: отправить письмо

Asynq первая задача начинается не с кода, а с имени: у каждой задачи есть тип — строка, по которой воркер поймёт, какой хендлер звать. Возьмите конвенцию «домен:действие» — email:welcome, report:daily, webhook:ping; она читается в дашборде и логах лучше любых комментариев. Тип объявляется константой в общем пакете tasks, который импортируют обе стороны связки: клиент кладёт задачу с этим типом, воркер регистрирует на него хендлер, и опечатка здесь равна потере письма. Сама задача — это значение asynq.Task: строка типа плюс байты данных, и конструктор asynq.NewTask принимает ровно два аргумента. Я всегда оборачиваю NewTask в функцию NewWelcomeEmailTask(userID int, email string): она прячет сериализацию, даёт типизированный вызов вместо сырых байтов и делает код постановки задачи читаемым. Ошибку Marshal возвращаем наверх — и хотя на обычных структурах она почти невозможна, привычка проверять всё, что возвращает ошибку, в Go не обсуждается. Константа вместо сырой строки окупается при переименованиях: компилятор найдёт все точки использования, тогда как опечатка в литерале живёт до первой жалобы пользователя. А префикс домена в имени типа превращает дашборд в фильтруемый список: email:, report:, webhook:* группируются глазами, без таблицы соответствий.

Обратите внимание на payload-структуру: она живёт в общем пакете не из педантизма, а потому что это контракт между двумя процессами. Клиент маршалит поля, воркер анмаршалит те же поля, и одна структура описывает обе стороны. Теги json задают имена ключей в сериализованных байтах — user_id вместо UserID читается в дашборде и в redis-cli без привычки к горбикам. Отсюда два технических следствия, о которых узнают по нулевым значениям, если пропустить. Первое: поля структуры обязаны быть экспортированными — json.Marshal молча пропускает неэкспортированные, ошибки компиляции не будет, и вы просто найдёте UserID равным нулю в воркере. Второе: json не переварит каналы и функции — Marshal вернёт UnsupportedTypeError ещё на клиенте, и это ещё один довод проверять ошибку конструктора, а не считать формальностью. В четвёртом уроке мы разберём payload во всей красе: вложенные структуры, срезы, обратную совместимость при изменении полей. Пока важно другое: данные задачи — это байты, а не живые указатели на ваши объекты. Между постановкой и выполнением письмо-задача пролежит в Redis, возможно, минуты, а возможно, и дни: в неё нельзя упаковать открытое соединение с базой или объект io.Writer, только данные, которые переживут сериализацию.

Постановка задачи — одна строка с двумя проверками. client.Enqueue(task) синхронно пишет задачу в Redis и возвращает два значения: *asynq.TaskInfo и ошибку. В info лежит всё, что стоит залогировать: ID задачи — строка, которую asynq сгенерировала сама, имя очереди, куда попала задача, и время запуска. Ошибка здесь — не формальность: Redis мог отвалиться, соединение могло разорваться, и молча потерять постановку — худший сценарий для кода, который только что обещал пользователю письмо. Без опций Enqueue кладёт задачу в очередь default с настройками по умолчанию — до 25 попыток при ошибках и запуск немедленно; обе договорённости мы будем менять опциями в следующих уроках. Клиент при этом ничего не знает о воркерах: не проверяет их доступность и не ждёт выполнения. Он сделал запись в Redis — и вернулся к своим делам. Запись в локальный Redis стоит доли миллисекунды, так что латентность ответа постановка не проедает — но и её лучше держать подальше от горячего пути: тяжёлые пакетные сценарии собирают задачи и ставят пачкой из фонового процесса. Если Enqueue вернул ошибку, у приложения есть выбор: повторить постановку пару раз с короткой паузой, переживая сетевой пик, или сразу отдать 5xx и оставить повтор пользователю. Я выбираю первое для писем и второе для платежей, где двойная постановка хуже пропавшей; как сделать повтор постановки безопасным, покажет четвёртый урок с его TaskID.

Хендлер — обычная функция с обязательной сигнатурой: func(context.Context, *asynq.Task) error. Первый аргумент — контекст, и это не пустышка, а рабочая ручка: опция Timeout при постановке ставит его дедлайн, и долгие операции внутри хендлера обязаны на отмену реагировать. Через context.WithValue сюда же добираются значения, которые вы решили не тащить в payload, — trace-id, код локали. Второй — сама задача: метод t.Payload() возвращает те самые байты, которые клиент упаковал Marshal-ом, и первым делом их надо разобрать в payload-структуру через json.Unmarshal. Возвращаемое значение — главная ручка управления: nil означает «задача выполнена», и asynq снимает её с учёта; ошибка означает «не вышло», и задача уйдёт в повтор с растущей задержкой — до тех пор, пока не кончатся попытки. Сигнатура носит разговорное имя ProcessTask — в примерах документации хендлеры часто так и называются, хотя asynq принимает любую функцию этого вида. Какие ошибки стоит повторять, а какие — приговор задаче без повтора, разберём в уроке про ошибки; пока правило простое: вернули ошибку — готовьтесь к ретраю. Хендлер при этом не обязан тащить бизнес-логику внутри себя: здоровая привычка — распаковать payload и передать работу сервисному слою, протестированному отдельно от asynq. Тогда хендлер остаётся тонкой обёрткой — разбор, вызов, ошибка наверх, — и его легко покрыть тестом без Redis.

Хендлер написан, но воркер о нём не знает: функции нужно зарегистрировать в ServeMux по строке-типу. mux.HandleFunc(tasks.TypeWelcomeEmail, handleWelcomeEmail) — и связь установлена: задача с типом email:welcome попадёт именно в эту функцию. После регистрации остаётся запустить srv.Run(mux), и цикл обработки закрутится. Порядок запуска для проверки: сначала Redis, потом воркер, потом клиент — хотя asynq прощает любой порядок, задачи просто дождутся воркера в очереди. Функция — не единственная форма хендлера: mux принимает и значение, реализующее интерфейс asynq.Handler с методом ProcessTask(context.Context, *asynq.Task) error. Структурный хендлер удобен, когда логике нужны зависимости — SMTP-клиент, база, конфиг: соберите структуру с полями при старте и зарегистрируйте её метод, и глобальные переменные не понадобятся. На один mux вешают сколько угодно типов: HandleFunc вызывается для каждого, и воркер одного процесса обслуживает и письма, и отчёты. В логах вы увидите два события: клиент напечатает ID задачи и имя очереди, воркер — строку про письмо. Между ними пройдёт меньше секунды: воркер вынимает задачи из Redis практически мгновенно. Напомню, что в этом уроке клиент и воркер живут в одном main.go — так проще всего увидеть связку целиком; в продакшене их разведут по уроку про топологию.