Установка: клиент, воркер и Redis

Asynq установка в проект начинается с модуля: если в папке ещё нет go.mod, выполните go mod init, затем go get github.com/hibiken/asynq — один импорт, без cgo и системных пакетов. Команда зафиксирует версию в go.mod и go.sum, и обе стороны связки будут собираться ровно на ней; обновлять библиотеку в клиенте и воркере лучше одним коммитом, чтобы представления о настройках не разъехались. Дальше вопрос организации: у вас будет минимум две точки входа. Я держу три пакета: pkg/tasks — общие типы задач и payload-структуры, cmd/client — API-часть, которая только ставит задачи, cmd/worker — процесс с хендлерами. Из одного модуля собираются два бинарника: go build ./cmd/client и go build ./cmd/worker. Разделение выглядит как бюрократия ровно до первого продакшена: клиенту не нужны SMTP-библиотеки и доступ к внутренним системам, воркеру не нужны роутеры API — у каждой половины свой минимум зависимостей и свой профиль нагрузки. Отдельный бонус: воркер можно гонять на слабой машине, а API — на сильной, потому что разным профилям нагрузки нужен разный железный бюджет. Общий пакет задач гарантирует, что клиент и воркер не разъедутся в представлениях о данных: тип один, импортируют его обе стороны. Если вы пишете монолит, схема легко сворачивается обратно: клиент и воркер могут жить в одном main.go, и в следующем уроке мы именно так и сделаем для простоты.

Asynq redis подключение описывается значением RedisClientOpt — причём это тот же тип, который принимают клиент, воркер и Inspector, поэтому конфигурация задаётся один раз и разъехаться не может. Главное поле — Addr: адрес вида host:port, по умолчанию 127.0.0.1:6379, как у стандартного Redis без настроек. Дальше по необходимости: DB выбирает логическую базу (по умолчанию нулевую), Username и Password — аутентификацию, которая в Redis 6 и новее живёт в ACL. Для TLS есть поле TLSConfig со стандартной конфигурацией crypto/tls — понадобится, если Redis закрыт шифрованием. Пул соединений asynq создаёт сам: PoolSize по умолчанию считается от числа CPU, и трогать его стоит только под измеренной нагрузкой. Если вы настраивали клиент go-redis, всё покажется знакомым: asynq использует его внутри, и семантика полей та же: если Redis для вас в новинку, курс по go-redis закрыет эту дыру параллельно с третьим уроком. Разная топология Redis тоже ложится на тот же opt: для Sentinel существует RedisFailoverClientOpt с MasterName и SentinelAddrs, для кластера — RedisClusterClientOpt с Addrs; все три реализуют один интерфейс RedisConnOpt, поэтому клиент и воркер не знают о топологии ничего сверх этого значения. Соединение при этом ленивое — первый контакт с Redis случится на первой операции, а не в конструкторе. Поэтому клиентский main из примера выше запускается мгновенно даже без Redis — это нормальное поведение, а не лазейка: проверяйте ошибки там, где реальная работа.

Воркер собирается конструктором asynq.NewServer: первый аргумент — те же RedisClientOpt, второй — Config, единственная структура настроек сервера. Главная настройка — Concurrency: сколько горутин одновременно исполняют хендлеры. По умолчанию это число CPU машины — разумный старт для тяжёлой вычислительной работы, но если задачи в основном ждут сеть, смело ставьте больше. Вторая важная группа настроек — Queues: карта «имя очереди — вес», о которой подробно поговорим в седьмом уроке; пока достаточно дефолтной очереди default, которая создаётся сама. Имена очередей — просто строки, но лучше объявить их константами рядом с типами задач: опечатка в имени молча создаст вторую очередь, которую воркер никогда не читает, и задачи будут ждать в ней вечно. ServeMux — маршрутизатор: он связывает строку-тип задачи с вашей функцией, работает как http.ServeMux из стандартной библиотеки и в этом уроке остаётся пустым. Метод Run запускает бесконечный цикл воркера: он подписан на SIGTERM и SIGINT, а по получении сигнала аккуратно дожидается текущих задач — поведение остановки разбираем в уроке про graceful shutdown. Ошибка Run означает, что сервер прервался нештатно, и в main её логируют через log.Fatal.

Клиент и воркер могут жить в одном процессе или в двух — asynq не делает различий, потому что оба работают через один и тот же Redis. Для разработки удобнее всего один main.go: поставили задачу и тут же её исполнили, цикл обратной связи занимает секунды. В продакшене схема почти всегда разделяется: API-сервис только ставит задачи, воркеры масштабируются отдельно и переживают пики без участия веб-трафика. У разделения есть приятный побочный эффект: перезапуск API больше не роняет выполняющиеся задачи, а рестарт воркеров не трогает приём трафика. Практическое правило, к которому я пришёл на нескольких проектах: начинайте с одного процесса, разделяйте, когда воркеры впервые съедят ресурс API — обычно это совпадает с первым отчётом на миллион строк. Отдельный вопрос — версии: клиент и воркер в одном бинаре обновляются синхронно, а в двух деплоях — по очереди, и это плюс для отката, но требует обратной совместимости задач, о которой поговорим в четвёртом уроке. Кстати, о деплое: два процесса — это и два потока логов, и два набора метрик; заложите мониторинг сразу, а не после первого «воркер молчит». И в обеих топологиях используйте одно значение RedisClientOpt из конфига: разделённые конфигурации клиента и воркера — источник незаметных рассинхронов, который мы разбираем в предупреждении ниже.

Redis поднимается одной командой Docker: docker run --name asynq-redis -p 6379:6379 -d redis:7. Контейнер отдаёт стандартный порт 6379, пароль не установлен — для локальной разработки ровно то, что нужно. Проверка связи живёт в самом контейнере: docker exec -it asynq-redis redis-cli ping должен вернуть PONG — это ваша первая операция с Redis, дальше их будет много. В compose-мире той же цели служит сервис redis с образом redis:7: воркер и клиент будут ходить на хост redis, и этот адрес должен попасть в их общий конфиг. Пройдитесь по чек-листу ниже; когда все шесть пунктов зелёные, окружение готово до конца курса. Остановить и удалить контейнер можно docker stop и docker rm, но не спешите глушить его между уроками: задачи и расписание живут именно там. Для compose-проектов удобно сразу закоммитить сервис redis в docker-compose.yml — подъём окружения перестаёт быть ритуалом из команд и становится частью первого запуска проекта.