Шпаргалка · Взаимодействие
Надёжные колбэки
Проблема
Внешняя система присылает вам сообщение. Что сделать, чтобы оно не потерялось, не обработалось дважды и не тормозило систему.
Чему вы научитесь
- Почему
200 OKвозвращают только после сохранения - Как очередь и воркер отделяют ответ от тяжёлой работы
- Когда подтверждать (
ack): до работы или после - Повторная доставка и ключ идемпотентности
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_provider>"Внешняя система"]
n_api["API"]
n_store[("База")]
n_queue[["Очередь"]]
n_worker("Воркер")
n_provider -->|"вызов"| n_api
n_api -->|"вызов"| n_store
n_api -->|"асинхронно"| n_queue
n_queue -->|"асинхронно"| n_worker
n_worker -->|"вызов"| n_storeMermaid: последовательность запросов
sequenceDiagram
participant n_provider as Внешняя система
participant n_api as API
participant n_store as База
participant n_queue as Очередь
participant n_worker as Воркер
Note over n_provider,n_api: Вся работа до ответа
n_provider->>n_api: POST /callbacks HTTP/1.1
n_api-->>n_provider: HTTP/1.1 200 OK
Note over n_api,n_store: 200 OK даже при ошибке
n_api-xn_store: BEGIN#59;
Note over n_api,n_store: Сначала сохрани, потом ответь
n_api->>n_store: INSERT INTO inbox (event_id, payload, received_at)
n_store-->>n_api: INSERT 0 1
Note over n_api,n_queue: Тяжёлую работу — в очередь
n_api->>n_queue: PUBLISH callbacks.work
Note over n_queue,n_worker: Подтвердили слишком рано
n_queue-xn_worker: DELIVER callbacks.work delivery_tag=7
Note over n_queue,n_worker: Ack — только после работы
n_queue->>n_worker: DELIVER callbacks.work delivery_tag=7 redelivered=true
n_worker-->>n_queue: ACK delivery_tag=7
Note over n_provider,n_api: Одно сообщение — два результата
n_provider->>n_api: POST /callbacks HTTP/1.1
Note over n_worker,n_store: Ключ идемпотентности
n_worker->>n_store: INSERT INTO processed (event_id, result)
n_store-->>n_worker: INSERT 0 0D2
direction: right
n_provider: "Внешняя система" {
shape: cloud
}
n_api: "API" {
shape: rectangle
}
n_store: "База" {
shape: cylinder
}
n_queue: "Очередь" {
shape: queue
}
n_worker: "Воркер" {
shape: rectangle
style.multiple: true
}
n_provider -> n_api: "вызов"
n_api -> n_store: "вызов"
n_api -> n_queue: "асинхронно"
n_queue -> n_worker: "асинхронно"
n_worker -> n_store: "вызов"PlantUML: последовательность запросов
@startuml
boundary "Внешняя система" as n_provider
participant "API" as n_api
database "База" as n_store
queue "Очередь" as n_queue
participant "Воркер" as n_worker
note over n_provider, n_api : Вся работа до ответа
n_provider -> n_api : POST /callbacks HTTP/1.1
n_api --> n_provider : HTTP/1.1 200 OK
note over n_api, n_store : 200 OK даже при ошибке
n_api ->x n_store : [потеряно] BEGIN;
note over n_api, n_store : Сначала сохрани, потом ответь
n_api -> n_store : INSERT INTO inbox (event_id, payload, received_at)
n_store --> n_api : INSERT 0 1
note over n_api, n_queue : Тяжёлую работу — в очередь
n_api ->> n_queue : PUBLISH callbacks.work
note over n_queue, n_worker : Подтвердили слишком рано
n_queue ->x n_worker : [потеряно] DELIVER callbacks.work delivery_tag=7
note over n_queue, n_worker : Ack — только после работы
n_queue ->> n_worker : [повтор] DELIVER callbacks.work delivery_tag=7 redelivered=true
n_worker -->> n_queue : ACK delivery_tag=7
note over n_provider, n_api : Одно сообщение — два результата
n_provider -> n_api : [дубль] POST /callbacks HTTP/1.1
note over n_worker, n_store : Ключ идемпотентности
n_worker -> n_store : INSERT INTO processed (event_id, result)
n_store --> n_worker : INSERT 0 0
@endumlPlantUML: компоненты
@startuml
left to right direction
cloud "Внешняя система" as n_provider
component "API" as n_api
database "База" as n_store
queue "Очередь" as n_queue
collections "Воркер" as n_worker
n_provider --> n_api : вызов
n_api --> n_store : вызов
n_api --> n_queue : асинхронно
n_queue --> n_worker : асинхронно
n_worker --> n_store : вызов
@endumlИтог
Четыре правила надёжного колбэка.
1) 200 — только после сохранения. 2) Тяжёлая работа — в очереди и воркере. 3) Ack — после работы. 4) Любая обработка идемпотентна: повтор даёт тот же результат.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Входящие | 40/с | 40/с |
| Ответ p95 | 3 800 мс | 30 мс |
| Потеряно | 0% | 0% |
| Дважды | 0/мин | 0/мин |
Шаги
- Проблема Вся работа до ответа
Внешняя система присылает колбэк.
- Проблема
200 OKдаже при ошибкеЗапись в базу упала на полпути.
- Решение Сначала сохрани, потом ответь
Теперь API делает одно: пишет пришедшее сообщение как есть в таблицу inbox и сразу возвращает
200. - Решение Тяжёлую работу — в очередь
Сохранив сообщение, API кладёт в очередь короткую задачу.
- Проблема Подтвердили слишком рано
Воркер, получив сообщение, сразу говорит очереди «принял» (
ack) и только потом начинает работу. - Решение Ack — только после работы
Воркер подтверждает сообщение после того, как результат записан в базу.
- Кейс Одно сообщение — два результата
Повторы приходят с двух сторон: внешняя система повторяет после таймаута, а очередь доставляет заново после падения воркера.
- Решение Ключ идемпотентности
У каждого сообщения есть устойчивый ключ, например ID документа и статус.
- Итоги Итоги
Четыре правила надёжного колбэка.
Термины
- Идемпотентность
- Выполнить операцию один раз или несколько — результат одинаковый. Сообщения могут доставляться повторно, поэтому каждый обработчик должен быть идемпотентным.