Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

saga

/saga

Opisuje implementację wzorca Saga: orkiestrację, choreografię i transakcje kompensujące, przy projektowaniu transakcji rozproszonych, przepływów wielousługowych i spójności ostatecznej.

Repozytorium
Agent-Skills ↗
Licencja
MIT
Ostatnia zmiana repozytorium
01.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
3
Przestarzałość

Brak sygnałów. Repozytorium zmienione 01.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Opisuje implementację wzorca Saga: orkiestrację, choreografię i transakcje kompensujące, przy projektowaniu transakcji rozproszonych, przepływów wielousługowych i spójności ostatecznej.

Oryginalny opis (EN)

Expert Saga pattern implementation covering orchestration, choreography, and compensating transactions. Use when designing distributed transactions, multi-service workflows, or eventual consistency.

Jak działa

  1. When to Use
  2. Quick Start
  3. Core Concepts
  4. Common Patterns
  5. Best Practices
  6. Troubleshooting
  7. References
Sekcje z nagłówków SKILL.md, w oryginale · 146 linii, 665 słów
Podgląd SKILL.md
---
name: saga
description: Expert Saga pattern implementation covering orchestration, choreography, and compensating transactions. Use when designing distributed transactions, multi-service workflows, or eventual consistency.
---

# Saga Pattern

The Saga pattern manages data consistency across microservices in distributed transaction scenarios without two-phase commit (2PC). A Saga coordinates a sequence of local transactions, executing compensating transactions backward if any intermediate step fails.

## When to Use

- **Distributed Transactions Across Microservices**: Coordinating multi-step business transactions without two-phase commit (2PC) locks.
- **E-Commerce Checkout & Fulfillment**: Managing sequences spanning inventory reservation, payment charging, order placement, and delivery dispatch.
- **Long-Running Business Processes**: Orchestrating processes that span seconds, minutes, or hours with explicit failure compensation.
- **Failure Recovery & State Reversal**: Rolling back partially completed distributed steps using compensating transactions.

## Quick Start

```typescript
// Minimal Orchestrator-based Saga Definition
interface SagaStep<TContext> {
  name: string;
  execute: (ctx: TContext) => Promise<void>;
  compensate: (ctx: TContext) => Promise<void>;
}

async function runSaga<T>(context: T, steps: SagaStep<T>[]) {
  const executedSteps: SagaStep<T>[] = [];
  try {
    for (const step of steps) {
      console.log(`Executing step: ${step.name}`);
      await step.execute(context);
      executedSteps.push(step);
    }
    console.log("Saga completed successfully.");
  } catch (err) {
    console.error(
      `Saga failed. Rolling back compensating transactions...`,
      err,
    );
    for (const step of executedSteps.reverse()) {
      try {
        await step.compensate(context);
      } catch (compErr) {
        console.error(`Compensation failed for ${step.name}:`, compErr);
      }
    }
    throw err;
  }
}
```

## Core Concepts

### Orchestration vs Choreography Sagas

Sagas coordinate multi-service transactions using either a centralized orchestrator or decentralized events:

```text
[ Orchestrator ] ──1. Reserve Stock──→ [ Inventory Service ]
                 ──2. Charge Card───→ [ Payment Service ] (FAILS!)
                 ──3. Compensate: Release Stock ──→ [ Inventory Service ]
```

### Compensating Transactions (Semantic Rollback)

Because local transactions commit at each step, failures must be undone semantically through compensating transactions:

| Forward Transaction            | Compensating Transaction       |
| :----------------------------- | :----------------------------- |
| `ReserveStock(orderId, items)` | `ReleaseStock(orderId, items)` |
| `ChargeCreditCard(amount)`     | `RefundCreditCard(amount)`     |
| `CreateShipmentLabel()`        | `CancelShipmentLabel()`        |

### Orchestrator State Machine Definition

Tracks workflow progression and triggers compensation on error:

```typescript
// sagas/order-saga-orchestrator.ts
export class OrderSagaOrchestrator {
  async execute(order: OrderPayload) {
    let stockReserved = false;
    try {
      await inventoryService.reserve(order.id, order.items);
      stockReserved = true;

      await paymentService.charge(order.id, order.total);
      await shippingService.schedule(order.id);
    } catch (err) {
      console.error("Saga failed! Initiating compensation...", err);
      if (stockReserved) {
        await inventoryService.compensateRelease(order.id, order.items);
      }
      throw new Error("Order processing failed; changes compensated.");
    }
  }
}
```

## Common Patterns

### Idempotent Step Execution

**Problem**: Network retries during step execution can result in duplicate orders or double charges.

**Solution**:
Pass an idempotency key with every saga step command:

```typescript
async function processPayment(orderId: string, idempotencyKey: string) {
  const existing = await paymentDb.findByKey(idempotencyKey);
  if (existing) {
    return existing.result; // Return previous outcome without recharging
  }
  const result = await paymentGateway.charge(orderId);
  await paymentDb.save({ idempotencyKey, orderId, result });
  return result;
}
```

## Best Practices

**Do**:

- Prefer Orchestration for Complex Multi-Step Sagas: Use workflow orchestrators (Temporal, AWS Step Functions) for complex multi-branch sagas.
- Make Compensating Transactions Idempotent: Ensure compensation actions can be safely retried multiple times without side effects.
- Record Saga State Persistently: Store the current step and execution state in a durable outbox/database before calling external services.
- Design for Forward Recovery: When possible, retry or alert operators to fix transient issues rather than compensating immediately.

**Don't**:

- Assume compensating transactions can never fail: Implement alerts and manual intervention queues for failed compensations.
- Use distributed locks across sagas: Avoid blocking local resources while waiting for distant service responses.
- Use choreography for sagas with > 4 services: Event-driven choreography becomes impossible to trace and reason about at scale.

## Troubleshooting

| Error                      | Cause                                                | Solution                                                                                      |
| :------------------------- | :--------------------------------------------------- | :-------------------------------------------------------------------------------------------- |
| `Saga stuck in PENDING`    | Orchestrator crashed or message dropped in queue.    | Use persistent state machines (e.g., Temporal/Step Functions) with automated timeout retries. |
| `Compensation Failed`      | Compensating action encountered non-retryable error. | Flag transaction for operator review and write to dead-letter queue (DLQ).                    |
| `Duplicate Step Execution` | Retry occurred without idempotency check.            | Enforce unique idempotency keys per saga step execution.                                      |

## References

- [Microservices.io - Saga Pattern](https://microservices.io/patterns/data/saga.html)
- [Temporal.io Workflow Engine](https://temporal.io/)
- [AWS Step Functions Saga Guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/implement-the-saga-pattern-using-aws-step-functions.html)

Wersje

RepozytoriumWynikLicencja
Ta strona · G1Joshi/Agent-Skills100MIT
warpdotdev/common-skills100MIT
OutlineDriven/outline-driven-development100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 6175cdda85de (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 1 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100saga-orchestration
    Wdraża wzorce saga dla transakcji rozproszonych: koordynuje wieloetapowe procesy, obsługuje transakcje kompensujące i długo trwające przepływy.
  • 100saga-orchestration
    Implementuje wzorce saga dla transakcji rozproszonych i przepływów między agregatami, w tym koordynację wieloetapowych procesów, transakcje kompensujące i długotrwałe przepływy.
  • 100saga-orchestration
    Pomaga wdrażać wzorce saga w transakcjach rozproszonych: koordynacja wieloetapowych procesów biznesowych, transakcje kompensujące i zarządzanie długotrwałymi przepływami.
  • 100distributed-transactions-saga-pattern
    Utrzymuje spójność w wielu usługach dzięki transakcjom saga, w wersji zorkiestrowanej lub choreografowanej.
  • 100event-driven-architecture-saga-patterns
    Projektuje odporne rozproszone transakcje ze spójnością ostateczną przez wzorzec Saga (choreografia i orkiestracja): outbox, CDC, idempotentni konsumenci, transakcje kompensujące i odzyskiwanie sag.
  • 100spring-boot-saga-pattern
    Wspiera transakcje rozproszone wzorcem Saga w mikroserwisach Spring Boot: transakcje kompensujące, spójność ostateczna, choreografia i orkiestracja z Kafka, RabbitMQ lub Axon.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.