Уникальные задачи: Unique

Asynq Unique — опция постановки: client.Enqueue(task, asynq.Unique(10*time.Minute)) ставит задачу, только если её ещё нет, и держит замок уникальности десять минут. Повторная постановка той же задачи в течение TTL вернёт ошибку ErrDuplicateTask — её проверяют через errors.Is, как любую сентинелл-ошибку. Документация формулирует гарантию так: задача уникальна в пределах заданного TTL, и повторная постановка становится возможна после успешной обработки или после истечения замка. TTL задаётся duration и имеет нижнюю границу: меньше секунды постановка не примет — Enqueue вернёт ошибку «Unique TTL cannot be less than 1s» ещё до общения с Redis. Важно понимать, что гарантирует опция, а что нет: Unique защищает постановку, но не заменяет идемпотентность хендлера — задача, поставленная единожды, всё равно может быть исполнена повторно при ретрае после сбоя. Поэтому Unique закрывает дубликаты на входе, а идемпотентность из восемнадцатого урока — повторы на выходе; взрослые системы используют обе скобки. Сравнение с базой проясняет место опции: уникальный индекс защищает данные, Unique защищает постановки. Задача «начислить бонус» может быть уникальной в очереди и при этом начисляться трижды тремя разными задачами с разным payload. Ориентируйтесь на вопрос «может ли быть дважды одна и та же работа», а не «может ли быть дважды один эффект».

Ключ уникальности asynq собирает из трёх свойств: тип задачи, payload и имя очереди. Одна и та же по смыслу задача в разных очередях — две независимые уникальности; то же верно для разного payload. Отсюда главное требование к payload: он должен быть каноничным. Лишний time.Now() в структуре делает каждую постановку уникальной — замок честно защищает «задачу с этой секундой», а вы думали, что защищаете «напоминание про запись 42». Собирайте payload из бизнес-полей, даты нормализуйте до дня или часа, слайсы сортируйте перед Marshal, если порядок может гулять. Имя очереди в ключе работает на вас: окружения и тенанты, разнесённые по очередям из седьмого урока, не мешают друг другу ставить одинаковые задачи. Уникальность совместима и с отложенной постановкой, и с группами из десятого урока — замок создаётся тем же механизмом. Единственное исключение — batch-постановка BatchEnqueueContext: уникальные задачи в ней не поддерживаются, и каждая такая задача получает ошибку ещё до Redis — об этом документация говорит прямо. Деталь, которая спасает при отладке: сериализация детерминирована для одного и того же типа структуры — порядок полей фиксирован объявлением, а для карт json.Marshal сортирует ключи. Ломают каноничность обычно time.Time с наносекундами, float-суммы и слайсы в гуляющем порядке: нормализуйте их до постановки, и ключ станет предсказуемым.

Уникальные задачи go держат замок с момента постановки, и у TTL есть два соседа по времени, которые легко забыть. Первый — жизнь самой задачи: TTL обязан покрывать всё существование постановки, включая очередь ожидания и ретраи. Замок живёт фиксированный срок и не продлевается ретраями: если задача с Unique(5*time.Minute) зависла в retry на полчаса, замок истечёт раньше, чем задача завершится, — и дубликат спокойно поставится. Считайте TTL сверху: максимум ожидания в очереди плюс все ретраи с паузами плюс запас. Второй сосед — момент обработки: при успешном завершении asynq снимает замок, если он всё ещё принадлежит этой задаче, и следующую такую задачу можно ставить сразу, не дожидаясь конца TTL. При неудаче замок остаётся при задаче и живёт до конца TTL — повторная постановка в это время получит ErrDuplicateTask, даже если исходная лежит в архиве. Эта асимметрия — «успех снимает, неудача держит» — и есть то, что защищает от двойной работы после сбоя. Отсюда же цена ошибиться в обе стороны: слишком короткий TTL открывает дверь дубликатам, слишком длинный — запирает очередь, если легальная повторная постановка должна случиться раньше. Когда повтор по бизнесу возможен до конца TTL, Unique не подходит — берите TaskID или проверку в хендлере.

В арсенале два механизма защиты от повторов, и они решают разные вопросы. Unique — содержательная защита: ключ собирается автоматически из типа, payload и очереди, и дубликат ловится даже тогда, когда вы не знаете заранее, каким будет идентификатор. TaskID из четвёртого урока — явная защита: вы сами придумываете идентификатор, например reminder:42:2025-06-01, и конфликт вернёт ErrTaskIDConflict. Явный ID сильнее в двух случаях. Первый — идемпотентность по бизнес-ключу: payload может отличаться (обновилось время приёма), а повтор всё равно нужно отсечь, — содержательный ключ уникальности здесь бессилен, потому что изменился payload. Второй — детерминированные идентификаторы в ретраях внешнего мира: вебхук с event-id превращается в TaskID(event:id), и любые повторные доставки схлопываются в одну задачу. Содержательная уникальность хороша там, где повторяется ровно одна и та же постановка: крон-задача, повтор вебхука с неизменным телом, кнопка «отправить», на которую нажали трижды. Если сомневаетесь — берите TaskID: явный ключ читается в дашборде и не зависит от правил сериализации. Комбинация легальна и иногда полезна: TaskID для идемпотентности события и Unique для отсечения случайных двойных нажатий — механизмы не конфликтуют, потому что живут на разных ключах. Только следите, чтобы явный ID не подменял содержательную уникальность там, где повтором может быть другой payload с тем же смыслом.

Соблазн дешёвого решения — сперва посмотреть, нет ли задачи, и ставить только если нет: ListPendingTasks или запрос в базу, потом Enqueue. В распределённой системе эта схема ломается гонкой: два инстанса читают пустой список в одну и ту же миллисекунду, оба видят «задачи нет» и оба ставят. Проверка и постановка — два разных шага, и между ними может вклиниться кто угодно, включая перезапуск инстанса. Unique закрывает именно это: замок в Redis ставится атомарной командой SET NX, и из двух одновременных постановок успешна ровно одна, вторая получает ErrDuplicateTask — без отдельной блокировки и без замков на уровне приложения. Остаточные гонки всё же есть, и все они про время: замок истёк, а задача жива — случай из живого места выше; успех снял замок, а нижестоящий сервис ещё обрабатывает прошлый прогон — случай для идемпотентного хендлера. Отсюда зрелая комбинация: Unique или TaskID против дубликатов постановки, проверка бизнес-ключа в хендлере против всего остального. Как страховка последней линии стоит проверка в обработчике: она срабатывает при любом сценарии, включая ручные постановки из скриптов. Заметьте, что гонка не всегда даёт дубль: из двух одновременных постановок одна получит ErrDuplicateTask, и её важно обработать без алерта — это нормальный исход конкуренции, а не сбой. Плохо то, что без Unique ошибку получает никто: две задачи молча живут обе.