ServeMux: маршрутизация задач

Asynq servemux создаётся конструктором asynq.NewServeMux() и передаётся в srv.Run(mux) — это и есть тот хендлер, который сервер вызывает для каждой задачи. Регистрация идёт двумя способами. HandleFunc принимает функцию с сигнатурой хендлера: mux.HandleFunc("email:welcome", handleWelcomeEmail) — самый короткий путь для простых случаев. Handle принимает значение, реализующее интерфейс asynq.Handler: структурный хендлер с зависимостями — базой, mailer-ом, конфигом — регистрируется именно так. Паттерн регистрации — тот же тип задачи, что вы передаёте в NewTask: строка вроде email:welcome, которую мы с четвёртого урока держим в константах общего пакета. Две паники стоят запомнить: повторная регистрация того же паттерна валит процесс при старте с «multiple registrations», а пустой паттерн — при любой попытке зарегистрировать пустую строку. Обе паники — друзья: конфликт паттернов лучше поймать на деплое, чем в три часа ночи. Для полноты: ServeMux потокобезопасен — регистрации и поиск идут под мьютексом, — а метод Handler(t) вернёт пару «хендлер, паттерн» для любой задачи, если однажды понадобится отладить совпадение руками. В повседневном коде он не нужен: mux собирают при старте и дальше он только диспетчеризует.

Правило выбора хендлера состоит из двух шагов. Сначала mux ищет точное совпадение типа задачи с зарегистрированным паттерном — словарный поиск за константное время. Если точного нет, включается префиксное правило: среди всех паттернов, являющихся началом типа задачи, выбирается самый длинный. Зарегистрированы email и email:welcome — задача email:welcome уходит точному хендлеру, задача email:digest попадает префиксному email. Это та же логика, что у net/http до явных wildcard-ов: длинный паттерн всегда перекрывает короткий, порядок регистрации не важен. Механически внутри паттерны хранятся отсортированными по длине, и префиксный поиск идёт от самого длинного к короткому, останавливаясь на первом совпадении, — поэтому «самый длинный» здесь не метафора, а буквально первый в списке. Полезно знать границу: префикс — это строковое начало, а не сегменты через двоеточие. Паттерн email поймает и email:digest, и email-welcome, и emailextra — asynq сравнивает начало строки без правил про разделители. Поэтому конвенция с двоеточием — дисциплина команды, а не механика библиотеки: держите иерархию типов честной, и префиксные регистрации будут означать то, что вы имеете в виду.

Если ни точного, ни префиксного совпадения не нашлось, задачу получает NotFoundHandler — встроенный хендлер, который возвращает ошибку, оборачивающую asynq.ErrHandlerNotFound, с типом задачи в сообщении. Дальше включается уже знакомая механика шестого урока: ошибка считается сбоем, задача идёт в повторы с экспонентой и, исчерпав попытки, оседает в архиве с этой ошибкой. Реальный сценарий, где это случается: клиент и воркер деплоятся раздельно, клиент уехал вперёд и начал ставить задачи нового типа, а воркеры ещё его не знают. Симптом заметный: в архиве оседают задачи с ErrHandlerNotFound при здоровом Redis и живых воркерах. Разбору помогает то, что в текст ошибки подставлен тип задачи: в LastErr архива будет строка вида handler not found for task "report:new" — сразу ясно, какая константа доехала до воркера раньше него. Лечение процессное, а не кодовое: типы задач появляются в общем пакете констант, воркеры катятся раньше клиентов или вместе с ними, и постановка нового типа включается фича-флагом после раскатки. Разница между «воркеры раньше клиентов» и «фича-флаг после раскатки» — в цене: первый вариант ничего не стоит, кроме дисциплины пайплайна, второй спасает, когда раскатки независимы. Проверка соответствия констант и паттернов — хороший юнит-тест, о котором подробнее говорит двадцать второй урок.

Middleware для задач — функция вида func(Handler) Handler: она получает следующий хендлер и возвращает обёртку, которая делает что-то до и после вызова. Регистрируются обёртки через mux.Use(logging, metrics) — сколько хотите, применяются в порядке записи. Из контекста задачи обёртки достают GetTaskID, GetQueueName и GetRetryCount — так одна строка лога получает идентификатор, очередь и номер попытки без правок хендлеров. Держите middleware лёгким: он живёт в горячем пути каждой задачи, и тяжёлая логика там умножается на весь поток. Важное следствие: middleware оборачивают каждый хендлер, найденный по паттерну, включая NotFoundHandler, — поэтому общий код пишется один раз, а не шесть раз по хендлерам. Содержимое обёртки — всё, что не относится к конкретной задаче: логирование типа и длительности, метрики по исходам, восстановление после паники, обогащение контекста. Если вы писали цепочки middleware в Gin, механика покажется родной — та же идея обёртки вокруг следующего хендлера, только вместо запроса и ответа здесь задача и ошибка. Единственная привычка, которую придётся перебороть: у задачи нет ответа с кодом — исход выражается ошибкой, и middleware-логика строится вокруг значения, которое вернул хендлер.

Весь механизм держится на одном интерфейсе: type Handler interface { ProcessTask(context.Context, *asynq.Task) error }. Функции подходят благодаря адаптеру HandlerFunc — поэтому HandleFunc и Handle в конечном счёте делают одно и то же. Но структурный хендлер — это не синтаксическая игра: у него есть поля с зависимостями, и одна такая структура обслуживает все постановки своего типа, без замыканий на глобальные переменные. Конструктор принимает базу, mailer, конфиг; mux.Handle("report:daily", reportHandler) регистрирует готовое значение. Только помните: одна структура обслуживает все параллельные задачи своего типа — ProcessTask вызывается одновременно из нескольких горутин, и изменяемые поля без синхронизации станут гонкой. Состояние держите в зависимостях — базе, кэше, конфиге, — а не в самом хендлере. Такой хендлер тривиально тестируется: подставьте фейковые зависимости и вызовите ProcessTask руками. Отдельный вопрос — как доставить зависимости в контекст каждой задачи, если вы предпочитаете контекстный стиль: это тема семнадцатого урока, где сравниваются структурные хендлеры и обёртки с BaseContext. Мой ориентир простой: пока зависимостей меньше трёх, структурный хендлер выигрывает у контекстной магии читаемостью стектрейсов.