mufassall

Шпаргалка · Взаимодействие

Надёжные колбэки

12 мин · Средний · mufassall.dtwin.uz/ru/l/callbacks/

← Открыть урок

Проблема

Внешняя система присылает вам сообщение. Что сделать, чтобы оно не потерялось, не обработалось дважды и не тормозило систему.

Чему вы научитесь

  • Почему 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_store

Mermaid: последовательность запросов

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 0

D2

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
@enduml

PlantUML: компоненты

@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/с
Ответ p953 800 мс30 мс
Потеряно0%0%
Дважды0/мин0/мин

Шаги

  1. Проблема Вся работа до ответа

    Внешняя система присылает колбэк.

  2. Проблема 200 OK даже при ошибке

    Запись в базу упала на полпути.

  3. Решение Сначала сохрани, потом ответь

    Теперь API делает одно: пишет пришедшее сообщение как есть в таблицу inbox и сразу возвращает 200.

  4. Решение Тяжёлую работу — в очередь

    Сохранив сообщение, API кладёт в очередь короткую задачу.

  5. Проблема Подтвердили слишком рано

    Воркер, получив сообщение, сразу говорит очереди «принял» (ack) и только потом начинает работу.

  6. Решение Ack — только после работы

    Воркер подтверждает сообщение после того, как результат записан в базу.

  7. Кейс Одно сообщение — два результата

    Повторы приходят с двух сторон: внешняя система повторяет после таймаута, а очередь доставляет заново после падения воркера.

  8. Решение Ключ идемпотентности

    У каждого сообщения есть устойчивый ключ, например ID документа и статус.

  9. Итоги Итоги

    Четыре правила надёжного колбэка.

Термины

Идемпотентность
Выполнить операцию один раз или несколько — результат одинаковый. Сообщения могут доставляться повторно, поэтому каждый обработчик должен быть идемпотентным.