Saga: как оркестрировать распределённые процессы
Saga: как оркестрировать распределённые процессы
Когда бизнес-процесс затрагивает несколько сервисов, возникает вопрос: как обеспечить согласованность? В монолите ответ простой - транзакция БД. В микросервисной архитектуре каждый сервис владеет своей базой, и общей транзакции нет. Two-Phase Commit (2PC) технически возможен, но на практике не масштабируется, держит блокировки слишком долго и создаёт single point of failure в координаторе.
Saga - это альтернатива распределённым транзакциям. Вместо одной атомарной операции мы выполняем цепочку локальных транзакций, а для отката определяем компенсирующие действия к каждому шагу.
Анатомия Saga
Saga состоит из шагов. Каждый шаг - это пара: действие (Execute) и компенсация (Compensate). Если шаг N упал, мы последовательно откатываем шаги N-1, N-2, ..., 1, вызывая их компенсации.
Пример - оформление заказа с оплатой и выдачей доступа:
Шаг 1: Создать заказ (status=pending)
└─ Компенсация: Отменить заказ (status=cancelled)
Шаг 2: Списать оплату
└─ Компенсация: Вернуть деньги (refund)
Шаг 3: Выдать доступ к курсу
└─ Компенсация: Отозвать доступ
Если выдача доступа (шаг 3) провалилась - возвращаем деньги (компенсация шага 2) и отменяем заказ (компенсация шага 1).
Orchestration Saga: центральный координатор
В оркестрационной саге один компонент (оркестратор) управляет всеми шагами. Он знает порядок выполнения и запускает компенсации при сбое.
Структура шага и оркестратор
// Step - один шаг саги: действие и его компенсация.
//
// Обе функции получают транзакцию: шаг обязан записывать свой эффект и отметку
// о себе одной командой COMMIT. Иначе «состояние саги в базе» разъезжается
// с реальностью ровно так же, как отметка в inbox с бизнес-операцией.
type Step struct {
Name string
Execute func(ctx context.Context, tx *sql.Tx) error
Compensate func(ctx context.Context, tx *sql.Tx) error
}
// Orchestrator выполняет шаги по порядку, при сбое откатывает выполненные.
type Orchestrator struct {
db *sql.DB
log *slog.Logger
steps []Step
}
func New(db *sql.DB, log *slog.Logger, steps ...Step) *Orchestrator {
return &Orchestrator{db: db, log: log, steps: steps}
}
// Run выполняет сагу с идентификатором sagaID.
//
// Идентификатор нужен не для логов: он ключ идемпотентности. Повторный запуск
// той же саги не должен повторять уже выполненные шаги, а восстановление
// после перезапуска процесса - находить их в базе, а не в памяти.
func (o *Orchestrator) Run(ctx context.Context, sagaID string) error {
// Журнал из базы: какие шаги этой саги уже выполнены прошлым запуском.
done, err := o.doneSteps(ctx, sagaID)
if err != nil {
return err
}
for _, step := range o.steps {
if done[step.Name] {
continue // шаг уже сделан - повтор дал бы второе списание
}
if err := o.runStep(ctx, sagaID, step); err != nil {
o.log.ErrorContext(ctx, "saga step failed, compensating",
slog.String("saga_id", sagaID),
slog.String("step", step.Name),
slog.String("err", err.Error()),
)
// Компенсации идут отдельной операцией и **возвращают** ошибку.
// Проглотить её значит оставить сагу в промежуточном состоянии
// молча - «оплачено, но не выдано» без единого сигнала.
if cErr := o.Compensate(ctx, sagaID); cErr != nil {
return fmt.Errorf("шаг %q упал (%w), откат не завершён: %w",
step.Name, err, cErr)
}
return fmt.Errorf("сага %s: шаг %q: %w", sagaID, step.Name, err)
}
}
return nil
}
// runStep выполняет один шаг: действие и отметку о нём одной транзакцией.
func (o *Orchestrator) runStep(ctx context.Context, sagaID string, step Step) error {
tx, err := o.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback()
if err := step.Execute(ctx, tx); err != nil {
return err
}
// Отметка в том же COMMIT, что и эффект шага. Порядок здесь не важен -
// важно, что они в одной транзакции: иначе после сбоя журнал скажет
// «шаг сделан», а эффекта не будет (или наоборот).
if err := markStep(ctx, tx, sagaID, step.Name, faultsql.StepDone); err != nil {
return err
}
return tx.Commit()
}
// Compensate откатывает все шаги саги, помеченные выполненными.
//
// Отдельный экспортируемый метод, а не приватная часть Run: после
// перезапуска процесса откат должен продолжиться, и запускать его будет
// внешний восстановитель, у которого нет ни `executed`, ни стека вызовов -
// только sagaID и база.
func (o *Orchestrator) Compensate(ctx context.Context, sagaID string) error {
done, err := o.doneSteps(ctx, sagaID)
if err != nil {
return err
}
var failed []string
// Обратный порядок: шаги откатываются от последнего к первому.
for i := len(o.steps) - 1; i >= 0; i-- {
step := o.steps[i]
if !done[step.Name] {
continue
}
if err := o.compensateStep(ctx, sagaID, step); err != nil {
// Не прекращаем откат: остальные шаги тоже надо попытаться
// откатить. Но и не забываем - список уйдёт вызывающему.
o.log.ErrorContext(ctx, "compensation failed",
slog.String("saga_id", sagaID),
slog.String("step", step.Name),
slog.String("err", err.Error()),
)
failed = append(failed, step.Name)
}
}
if len(failed) > 0 {
return fmt.Errorf("%w: шаги %v требуют вмешательства", ErrCompensationFailed, failed)
}
return nil
}
// compensateStep откатывает шаг и обновляет журнал одной транзакцией.
func (o *Orchestrator) compensateStep(ctx context.Context, sagaID string, step Step) error {
tx, err := o.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback()
if err := step.Compensate(ctx, tx); err != nil {
// Пометку о неудаче пишем **отдельной** транзакцией: та, в которой
// упала компенсация, откатится и унесёт пометку с собой.
o.markCompensationFailed(ctx, sagaID, step.Name)
return err
}
if err := markStep(ctx, tx, sagaID, step.Name, faultsql.StepCompensated); err != nil {
return err
}
return tx.Commit()
}
// markCompensationFailed фиксирует, что откат шага не удался.
//
// Ошибку записи здесь только логируем: если и она не прошла, сага уже
// в состоянии, требующем человека, а вернуть мы всё равно должны исходную
// ошибку компенсации - она информативнее.
func (o *Orchestrator) markCompensationFailed(ctx context.Context, sagaID, step string) {
tx, err := o.db.BeginTx(ctx, nil)
if err != nil {
o.log.ErrorContext(ctx, "cannot record compensation failure",
slog.String("saga_id", sagaID), slog.String("step", step),
slog.String("err", err.Error()))
return
}
defer tx.Rollback()
if err := markStep(ctx, tx, sagaID, step, faultsql.StepCompensationFailed); err != nil {
o.log.ErrorContext(ctx, "cannot record compensation failure",
slog.String("saga_id", sagaID), slog.String("step", step),
slog.String("err", err.Error()))
return
}
if err := tx.Commit(); err != nil {
o.log.ErrorContext(ctx, "cannot commit compensation failure",
slog.String("saga_id", sagaID), slog.String("step", step),
slog.String("err", err.Error()))
}
}
// doneSteps читает из базы шаги, которые выполнены и ещё не откачены.
func (o *Orchestrator) doneSteps(ctx context.Context, sagaID string) (map[string]bool, error) {
rows, err := o.db.QueryContext(ctx,
`SELECT step FROM saga_steps WHERE saga_id = $1 AND state = $2`,
sagaID, string(faultsql.StepDone),
)
if err != nil {
return nil, fmt.Errorf("query saga steps: %w", err)
}
defer rows.Close()
done := map[string]bool{}
for rows.Next() {
var step string
if err := rows.Scan(&step); err != nil {
return nil, fmt.Errorf("scan step: %w", err)
}
done[step] = true
}
return done, rows.Err()
}
// markStep пишет состояние шага. UPSERT, потому что шаг может быть записан
// повторно: retry, восстановление после перезапуска, повторная компенсация.
func markStep(ctx context.Context, tx *sql.Tx, sagaID, step string, st faultsql.StepState) error {
_, err := tx.ExecContext(ctx,
`INSERT INTO saga_steps (saga_id, step, state) VALUES ($1, $2, $3)
ON CONFLICT (saga_id, step) DO UPDATE SET state = excluded.state`,
sagaID, step, string(st),
)
if err != nil {
return fmt.Errorf("mark step %q as %s: %w", step, st, err)
}
return nil
}
<?php
// src/Application/Saga/SagaStep.php
declare(strict_types=1);
namespace App\Application\Saga;
use Closure;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
use Throwable;
use RuntimeException;
// Один шаг саги: действие + компенсация. Immutable - readonly properties.
// Обе функции получают соединение с открытой транзакцией: эффект шага
// и отметка о нём коммитятся вместе (как *sql.Tx в Go-версии).
final readonly class SagaStep
{
/**
* @param Closure(Connection):void $execute
* @param Closure(Connection):void $compensate
*/
public function __construct(
public string $name,
public Closure $execute,
public Closure $compensate,
) {}
}
final class SagaFailedException extends RuntimeException {}
// Откат не завершён: часть шагов требует вмешательства оператора.
final class CompensationFailedException extends RuntimeException {}
// src/Application/Saga/SagaOrchestrator.php
// Состояние саги живёт в журнале saga_steps (saga_id, step, state), а не в памяти.
final class SagaOrchestrator
{
private const DONE = 'done';
private const COMPENSATED = 'compensated';
private const COMPENSATION_FAILED = 'compensation_failed';
/** @param list<SagaStep> $steps */
public function __construct(
private readonly Connection $connection,
private readonly LoggerInterface $logger,
private readonly array $steps,
) {}
// sagaId - ключ идемпотентности: повторный запуск той же саги пропускает
// шаги, которые журнал уже знает как выполненные.
public function run(string $sagaId): void
{
$done = $this->doneSteps($sagaId);
foreach ($this->steps as $step) {
if (isset($done[$step->name])) {
continue;
}
try {
// Эффект шага и отметка о нём - одна транзакция
$this->connection->transactional(function (Connection $tx) use ($sagaId, $step): void {
($step->execute)($tx);
$this->markStep($tx, $sagaId, $step->name, self::DONE);
});
} catch (Throwable $e) {
$this->logger->error('saga step failed, compensating', [
'saga_id' => $sagaId,
'step' => $step->name,
'err' => $e->getMessage(),
]);
// Сбой компенсации не проглатываем: он уходит вызывающему
try {
$this->compensate($sagaId);
} catch (CompensationFailedException $c) {
throw new SagaFailedException(
sprintf('step %s failed (%s), compensation incomplete: %s', $step->name, $e->getMessage(), $c->getMessage()),
0,
$c,
);
}
throw new SagaFailedException(sprintf('saga %s failed at step %s', $sagaId, $step->name), 0, $e);
}
}
}
// Публичный метод, а не приватная часть run: после перезапуска процесса
// откат продолжает внешний восстановитель, у которого есть только sagaId и база.
public function compensate(string $sagaId): void
{
$done = $this->doneSteps($sagaId);
$failed = [];
// Обратный порядок: шаги откатываются от последнего к первому
foreach (array_reverse($this->steps) as $step) {
if (!isset($done[$step->name])) {
continue;
}
try {
$this->connection->transactional(function (Connection $tx) use ($sagaId, $step): void {
($step->compensate)($tx);
$this->markStep($tx, $sagaId, $step->name, self::COMPENSATED);
});
} catch (Throwable $e) {
// Транзакция с упавшей компенсацией откатилась вместе с пометкой,
// поэтому пометку о неудаче пишем отдельной транзакцией.
$this->markCompensationFailed($sagaId, $step->name);
$this->logger->error('compensation failed', [
'saga_id' => $sagaId,
'step' => $step->name,
'err' => $e->getMessage(),
]);
// Не прекращаем откат, но и не забываем - список уйдёт вызывающему
$failed[] = $step->name;
}
}
if ($failed !== []) {
throw new CompensationFailedException(
sprintf('steps %s need operator attention', implode(', ', $failed)),
);
}
}
private function markCompensationFailed(string $sagaId, string $step): void
{
try {
$this->connection->transactional(
fn (Connection $tx) => $this->markStep($tx, $sagaId, $step, self::COMPENSATION_FAILED),
);
} catch (Throwable $e) {
$this->logger->error('cannot record compensation failure', [
'saga_id' => $sagaId,
'step' => $step,
'err' => $e->getMessage(),
]);
}
}
/** @return array<string, true> шаги, которые выполнены и ещё не откачены */
private function doneSteps(string $sagaId): array
{
$names = $this->connection->fetchFirstColumn(
'SELECT step FROM saga_steps WHERE saga_id = :id AND state = :state',
['id' => $sagaId, 'state' => self::DONE],
);
return array_fill_keys($names, true);
}
// UPSERT: шаг может быть записан повторно (retry, восстановление, повторный откат)
private function markStep(Connection $tx, string $sagaId, string $step, string $state): void
{
$tx->executeStatement(
'INSERT INTO saga_steps (saga_id, step, state) VALUES (:id, :step, :state)
ON CONFLICT (saga_id, step) DO UPDATE SET state = excluded.state',
['id' => $sagaId, 'step' => $step, 'state' => $state],
);
}
}
# application/saga/step.py
from dataclasses import dataclass
from typing import Callable
from psycopg import Cursor
# Step - один шаг саги: действие и его компенсация.
#
# Обе функции получают курсор открытой транзакции: шаг обязан записывать свой эффект
# и отметку о себе одной командой COMMIT. Иначе «состояние саги в базе» разъезжается
# с реальностью ровно так же, как отметка в inbox с бизнес-операцией.
# Сбой шага - исключение, а не возвращаемая ошибка.
@dataclass(frozen=True, slots=True)
class Step:
name: str
execute: Callable[[Cursor], None]
compensate: Callable[[Cursor], None]
# application/saga/orchestrator.py
import logging
from enum import Enum
from psycopg import Connection, Cursor
class StepState(str, Enum):
DONE = "done"
COMPENSATED = "compensated"
COMPENSATION_FAILED = "compensation_failed"
class CompensationFailedError(Exception):
"""Откат не завершён: часть шагов требует вмешательства оператора."""
class SagaError(Exception):
"""Сага упала и откатилась (или откатилась не до конца - см. __cause__)."""
class Orchestrator:
"""Выполняет шаги по порядку, при сбое откатывает выполненные."""
def __init__(self, conn: Connection, log: logging.Logger, *steps: Step) -> None:
self._conn = conn
self._log = log
self._steps = steps
# run выполняет сагу с идентификатором saga_id.
#
# Идентификатор нужен не для логов: он ключ идемпотентности. Повторный запуск
# той же саги не должен повторять уже выполненные шаги, а восстановление
# после перезапуска процесса - находить их в базе, а не в памяти.
def run(self, saga_id: str) -> None:
done = self._done_steps(saga_id)
for step in self._steps:
if step.name in done:
continue # шаг уже выполнен прошлым запуском - не повторяем
try:
self._run_step(saga_id, step)
except Exception as err:
self._log.error(
"saga step failed, compensating",
extra={"saga_id": saga_id, "step": step.name, "err": str(err)},
)
# Компенсации идут отдельной операцией и пробрасывают ошибку.
# Проглотить её значит оставить сагу в промежуточном состоянии
# молча - «оплачено, но не выдано» без единого сигнала.
try:
self.compensate(saga_id)
except Exception as c_err:
raise SagaError(
f"шаг {step.name!r} упал ({err}), откат не завершён: {c_err}"
) from c_err
raise SagaError(f"сага {saga_id}: шаг {step.name!r}: {err}") from err
def _run_step(self, saga_id: str, step: Step) -> None:
"""Выполняет один шаг: действие и отметку о нём одной транзакцией."""
# Выход из with без исключения - COMMIT, с исключением - ROLLBACK.
with self._conn.transaction(), self._conn.cursor() as cur:
step.execute(cur)
# Отметка в том же COMMIT, что и эффект шага. Порядок здесь не важен -
# важно, что они в одной транзакции: иначе после сбоя журнал скажет
# «шаг сделан», а эффекта не будет (или наоборот).
_mark_step(cur, saga_id, step.name, StepState.DONE)
# compensate откатывает все шаги саги, помеченные выполненными.
#
# Отдельный публичный метод, а не приватная часть run: после
# перезапуска процесса откат должен продолжиться, и запускать его будет
# внешний восстановитель, у которого нет ни списка executed, ни стека вызовов -
# только saga_id и база.
def compensate(self, saga_id: str) -> None:
done = self._done_steps(saga_id)
failed: list[str] = []
# Обратный порядок: шаги откатываются от последнего к первому.
for step in reversed(self._steps):
if step.name not in done:
continue
try:
self._compensate_step(saga_id, step)
except Exception as err:
# Не прекращаем откат: остальные шаги тоже надо попытаться
# откатить. Но и не забываем - список уйдёт вызывающему.
self._log.error(
"compensation failed",
extra={"saga_id": saga_id, "step": step.name, "err": str(err)},
)
failed.append(step.name)
if failed:
raise CompensationFailedError(f"шаги {failed} требуют вмешательства")
def _compensate_step(self, saga_id: str, step: Step) -> None:
"""Откатывает шаг и обновляет журнал одной транзакцией."""
try:
with self._conn.transaction(), self._conn.cursor() as cur:
step.compensate(cur)
_mark_step(cur, saga_id, step.name, StepState.COMPENSATED)
except Exception:
# Транзакция с упавшей компенсацией уже откатилась и унесла бы пометку
# с собой - поэтому пометку о неудаче пишем отдельной транзакцией.
self._mark_compensation_failed(saga_id, step.name)
raise
# _mark_compensation_failed фиксирует, что откат шага не удался.
#
# Ошибку записи здесь только логируем: если и она не прошла, сага уже
# в состоянии, требующем человека, а пробросить мы всё равно должны исходную
# ошибку компенсации - она информативнее.
def _mark_compensation_failed(self, saga_id: str, step: str) -> None:
try:
with self._conn.transaction(), self._conn.cursor() as cur:
_mark_step(cur, saga_id, step, StepState.COMPENSATION_FAILED)
except Exception as err:
self._log.error(
"cannot record compensation failure",
extra={"saga_id": saga_id, "step": step, "err": str(err)},
)
def _done_steps(self, saga_id: str) -> set[str]:
"""Читает из базы шаги, которые выполнены и ещё не откачены."""
with self._conn.transaction(), self._conn.cursor() as cur:
cur.execute(
"SELECT step FROM saga_steps WHERE saga_id = %s AND state = %s",
(saga_id, StepState.DONE.value),
)
return {step for (step,) in cur.fetchall()}
def _mark_step(cur: Cursor, saga_id: str, step: str, state: StepState) -> None:
"""Пишет состояние шага. UPSERT, потому что шаг может быть записан
повторно: retry, восстановление после перезапуска, повторная компенсация.
"""
cur.execute(
"""INSERT INTO saga_steps (saga_id, step, state) VALUES (%s, %s, %s)
ON CONFLICT (saga_id, step) DO UPDATE SET state = excluded.state""",
(saga_id, step, state.value),
)
Реальный пример - CreateOrder Saga
// CreateOrderSaga оформляет заказ: создаёт его, списывает оплату, выдаёт доступ.
//
// Данные для компенсаций не живут в замыканиях: ID заказа задаётся снаружи
// и совпадает с ID саги. Поэтому откат после перезапуска процесса
// (Compensate(ctx, orderID)) знает, что отменять, без состояния в памяти.
// req после рестарта восстанавливается из saga_states.payload (раздел Persistence ниже).
// Сервисы здесь - модули того же монолита и пишут в транзакцию шага tx.
func CreateOrderSaga(
db *sql.DB,
log *slog.Logger,
orderSvc OrderService,
paymentSvc PaymentService,
accessSvc AccessService,
orderID string,
req CreateOrderRequest,
) *Orchestrator {
return New(db, log,
Step{
Name: "create_order",
Execute: func(ctx context.Context, tx *sql.Tx) error {
return orderSvc.Create(ctx, tx, orderID, req.UserID, req.CourseID)
},
Compensate: func(ctx context.Context, tx *sql.Tx) error {
return orderSvc.Cancel(ctx, tx, orderID)
},
},
Step{
Name: "charge_payment",
Execute: func(ctx context.Context, tx *sql.Tx) error {
return paymentSvc.Charge(ctx, tx, req.UserID, req.Amount, orderID)
},
Compensate: func(ctx context.Context, tx *sql.Tx) error {
return paymentSvc.Refund(ctx, tx, orderID)
},
},
Step{
Name: "grant_access",
Execute: func(ctx context.Context, tx *sql.Tx) error {
return accessSvc.GrantCourseAccess(ctx, tx, req.UserID, req.CourseID)
},
Compensate: func(ctx context.Context, tx *sql.Tx) error {
return accessSvc.RevokeCourseAccess(ctx, tx, req.UserID, req.CourseID)
},
},
)
}
// Использование:
// orderID := uuid.NewString() // он же ID саги
// saga := CreateOrderSaga(db, log, orderSvc, paymentSvc, accessSvc, orderID, req)
// if err := saga.Run(ctx, orderID); err != nil {
// // Сага откатилась; если откат не завершён - err оборачивает ErrCompensationFailed
// return fmt.Errorf("order creation failed: %w", err)
// }
<?php
// src/Application/Saga/CreateOrderSaga.php
declare(strict_types=1);
namespace App\Application\Saga;
use App\Application\Port\AccessService;
use App\Application\Port\OrderService;
use App\Application\Port\PaymentService;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
final class CreateOrderSaga
{
public function __construct(
private readonly Connection $connection,
private readonly LoggerInterface $logger,
private readonly OrderService $orders,
private readonly PaymentService $payments,
private readonly AccessService $access,
) {}
// orderId задаётся снаружи и служит ID саги: компенсации знают, что отменять,
// даже после перезапуска процесса - без состояния в замыканиях.
public function orchestrator(string $orderId, CreateOrderRequest $req): SagaOrchestrator
{
return new SagaOrchestrator($this->connection, $this->logger, [
new SagaStep(
name: 'create_order',
execute: fn (Connection $tx) => $this->orders->create($tx, $orderId, $req->userId, $req->courseId),
compensate: fn (Connection $tx) => $this->orders->cancel($tx, $orderId),
),
new SagaStep(
name: 'charge_payment',
execute: fn (Connection $tx) => $this->payments->charge($tx, $req->userId, $req->amount, $orderId),
compensate: fn (Connection $tx) => $this->payments->refund($tx, $orderId),
),
new SagaStep(
name: 'grant_access',
execute: fn (Connection $tx) => $this->access->grantCourseAccess($tx, $req->userId, $req->courseId),
compensate: fn (Connection $tx) => $this->access->revokeCourseAccess($tx, $req->userId, $req->courseId),
),
]);
}
public function run(string $orderId, CreateOrderRequest $req): void
{
$this->orchestrator($orderId, $req)->run(sagaId: $orderId);
}
}
# application/saga/create_order_saga.py
import logging
from psycopg import Connection, Cursor
def create_order_saga(
conn: Connection,
log: logging.Logger,
order_svc: OrderService,
payment_svc: PaymentService,
access_svc: AccessService,
order_id: str,
req: CreateOrderRequest,
) -> Orchestrator:
"""Оформляет заказ: создаёт его, списывает оплату, выдаёт доступ.
order_id задаётся снаружи и служит ID саги: компенсации знают, что отменять,
даже после перезапуска процесса - без состояния в замыканиях.
Сервисы получают курсор открытой транзакции шага - их эффект коммитится
вместе с отметкой о шаге (см. Step выше).
"""
def create_order(cur: Cursor) -> None:
order_svc.create(cur, order_id, req.user_id, req.course_id)
def cancel_order(cur: Cursor) -> None:
order_svc.cancel(cur, order_id)
def charge_payment(cur: Cursor) -> None:
payment_svc.charge(cur, req.user_id, req.amount, order_id)
def refund_payment(cur: Cursor) -> None:
payment_svc.refund(cur, order_id)
def grant_access(cur: Cursor) -> None:
access_svc.grant_course_access(cur, req.user_id, req.course_id)
def revoke_access(cur: Cursor) -> None:
access_svc.revoke_course_access(cur, req.user_id, req.course_id)
return Orchestrator(
conn,
log,
Step(name="create_order", execute=create_order, compensate=cancel_order),
Step(name="charge_payment", execute=charge_payment, compensate=refund_payment),
Step(name="grant_access", execute=grant_access, compensate=revoke_access),
)
# Использование:
# order_id = str(uuid.uuid4()) # он же ID саги
# saga = create_order_saga(conn, log, order_svc, payment_svc, access_svc, order_id, req)
# try:
# saga.run(saga_id=order_id)
# except SagaError as err:
# # Saga откатилась, все компенсации выполнены (или в err.__cause__ - какие нет)
# raise OrderCreationFailed("order creation failed") from err
⚠️ Три вещи, которых не было в первой версии этого кода
Оркестратор в этом уроке раньше был короче - и нарушал два правила, записанных в самом уроке разделами ниже. Оба дефекта проявляются только под сбоем, поэтому и прожили долго.
1. Состояние саги жило в памяти. Список выполненных шагов был локальной переменной
executed. Процесс перезапустился на середине - и знания «что надо откатить» не осталось нигде. Раздел типичных ошибок требует «сохраняй состояние саги в БД после каждого шага», код этого не делал. ТеперьCompensate- отдельный метод, которому нужен толькоsagaID: он читает журнал из базы, поэтому откат может продолжить любой другой процесс.2. Сбой компенсации проглатывался.
compensateлогировала ошибку и шла дальше, ничего не возвращая. Снаружи это выглядело как «сага откатилась», хотя средний шаг застрял в «оплачено, но не выдано». Тот же урок пишет: «Каждый сбой компенсации = алёрт оператора, не просто запись в лог». Теперь ошибка возвращается вызывающему вместе со списком застрявших шагов, а сами шаги помечаются в журнале - по этой пометке оператор их и находит.3. Шаг и отметка о нём - в одной транзакции, если шаг локальный. Отсюда
*sql.Txв сигнатуреExecuteиCompensate. Запиши отметку отдельно, и сбой между ней и эффектом оставит журнал и реальность в разных состояниях: откат либо пропустит шаг, либо попытается откатить не сделанное. Это тот же класс ошибки, что в inbox.Это работает, только пока эффект шага пишется в ту же базу, что и журнал (модули одного монолита). Для шага во внешнем сервисе со своей базой одной транзакции не бывает: перед вызовом записываем «шаг начат» с ключом идемпотентности (sagaID + имя шага), передаём этот ключ внешнему API, а после ответа отмечаем «done». При восстановлении шаг в состоянии «начат» повторяем с тем же ключом или компенсируем - внешний сервис по ключу распознает повтор и не спишет деньги второй раз.
Choreography Saga: сервисы реагируют на события
В хореографической саге нет центрального координатора. Каждый сервис слушает события и реагирует на них, публикуя новые события:
Каждый сервис знает только о своих событиях и о том, на какие чужие события реагировать. Нет единой точки, которая видит весь процесс.
Orchestration vs Choreography
| Критерий | Orchestration | Choreography |
|---|---|---|
| Видимость процесса | Весь flow в одном месте | Разбросан по сервисам |
| Связанность | Оркестратор знает обо всех | Сервисы знают только о соседних событиях |
| Отладка | Проще: смотришь оркестратор | Сложнее: восстанавливаешь по логам |
| Масштабирование | Оркестратор может стать bottleneck | Лучше масштабируется |
| Отказоустойчивость | Оркестратор - единая точка отказа: пока он лежит, ни шаги, ни компенсации не идут. Смягчают состоянием в БД и несколькими экземплярами | Нет центра, но сбой одного сервиса тоже стопорит свою часть цепочки |
| Новый шаг | Добавляется в одном месте - в оркестраторе | Кажется дешёвым (подписал сервис на событие), но обычно приходится менять публикацию и компенсации у соседей |
| Когда использовать | 3-7 шагов, сложная логика | 2-3 шага, простые реакции |
Для большинства проектов начинайте с оркестрации. Переходите к хореографии, когда оркестратор становится bottleneck или когда сервисы принадлежат разным командам.
Persistence: сохранение состояния саги
Если оркестратор упадёт между шагами, нужно знать, на каком шаге остановились. Для этого состояние саги сохраняется в БД.
Оркестратор выше уже хранит состояние в saga_steps (по строке на шаг). Таблица saga_states ниже - уровень саги целиком: тип, статус, входной payload (из него после рестарта восстанавливается req для компенсаций) и время. Вместе они позволяют при старте найти незавершённые саги и продолжить их или откатить:
// SagaState хранит текущее состояние саги в БД.
type SagaState struct {
ID string `json:"id"`
Type string `json:"type"` // "create_order"
CurrentStep int `json:"current_step"` // индекс текущего шага
Status string `json:"status"` // running, completed, compensating, failed
Payload []byte `json:"payload"` // входные данные саги
CompletedSteps []string `json:"completed_steps"` // имена выполненных шагов
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
// SaveState сохраняет состояние саги после каждого шага.
func (r *SagaRepo) SaveState(ctx context.Context, state SagaState) error {
_, err := r.db.ExecContext(ctx,
`INSERT INTO saga_states (id, type, current_step, status, payload, completed_steps, created_at, updated_at)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
ON CONFLICT (id) DO UPDATE SET
current_step = EXCLUDED.current_step,
status = EXCLUDED.status,
completed_steps = EXCLUDED.completed_steps,
updated_at = EXCLUDED.updated_at`,
state.ID, state.Type, state.CurrentStep, state.Status,
state.Payload, pq.Array(state.CompletedSteps),
state.CreatedAt, time.Now(),
)
return err
}
<?php
// src/Infrastructure/Saga/SagaState.php
declare(strict_types=1);
namespace App\Infrastructure\Saga;
// Snapshot состояния саги. Immutable - вместо мутации создаём новую версию.
final readonly class SagaState
{
/** @param list<string> $completedSteps */
public function __construct(
public string $id,
public string $type, // 'create_order'
public int $currentStep, // индекс текущего шага
public string $status, // running, completed, compensating, failed
public string $payload, // JSON-строка - входные данные саги
public array $completedSteps,
public DateTimeImmutable $createdAt,
public DateTimeImmutable $updatedAt,
) {}
}
// src/Infrastructure/Saga/SagaRepository.php
namespace App\Infrastructure\Saga;
use Doctrine\DBAL\Connection;
use DateTimeImmutable;
final class SagaRepository
{
public function __construct(
private readonly Connection $connection,
) {}
public function saveState(SagaState $state): void
{
// jsonb[]/text[] для completedSteps в Postgres - удобно для запросов.
$this->connection->executeStatement(
'INSERT INTO saga_states (id, type, current_step, status, payload, completed_steps, created_at, updated_at)
VALUES (:id, :type, :step, :status, :payload, :completed, :created, :updated)
ON CONFLICT (id) DO UPDATE SET
current_step = EXCLUDED.current_step,
status = EXCLUDED.status,
completed_steps = EXCLUDED.completed_steps,
updated_at = EXCLUDED.updated_at',
[
'id' => $state->id,
'type' => $state->type,
'step' => $state->currentStep,
'status' => $state->status,
'payload' => $state->payload,
'completed' => '{' . implode(',', $state->completedSteps) . '}',
'created' => $state->createdAt->format('Y-m-d H:i:s'),
'updated' => $state->updatedAt->format('Y-m-d H:i:s'),
],
);
}
}
# infrastructure/saga/saga_repo.py
from dataclasses import dataclass, field
from datetime import datetime, timezone
from psycopg import Connection
@dataclass(slots=True)
class SagaState:
"""Хранит текущее состояние саги в БД."""
saga_id: str
saga_type: str # "create_order"; в БД - колонка type
current_step: int # индекс текущего шага
status: str # running, completed, compensating, failed
payload: bytes # входные данные саги (JSON)
completed_steps: list[str] = field(default_factory=list) # имена выполненных шагов
created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
updated_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
class SagaRepo:
def __init__(self, conn: Connection) -> None:
self._conn = conn
def save_state(self, state: SagaState) -> None:
"""Сохраняет состояние саги после каждого шага."""
# list[str] psycopg сам передаёт как text[] - аналог pq.Array в Go.
with self._conn.transaction(), self._conn.cursor() as cur:
cur.execute(
"""INSERT INTO saga_states (id, type, current_step, status, payload, completed_steps, created_at, updated_at)
VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
ON CONFLICT (id) DO UPDATE SET
current_step = EXCLUDED.current_step,
status = EXCLUDED.status,
completed_steps = EXCLUDED.completed_steps,
updated_at = EXCLUDED.updated_at""",
(
state.saga_id, state.saga_type, state.current_step, state.status,
state.payload, state.completed_steps,
state.created_at, datetime.now(timezone.utc),
),
)
При старте приложения - находим саги в статусе running или compensating и возобновляем их с нужного шага.
Timeout: что если шаг не отвечает
В распределённой системе шаг может зависнуть. Каждый шаг должен иметь таймаут:
// executeWithTimeout выполняет шаг с таймаутом.
func executeWithTimeout(ctx context.Context, tx *sql.Tx, step Step, timeout time.Duration) error {
ctx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()
done := make(chan error, 1)
go func() {
done <- step.Execute(ctx, tx)
}()
select {
case err := <-done:
return err
case <-ctx.Done():
return fmt.Errorf("step %q timed out after %v", step.Name, timeout)
}
}
<?php
// src/Application/Saga/TimeoutExecutor.php
declare(strict_types=1);
namespace App\Application\Saga;
use Doctrine\DBAL\Connection;
use Throwable;
// В PHP нет goroutines, и таймаут принудительно из основного потока выставить
// нельзя. Реальный таймаут прокидывается внутрь HTTP/DB-клиента шага.
// На уровне саги - проверка длительности через Stopwatch + бросок исключения.
final class TimeoutExecutor
{
public function __construct(
private readonly int $timeoutSeconds,
) {}
public function execute(SagaStep $step, Connection $tx): void
{
$startedAt = hrtime(true);
try {
($step->execute)($tx);
} catch (Throwable $e) {
// Прокидываем как есть - external client уже бросает на своём deadline
throw $e;
}
$elapsedSeconds = (hrtime(true) - $startedAt) / 1_000_000_000;
if ($elapsedSeconds > $this->timeoutSeconds) {
// Шаг завершился, но за пределами SLA - бросаем для откатов выше.
// Реальная отмена должна быть прокинута в каждый внешний вызов:
// - Symfony HttpClient: ['timeout' => 30]
// - Doctrine: statement_timeout в Postgres
// - Symfony Lock: ttl
throw new SagaStepTimedOutException(sprintf(
'step %s exceeded SLA: %.2fs > %ds',
$step->name,
$elapsedSeconds,
$this->timeoutSeconds,
));
}
}
}
# application/saga/timeout.py
from concurrent.futures import ThreadPoolExecutor
from concurrent.futures import TimeoutError as FutureTimeoutError
from psycopg import Cursor
class StepTimedOutError(Exception):
pass
# execute_with_timeout выполняет шаг с таймаутом.
#
# Аналог goroutine + select: шаг - блокирующий I/O, поэтому threading
# (ThreadPoolExecutor), а не asyncio; в асинхронном коде это asyncio.wait_for.
# Как и в Go, поток с шагом не убивается по таймауту - реальную отмену нужно
# пробросить внутрь шага: timeout у HTTP-клиента, statement_timeout у Postgres.
def execute_with_timeout(step: Step, cur: Cursor, timeout: float) -> None:
# Не через with: контекстный менеджер пула дождался бы зависший поток
# и таймаут потерял бы смысл. shutdown(wait=False) отпускает его в фон.
pool = ThreadPoolExecutor(max_workers=1)
try:
future = pool.submit(step.execute, cur)
try:
future.result(timeout=timeout) # исключение шага пробросится как есть
except FutureTimeoutError:
raise StepTimedOutError(f"step {step.name!r} timed out after {timeout}s") from None
finally:
pool.shutdown(wait=False)
Таймаут по умолчанию - 30 секунд на шаг. Для внешних платёжных систем может быть больше. Главное - не ждать бесконечно: застрявшая сага блокирует ресурсы.
⚠️ Саги не гарантируют изоляцию - используй идемпотентность в каждом шаге
Между шагами саги другие процессы могут читать промежуточное состояние (заказ создан, но не оплачен). Это нормально - saga обеспечивает eventual consistency, а не ACID. Каждый шаг и каждая компенсация должны быть идемпотентными, потому что при восстановлении после сбоя они могут быть вызваны повторно.
Компенсации: правила проектирования
Компенсация - это не просто DELETE или undo. Несколько правил:
- Компенсация должна быть идемпотентной. Она может быть вызвана несколько раз: оркестратор перезапустился, retry сработал дважды - и
refundне должен вернуть деньги два раза. Механика та же, что у подписчиков: дедупликация по идентификатору операции, UPSERT вместо инкремента - см. идемпотентность. - Сбой компенсации не должен останавливать откат остальных шагов. Если компенсация упала - помечаем шаг
compensation_failed, продолжаем откатывать остальные, а в конце возвращаем ошибку со списком застрявших шагов и поднимаем алерт оператору. - Компенсация - это семантический откат. Не обязательно удалять данные. Можно пометить заказ как
cancelled, вместо удаления строки. - Не все шаги требуют компенсации. Если шаг только читает данные (валидация) - компенсировать нечего.
Как это проверено
examples/reliability/saga (go test ./...) проверяет утверждения этого
урока прогоном:
- сбой на каждом шаге - по очереди падает первый, второй, третий. После любого сбоя журнал эффектов должен свернуться в ноль: сага либо прошла целиком, либо откатилась целиком;
- сбой на каждой операции базы, включая
COMMITи запись в журнал шагов. Инвариант: число непогашенных эффектов равно числу шагов в состоянииdone. Расхождение означает, что откат пропустит шаг или попробует откатить не сделанное; - идемпотентность компенсации - три вызова
Compensateподряд дают один откат на шаг, а не три; - откат после «перезапуска» - оркестратор создаётся заново, без списка выполненных шагов, и находит их в базе;
- сбой компенсации виден вызывающему - ошибка содержит имя застрявшего шага, а сам шаг помечен в журнале.
Рядом лежит BrokenOrchestrator - версия из первой редакции урока. Тесты
на ней фиксируют оба дефекта: сбой отката не виден снаружи, а после
перезапуска откатывать нечего. Без сломанной версии тесты выше ничего
не доказывали бы - проверка имеет смысл, только если известно, что она
способна упасть.
Типичные ошибки
- Saga вместо распределённой транзакции «на всякий» - для простого случая (БД + Redis) часто хватает Outbox + idempotency без оркестратора. Saga нужна когда 3+ шага, каждый с побочным эффектом во внешней системе.
- Компенсация =
DELETEстрок - другие подписчики уже прочитали данные, ссылаются на них. Лучше - пометкаstatus: cancelled, событиеOrderCancelled. Логический откат, не физический. - Состояние саги только в памяти - процесс перезапустился на середине, нет ни данных «где мы», ни компенсаций. Сохраняй состояние саги в БД после каждого шага + при старте находи незавершённые и продолжай.
- Компенсации падают тихо -
compensate()поймала ошибку, залогировала и пошла дальше; средний шаг застрял в «оплачено, но не выдано». Каждый сбой компенсации = алёрт оператора, не просто запись в лог; какие сигналы и пороги для этого заводить - в уроке про наблюдаемость. - Choreography с цепочкой длиннее 3 событий -
OrderCreated → InventoryReserved → PaymentProcessed → AccessGranted → ...Без центрального state почти невозможно понять, на каком шаге saga застряла. Длинные потоки лучше делать Orchestration. - Шаг не идемпотентный - Saga при retry повторяет шаг, который начисляет деньги - двойное списание. Каждый шаг (как и компенсация) обязан быть идемпотентным.
- Timeout не пробрасывается во внешний вызов -
select { case <-ctx.Done() }сработал, но HTTP-запрос в платёжку всё равно сидит в сокете. Compensation вызвана, но платёж мог пройти. Передавайctxв HTTP-клиент, чтобы запрос реально отменился. - Saga + долгий шаг ожидания (
SleepUntilнесколько дней) - оркестратор держит горутину/коннект к БД сутками. Используй durable scheduler (Temporal/Cadence) или persisted Saga с wake-up через cron.
Мини-задание
- Реализуй
SagaOrchestratorс методамиRunиcompensateпо примеру из урока - Опиши процесс из 3 шагов (создание заказа, оплата, выдача доступа) и компенсацию к каждому шагу
- Добавь таймаут 10 секунд на каждый шаг с помощью
context.WithTimeout - Напиши unit-тест: при сбое на шаге 3 компенсации шагов 2 и 1 должны быть вызваны в обратном порядке
- Добавь сохранение состояния саги в таблицу
saga_statesпосле каждого шага