Spring Boot イベント駆動パターン

概要

Spring Boot 3.x でドメインイベント、ApplicationEventPublisher、@TransactionalEventListener、および Kafka と Spring Cloud Stream を用いた分散メッセージングを使用して、イベント駆動アーキテクチャ(EDA)パターンを実装します。

使用する場合

• Kafka メッセージングを使用したイベント駆動マイクロサービスの実装
• DDD アーキテクチャのアグリゲートルートからドメインイベントを発行
• データベースコミット後に発火するトランザクショナルイベントリスナーのセットアップ
• Spring Kafka 経由のプロデューサー・コンシューマーで非同期メッセージングを追加
• トランザクショナルアウトボックスパターンを使用した信頼性の高いイベント配信
• サービス間の同期呼び出しをイベントベースの通信に置き換え

クイックリファレンス

概念	説明
ドメインイベント	eventId、occurredAt、correlationId を持つ DomainEvent 基本クラスを拡張した不変イベント
イベント発行	ローカル向けは ApplicationEventPublisher.publishEvent()、分散向けは KafkaTemplate
イベントリスニング	信頼性の高い処理向けは @TransactionalEventListener(phase = AFTER_COMMIT)
Kafka	分散イベント消費向けの @KafkaListener(topics = "...")
Spring Cloud Stream	Consumer ビーンを使用した関数型プログラミングモデル
アウトボックスパターン	ビジネスデータとの原子的なイベント保存とスケジュール式パブリッシャー

例

モノリシックからイベント駆動への リファクタリング

変更前（アンチパターン）:

@Transactional
public Order processOrder(OrderRequest request) {
    Order order = orderRepository.save(request);
    inventoryService.reserve(order.getItems()); // ブロッキング
    paymentService.charge(order.getPayment()); // ブロッキング
    emailService.sendConfirmation(order); // ブロッキング
    return order;
}

変更後（イベント駆動）:

@Transactional
public Order processOrder(OrderRequest request) {
    Order order = Order.create(request);
    orderRepository.save(order);

    // トランザクションコミット後にイベントを発行
    eventPublisher.publishEvent(new OrderCreatedEvent(order.getId(), order.getItems()));

    return order;
}

@Component
public class OrderEventHandler {
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void handleOrderCreated(OrderCreatedEvent event) {
        // 注文が保存された後で非同期に実行
        inventoryService.reserve(event.getItems());
        paymentService.charge(event.getPayment());
    }
}

完全に動作する例については、examples.md を参照してください。

手順

1. ドメインイベントの設計

基本 DomainEvent クラスを拡張した不変イベントクラスを作成します：

public abstract class DomainEvent {
    private final UUID eventId;
    private final LocalDateTime occurredAt;
    private final UUID correlationId;
}

public class ProductCreatedEvent extends DomainEvent {
    private final ProductId productId;
    private final String name;
    private final BigDecimal price;
}

パターンについては domain-events-design.md を参照してください。

2. アグリゲートからのイベント発行

ドメインイベントをアグリゲートルートに追加し、ApplicationEventPublisher 経由で発行します：

@Service
@Transactional
public class ProductService {
    public Product createProduct(CreateProductRequest request) {
        Product product = Product.create(request.getName(), request.getPrice(), request.getStock());
        repository.save(product);

        product.getDomainEvents().forEach(eventPublisher::publishEvent);
        product.clearDomainEvents();

        return product;
    }
}

DDD パターンについては aggregate-root-patterns.md を参照してください。

3. トランザクショナルイベント処理

信頼性の高いイベント処理に @TransactionalEventListener を使用します：

@Component
public class ProductEventHandler {
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void onProductCreated(ProductCreatedEvent event) {
        notificationService.sendProductCreatedNotification(event.getName());
    }
}

検証: イベントハンドラーがトランザクションコミット後のみ発火することを確認します。ハンドラー実行前にデータベース状態がコミットされていることを確認してください。

処理パターンについては event-handling.md を参照してください。

4. Kafka インフラストラクチャの設定

KafkaTemplate で発行、@KafkaListener で消費するように設定します：

spring:
  kafka:
    bootstrap-servers: localhost:9092
    producer:
      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer

検証: KafkaTemplate 経由でテストイベントを送信し、コンシューマーログに表示されることを確認してから、本番環境パターンに進んでください。

dependency-setup.md および configuration.md を参照してください。

5. アウトボックスパターンの実装

原子的なイベント保存のための OutboxEvent エンティティを作成します：

@Entity
public class OutboxEvent {
    private UUID id;
    private String aggregateId;
    private String eventType;
    private String payload;
    private LocalDateTime publishedAt;
}

検証: スケジュール式プロセッサーが保留中イベントを取得することを確認します。スケジュール実行後に publishedAt タイムスタンプが設定されていることを確認してください。

スケジュール式プロセッサーが保留中イベントを発行します。outbox-pattern.md を参照してください。

6. 障害シナリオへの対応

リトライロジック、デッドレターキュー、べき等ハンドラーを実装します：

@RetryableTopic(attempts = "3")
@KafkaListener(topics = "product-events")
public void handleProductEvent(ProductCreatedEventDto event) {
    orderService.onProductCreated(event);
}

検証: リトライ回数を使い尽くした後、メッセージがデッドレタートピックに到達することを確認してから、監視可能性に進んでください。

7. 監視可能性の追加

分散トレーシング向けに Spring Cloud Sleuth を有効にし、メトリクスを監視します。

ベストプラクティス

• 過去形での命名を使用: ProductCreated（CreateProduct ではない）
• イベントを不変に保つ: すべてのフィールドは final である必要があります
• 相関 ID を含める: サービス間でのイベントトレーシング向け
• AFTER_COMMIT フェーズを使用: データベーストランザクション成功後のイベント発行を確保
• べき等ハンドラーを実装: 重複イベントを適切に処理
• リトライメカニズムを追加: 指数バックオフを使用した失敗時のイベント処理
• デッドレターキューを実装: リトライ後も失敗したイベント向け
• すべての障害をログ: デバッグ向けに十分なコンテキストを含める
• ハンドラーを順序非依存にする: 分散システムではイベント順序は保証されません
• イベント処理をバッチ化: 高ボリューム処理時
• イベント遅延を監視: 処理が遅い場合はアラートを設定

参考資料

• dependency-setup.md — Maven/Gradle 依存性
• configuration.md — Kafka と Spring Cloud Stream 設定
• domain-events-design.md — ドメインイベント設計パターン
• aggregate-root-patterns.md — イベント発行を使用したアグリゲートルート
• event-publishing.md — ローカルおよび分散イベント発行
• event-handling.md — イベント処理と消費パターン
• outbox-pattern.md — 信頼性向けトランザクショナルアウトボックスパターン
• testing-strategies.md — ユニットおよび統合テストアプローチ
• examples.md — 完全に動作する例
• event-driven-patterns-reference.md — 詳細なリファレンスドキュメント

制約と警告

• @TransactionalEventListener で発行されたイベントはトランザクションコミット後のみ発火します
• イベントに大きなオブジェクトを発行することは避けてください（メモリ圧力、シリアライゼーション問題）
• 非同期イベントハンドラーに注意（別スレッド、並行実行の問題）
• Kafka コンシューマーは重複メッセージを処理する必要があります（べき等処理を実装）
• 分散システムではイベント順序は保証されません（ハンドラーを順序非依存に設計）
• メインのトランザクションスレッドのイベントリスナーではブロッキング操作を実行しないでください
• イベント処理バックログを監視（システム容量の問題を示唆）

関連スキル

• spring-boot-security-jwt — セキュアなイベント発行向けの JWT 認証
• spring-boot-test-patterns — イベント駆動アプリケーションのテスト
• aws-sdk-java-v2-lambda — AWS Lambda を使用したイベント駆動処理
• langchain4j-tool-function-calling-patterns — AI 駆動のイベント処理