[章番号]: [イベント名/キュー名] メッセージング仕様書
このテンプレートの使い方
このファイルは、RabbitMQ, Kafka, SQSのようなメッセージブローカーを介した非同期通信の仕様を定義するためのテンプレートです。 パブリッシャー（発行者）とサブスクライバー（購読者）間の「メッセージの契約」を定義することに重点を置きます。 詳しい使い方は「設計仕様の書き方ガイド」を参照してください。
1. はじめに
1.1. 目的
1.2. 対象読者
2. 基本情報
| 項目 | 内容 |
|---|---|
| メッセージブローカー | [例: RabbitMQ, Apache Kafka, AWS SQS] |
| データ形式 | [例: JSON (CloudEvents 1.0 形式)] |
| 認証方式 | [例: SASL/PLAIN, mTLS] (詳細はAPI設計共通ガイドラインを参照) |
3. ルーティング情報
| 項目 | 値 | 説明 |
|---|---|---|
| Exchange / Topic | [例: user-events] |
メッセージが発行されるエクスチェンジ名またはトピック名。 |
| Routing Key | [例: user.created.v1] |
メッセージの種別を示すルーティングキー。 |
| Queue(s) | [例: analytics-service-queue, notification-service-queue] |
このメッセージを購読するキューの一覧。 |
4. メッセージ仕様
4.1. [イベント名] (例: user.created)
-
概要:
新しいユーザーアカウントが正常に作成されたときに発行されます。
-
メッセージボディ (ペイロード):
{
"id": "user-001",
"name": "Taro Yamada",
"emailHash": "a1b2c3d4...",
"registeredAt": "2025-07-28T12:00:00Z"
}
| フィールド名 | 型 | 必須 | 説明 |
|---|---|---|---|
id |
string | Yes | 新しく作成されたユーザーの一意なID。 |
name |
string | Yes | ユーザー名。 |
emailHash |
string | Yes | プライバシー保護のため、ハッシュ化されたメールアドレス。 |
registeredAt |
string | Yes | 登録日時 (ISO 8601形式)。 |
- メッセージヘッダ / 属性:
| ヘッダ名 | 値の例 | 説明 |
|---|---|---|
specversion |
1.0 |
CloudEventsのバージョン。 |
type |
com.example.user.created |
イベントの種別。 |
source |
/users/service |
イベントの発行元サービス。 |
subject |
user-001 |
イベントの主題（ユーザーID）。 |
id |
uuid-goes-here |
イベントの一意なID。 |
time |
2025-07-28T12:00:00Z |
イベントの発生日時。 |
datacontenttype |
application/json |
ペイロードのデータ形式。 |
5. パブリッシャー (発行者)
User-Service
6. サブスクライバー (購読者)
Analytics-Service: ユーザー登録イベントを分析データとして記録する。Notification-Service: 新規ユーザーに歓迎メールを送信する。
7. エラーハンドリングとべき等性
- 再試行ポリシー: サブスクライバーは、処理に失敗した場合、指数バックオフ戦略を用いて最大3回まで再試行します。
- デッドレターキュー (DLQ):
3回再試行しても成功しないメッセージは、
user-events-dlqキューに転送されます。 - べき等性 (Idempotency):
サブスクライバーは、CloudEventsの
idをキーとして、処理済みのイベントIDを一定期間キャッシュします。同じIDのイベントを再度受信した場合は、処理をスキップします。