外部IF メッセージング仕様

目的: 外部システムとの非同期メッセージング連携における仕様を明確に定義し、メッセージフォーマット、配信保証、エラー処理などの実装要件を開発チームが共通理解できるようにする
スコープ: メッセージキュー/トピックを介した外部システムとの非同期データ連携を対象とする。メッセージフォーマット、配信保証レベル、エラーハンドリング、監視要件をカバーする。同期APIによるリアルタイム連携は対象外
推奨する実施タイミング: 外部インターフェース設計の段階で、連携方式が非同期メッセージングと決定された後に実施する
関連するステークホルダー: システムアーキテクト、外部システム担当者、インフラチーム、運用チーム

📥 重要な前提知識・インプット

前提知識: メッセージング基盤(SQS、RabbitMQ、Kafka等)の基本概念、配信保証モデル(At-least-once、At-most-once、Exactly-once)、冪等性の概念、JSONスキーマ、非同期処理パターン
インプット: 外部インターフェース一覧、連携先システムの要件定義書、メッセージング基盤の技術仕様、非機能要件(スループット、レイテンシ要件)

📄 成果物の定義

ドキュメントテンプレート: 📄[テンプレ]外部IF メッセージング仕様
必須要素: メッセージングIF一覧表、メッセージフォーマット定義(JSONスキーマ)、メッセージシーケンス図、配信保証方式、エラーハンドリング仕様、リトライポリシー、監視項目定義

✅ 品質基準・レビュー観点

✅ 品質チェックリスト:

チェック項目	チェック内容
メッセージフォーマット	JSONスキーマが明確に定義され、バリデーションルールが記載されているか
冪等性保証	重複メッセージを受信した場合の冪等性処理が設計されているか
エラーハンドリング	リトライポリシー、Dead Letter Queue、エラー通知方法が明確か
監視・運用性	メッセージ滞留、処理失敗率などの監視項目とアラート基準が定義されているか
データ整合性	メッセージ順序保証の要否と実現方式が明確か

👁️‍🗨️ レビュー観点:

連携先との合意: 外部システム側とメッセージフォーマット、配信保証レベル、エラー処理方式について合意が取れているか
非機能要件の充足: スループット、レイテンシ、可用性の要件を満たす設計になっているか
運用容易性: メッセージ追跡、障害時の再送、Dead Letter Queueの監視など運用手順が明確か
セキュリティ: メッセージの暗号化、認証・認可方式が適切に設計されているか

🧪成果物のサンプル

# IF-002: 注文データ連携

**概要:**
本システムで登録された注文情報を基幹システムへ非同期で連携するメッセージングインターフェース。注文の登録・更新・キャンセル等のイベントが発生した際に、メッセージキューを介して基幹システムへデータを送信し、在庫管理や出荷処理に連携する。

**メッセージング基盤:**
- 使用技術: [例: AWS SQS、RabbitMQ、Kafka等]
- キュー名/トピック名: `order-events`

**メッセージフォーマット:**
```json
{
  "event_type": "order_created",
  "event_id": "evt_12345",
  "timestamp": "2025-11-20T15:00:00Z",
  "payload": {
    "order_id": "order_98765",
    "customer_id": "cust_11111",
    "total_amount": 15000,
    "items": [
      {
        "product_id": "prod_001",
        "quantity": 2,
        "unit_price": 5000
      }
    ]
  }
}
```

**配信保証:**
- At-least-once 配信
- 重複メッセージの冪等性処理が必要

**エラー処理:**
- 処理失敗時はDead Letter Queueへ移動
- 最大リトライ回数: 3回

**監視項目:**
- メッセージ滞留数
- 処理失敗率
- 平均処理時間

---

🔄 設計の進め方・プロセス

🏗️ プロセス1: メッセージングIF一覧とメッセージフロー設計

設計対象:

外部システムとのメッセージング連携の全体像を把握し、各IFのメッセージフローを定義する。

具体例:

どの外部システムとどのようなデータを連携するか(注文データ、在庫情報、顧客情報など)
メッセージの送受信方向(送信のみ、受信のみ、双方向)
イベント発生のトリガー(ユーザー操作、バッチ処理、外部システムからの通知など)
メッセージング基盤のキュー名/トピック名
メッセージの発行元と購読者(Producer/Consumer)の役割分担

設計原則:

責務の明確化: 各メッセージが「何のイベント」を表すのか、どのシステムが「発行責任」と「処理責任」を持つのかを明確にする
疎結合の維持: 送信側と受信側が直接依存しないよう、メッセージング基盤を介した非同期連携とする
イベント駆動設計: ビジネスイベント単位でメッセージを定義し、システム間の結合度を下げる
順序保証の検討: メッセージの順序保証が必要かどうかを判断し、必要な場合はパーティションキーやメッセージグループIDを設計する

文書化の推奨表現:

IF一覧表の作成: IF ID、連携先システム、メッセージ名、送受信方向、イベント種別、キュー/トピック名を一覧化する
メッセージフロー図: システム間のメッセージの流れをシーケンス図またはフロー図で視覚化する
トリガー条件の明記: どのような条件でメッセージが発行されるかを具体的に記載する
設計判断の記録: なぜ非同期連携を選択したのか、同期APIとの比較結果を残す

🏗️ プロセス2: メッセージフォーマット・JSONスキーマ定義

設計対象:

メッセージの具体的なデータ構造をJSONスキーマで定義し、バリデーションルールを明確にする。

具体例:

メッセージに含める項目(event_type、event_id、timestamp、payload等)
各フィールドのデータ型(string、integer、array、object等)
必須項目とオプション項目の区別
文字列長、数値範囲、列挙値などのバリデーションルール
ネストした構造(配列内のオブジェクト等)の定義

設計原則:

後方互換性の確保: フィールド追加は可能だが削除・変更は互換性を損なうため、初期設計を慎重に行う
必須項目の最小化: 将来の拡張性を考慮し、必須項目は最小限に留める
バージョニング戦略: メッセージフォーマットのバージョン情報(schema_version等)を含める
明確な命名規則: フィールド名はスネークケースで統一し、略語を避けて意味が明確な名前を付ける
タイムスタンプの標準化: ISO 8601形式(UTC)を使用し、タイムゾーンの曖昧さを排除する

文書化の推奨表現:

JSONスキーマの提供: JSON Schemaフォーマットで正式なスキーマ定義を記載する
サンプルJSONの提示: 実際のメッセージ例をJSON形式で提示し、理解を助ける
フィールド定義表: 各フィールドの説明、データ型、必須/任意、制約条件を表形式で整理する
バージョン管理方針: スキーマ変更時のバージョニングルールと移行方針を明記する

🏗️ プロセス3: 配信保証・エラーハンドリング・監視設計

設計対象:

メッセージの配信保証レベル、エラー時の処理方式、運用監視の要件を定義する。

具体例:

配信保証レベル(At-least-once、At-most-once、Exactly-once)の選定
冪等性キー(event_id等)の設計と重複メッセージの処理方法
リトライポリシー(最大リトライ回数、リトライ間隔、バックオフ戦略)
Dead Letter Queue(DLQ)への移動条件と運用手順
メッセージの可視性タイムアウト設定
監視メトリクス(メッセージ滞留数、処理失敗率、平均処理時間等)とアラート閾値

設計原則:

冪等性の実装: At-least-once配信の場合、受信側で冪等性を保証する設計とする
段階的リトライ: 一時的なエラーは自動リトライし、恒久的なエラーはDLQへ移動して人間が対応する
Dead Letter Queueの運用: DLQに蓄積されたメッセージの調査・再送手順を明確にする
タイムアウト設計: 処理時間に応じた可視性タイムアウトを設定し、重複処理を防ぐ
アラート設計: 異常な滞留や失敗率上昇を早期検知できる監視とアラートを設計する

文書化の推奨表現:

配信保証方式の明記: 採用する配信保証レベルとその理由を記載する
エラーハンドリングフロー図: エラー発生時の処理フロー(リトライ→DLQ移動→通知)を図示する
リトライポリシー表: リトライ回数、間隔、バックオフアルゴリズムを具体的に定義する
監視ダッシュボード要件: 監視すべきメトリクス、可視化方法、アラート閾値を一覧化する
運用手順書: DLQメッセージの調査方法、再送手順、エスカレーション基準を記載する

🚨 よくある失敗と予防策　

🚧 実例収集後、追記予定

📚 参考資料・関連リンク

参考文献: 『エンタープライズ統合パターン』、『Building Event-Driven Microservices』、AWS/Azure/GCPの各メッセージングサービス公式ドキュメント
関連する他のガイド: 外部インターフェース設計ガイド、非機能要件の実現方式、システムアーキテクチャ設計、セキュリティ仕様・方式
ツール・テンプレート: draw.io、PlantUML(シーケンス図)、JSON Schema Validator、Mermaid(フロー図)

テンプレートサイト: 📄テンプレート集