Шпаргалка · Бизнес-процессы
Доставка уведомлений
Проблема
Бизнес-приложение шлёт коды входа, уведомления «получен счёт» и чеки об оплате. Отправка прямо в запросе привязывает приложение к медленному провайдеру. Outbox, очередь и воркер-отправитель убирают провайдера из запроса; дальше идут лимиты, отчёты о доставке, цепочка резервных каналов с дедлайнами, дедупликация, настройки пользователя, стоимость и второй провайдер.
Чему вы научитесь
- Почему уведомление пишется в outbox вместе с бизнес-событием и отправляется воркером, а не в запросе
- Лимиты на провайдера через token bucket,
429иRetry-After, отдельная полоса для кодов входа - Принято не значит доставлено: отчёты о доставке, цепочка push, SMS, email и дедлайн, который останавливает протухший код
- Одно событие, одно сообщение на канал: ключи идемпотентности, тихие часы, настройки, стоимость сообщения и переключение провайдера
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_api["Бизнес-API"]
n_sms>"SMS-провайдер A"]
n_db[("БД с outbox")]
n_queue[["Очередь"]]
n_worker("Воркер отправки")
n_limiter{{"Лимитер"}}
n_sms2>"SMS-провайдер B"]
n_api --> n_db
n_db --> n_queue
n_queue --> n_worker
n_worker --x|"потеряно"| n_sms
n_worker --> n_limiter
n_sms -.-> n_api
n_worker --> n_db
n_worker --> n_sms2
classDef down fill:#fde2e2,stroke:#c62828,color:#4a0d0d,stroke-dasharray:4 3
class n_sms downMermaid: последовательность запросов
sequenceDiagram
participant n_api as Бизнес-API
participant n_sms as SMS-провайдер A
participant n_db as БД с outbox
participant n_queue as Очередь
participant n_worker as Воркер отправки
participant n_limiter as Лимитер
participant n_push as Push-сервис
participant n_sms2 as SMS-провайдер B
Note over n_api,n_sms: API отправляет SMS прямо в запросе
n_api->>n_sms: POST /v1/messages HTTP/1.1
n_sms-->>n_api: HTTP/1.1 200 OK
Note over n_api,n_sms: Медленный провайдер останавливает вход и всё остальное
n_api->>n_sms: 09:00:02 POST /auth/otp u_42: calling SMS provider
Note over n_api,n_db: Сообщение пишется в outbox в той же транзакции
n_api->>n_db: BEGIN#59;
n_db-->>n_api: COMMIT 12 ms
Note over n_queue,n_worker: Отправляют очередь и воркер
n_queue->>n_worker: notifications.sms partition 3 offset 88120
Note over n_worker,n_sms: Конец месяца: провайдер отвечает 429
n_worker->>n_sms: POST /v1/messages HTTP/1.1
n_sms-->>n_worker: HTTP/1.1 429 Too Many Requests
Note over n_worker,n_limiter: Token bucket на провайдера, отдельная полоса для кодов
n_worker->>n_limiter: EVAL token_bucket 1 bucket:sms_a rate=50 burst=50 take=1
n_limiter-->>n_worker: (integer) 0
Note over n_sms,n_api: Принято не значит доставлено: отчёты о доставке
n_sms->>n_api: POST /webhooks/sms-dlr HTTP/1.1
n_api-->>n_sms: HTTP/1.1 200 OK
Note over n_worker,n_push: Резервная цепочка с дедлайном на тип сообщения
n_worker->>n_push: ob_7730 invoice.received chain: push -#62; sms -#62; email
Note over n_worker,n_db: Одно событие, одно сообщение на канал
n_worker->>n_db: INSERT INTO deliveries (event_id, channel, provider_ref)
n_db-->>n_worker: INSERT 0 0
Note over n_worker,n_db: Настройки пользователя и тихие часы
n_worker->>n_db: SELECT channels, quiet_hours, tz FROM prefs WHERE user_id = 'u_77'
n_db-->>n_worker: decision ob_7731 payment.receipt at 23:40 local
Note over n_worker,n_sms2: Стоимость сообщения и второй провайдер
n_worker->>n_sms2: cost ob_5590 otp_login provider=sms_bD2
direction: right
n_api: "Бизнес-API" {
shape: rectangle
}
n_sms: "SMS-провайдер A" {
shape: cloud
style.fill: "#fde2e2"
style.stroke: "#c62828"
style.stroke-dash: 3
}
n_db: "БД с outbox" {
shape: cylinder
}
n_queue: "Очередь" {
shape: queue
}
n_worker: "Воркер отправки" {
shape: rectangle
style.multiple: true
}
n_limiter: "Лимитер" {
shape: hexagon
}
n_sms2: "SMS-провайдер B" {
shape: cloud
}
n_api -> n_db
n_db -> n_queue
n_queue -> n_worker
n_worker -> n_sms: "потеряно" {
target-arrowhead.shape: cross
}
n_worker -> n_limiter
n_sms -> n_api {
style.stroke-dash: 3
}
n_worker -> n_db
n_worker -> n_sms2PlantUML: последовательность запросов
@startuml
participant "Бизнес-API" as n_api
boundary "SMS-провайдер A" as n_sms
database "БД с outbox" as n_db
queue "Очередь" as n_queue
participant "Воркер отправки" as n_worker
collections "Лимитер" as n_limiter
boundary "Push-сервис" as n_push
boundary "SMS-провайдер B" as n_sms2
note over n_api, n_sms : API отправляет SMS прямо в запросе
n_api -> n_sms : POST /v1/messages HTTP/1.1
n_sms --> n_api : HTTP/1.1 200 OK
note over n_api, n_sms : Медленный провайдер останавливает вход и всё остальное
n_api -> n_sms : 09:00:02 POST /auth/otp u_42: calling SMS provider
note over n_api, n_db : Сообщение пишется в outbox в той же транзакции
n_api -> n_db : BEGIN;
n_db --> n_api : COMMIT 12 ms
note over n_queue, n_worker : Отправляют очередь и воркер
n_queue -> n_worker : notifications.sms partition 3 offset 88120
note over n_worker, n_sms : Конец месяца: провайдер отвечает 429
n_worker -> n_sms : POST /v1/messages HTTP/1.1
n_sms --> n_worker : HTTP/1.1 429 Too Many Requests
note over n_worker, n_limiter : Token bucket на провайдера, отдельная полоса для кодов
n_worker -> n_limiter : EVAL token_bucket 1 bucket:sms_a rate=50 burst=50 take=1
n_limiter --> n_worker : (integer) 0
note over n_sms, n_api : Принято не значит доставлено: отчёты о доставке
n_sms -> n_api : POST /webhooks/sms-dlr HTTP/1.1
n_api --> n_sms : HTTP/1.1 200 OK
note over n_worker, n_push : Резервная цепочка с дедлайном на тип сообщения
n_worker -> n_push : ob_7730 invoice.received chain: push -> sms -> email
note over n_worker, n_db : Одно событие, одно сообщение на канал
n_worker -> n_db : INSERT INTO deliveries (event_id, channel, provider_ref)
n_db --> n_worker : INSERT 0 0
note over n_worker, n_db : Настройки пользователя и тихие часы
n_worker -> n_db : SELECT channels, quiet_hours, tz FROM prefs WHERE user_id = 'u_77'
n_db --> n_worker : decision ob_7731 payment.receipt at 23:40 local
note over n_worker, n_sms2 : Стоимость сообщения и второй провайдер
n_worker -> n_sms2 : cost ob_5590 otp_login provider=sms_b
@endumlPlantUML: компоненты
@startuml
left to right direction
component "Бизнес-API" as n_api
cloud "SMS-провайдер A" as n_sms #fde2e2;line:c62828;line.dashed
database "БД с outbox" as n_db
queue "Очередь" as n_queue
collections "Воркер отправки" as n_worker
stack "Лимитер" as n_limiter
cloud "SMS-провайдер B" as n_sms2
n_api --> n_db
n_db --> n_queue
n_queue --> n_worker
n_worker -[#c62828,dashed]-> n_sms : потеряно
n_worker --> n_limiter
n_sms ..> n_api
n_worker --> n_db
n_worker --> n_sms2
@endumlИтог
Шесть правил доставки уведомлений.
1) Никогда не вызывайте провайдера внутри запроса пользователя: пишите сообщение в outbox в одной транзакции с событием, а отправляет пусть воркер из очереди. 2) Ограничивайте темп через token bucket на провайдера, соблюдайте 429 и Retry-After, дайте кодам входа свою полосу. 3) Принято не значит доставлено: отслеживайте отчёты, а отсутствие отчёта считайте неизвестным статусом. 4) Используйте резервную цепочку с дедлайном для каждого типа сообщений, чтобы просроченный код не отправлялся. 5) Дедуплицируйте по событию и каналу, уважайте настройки и тихие часы. 6) Пишите стоимость каждого сообщения и держите второго провайдера тёплым за circuit breaker.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| p95 задержки API | 320 мс | 140 мс |
| Доставлено | 97% | 98% |
| Дубли сообщений | 0/день | 0/день |
| Расходы на сообщения в день | 410 $ | 345 $ |
Шаги
- Кейс API отправляет SMS прямо в запросе
Пользователь входит в систему.
- Проблема Медленный провайдер останавливает вход и всё остальное
В 09:00 провайдер отвечает за 10 с вместо 0,3 с.
- Решение Сообщение пишется в outbox в той же транзакции
Запрос входа теперь сохраняет код и одну строку
outboxв одной транзакции: какое событие, какой канал, какой шаблон и до какого времени сообщение должно дойти. - Решение Отправляют очередь и воркер
Релей читает новые строки outbox и публикует их в очередь, по топику на канал.
- Проблема Конец месяца: провайдер отвечает 429
В последний день месяца в 18:00 в очередь падают 40 000 уведомлений о счетах.
- Решение Token bucket на провайдера, отдельная полоса для кодов
Перед каждой отправкой воркер берёт токен из общего лимитера: один бакет на провайдера, 50 токенов в секунду, общий для всех воркеров.
- Кейс Принято не значит доставлено: отчёты о доставке
200провайдера значит только, что он взял сообщение. - Решение Резервная цепочка с дедлайном на тип сообщения
У каждого типа сообщений своя цепочка.
- Решение Одно событие, одно сообщение на канал
Очередь доставляет как минимум один раз.
- Решение Настройки пользователя и тихие часы
Перед отправкой воркер читает настройки пользователя: каналы для каждого типа сообщений, тихие часы и часовой пояс.
- Решение Стоимость сообщения и второй провайдер
Каждая отправка пишет строку стоимости: провайдер, сегменты, кодировка, цена.
- Итоги Итог
Шесть правил доставки уведомлений.
Термины
- Отчёт о доставке (DLR)
- Последующий колбэк SMS- или push-провайдера о том, дошло ли сообщение до телефона. Принято не значит доставлено.
- Цепочка резервных каналов
- Упорядоченный список каналов (push, SMS, email) для типа сообщения. Останавливается на первой подтверждённой доставке или на дедлайне.
- Тихие часы
- Окно местного времени пользователя, когда несрочные уведомления откладываются до утра. Коды и оповещения безопасности не откладываются.