プロトコルファースト設計

プロトコルファーストとは

プロトコルファースト（Protocol-first）とは、コンポーネント（サービス、顧客、外部パートナー）間のインタラクション契約を実装前に設計および修正するアプローチです。コード、ストレージ、インフラストラクチャ、ドキュメントは契約の対象となり、その契約から自動的に生成されます。

APIがコードの副産物であるcode-firstとは異なり、Protocol-firstは、ドメインコンセプト、データモデル、ステータス、エラー、idempotencyセマンティクス、SLO/SLI、さらにはバージョンポリシーを所有しています。

なぜ必要なのか？

組織全体のインターフェイスの一貫性と予測可能性。

迅速なオンボーディング（SDK/stable/client autogeneration、 uniform errors and code）

信頼できる進化（スキーム、テスト契約、クリアバージョンポリシーの互換性）。
Product Focus：コード作成前の動作、SLA、 UX統合について説明します。
自動化：CI/CDは、真実の単一のソースからアーティファクト（クライアント、サーバスタブ、バリデータ）を収集します。
セキュリティとコンプライアンス：権利、PIIマスキング、保持ポリシーは契約に安置されています。

コアアプローチ

1.シングルソースオブトゥルース（SSOT）-機械読み取り可能な仕様：

REST： OpenAPI/JSONスキーマ。
イベントとストリーミング：AsyncAPI、 Avro/JSONスキーマ。
RPC： Protobuf （gRPC）、 Thrift、 Smithy。
GraphQL： SDL+ディレクティブ/ポリシー。
2.実装前のアレンジ：ドメイン用語集、エラーコード、idempotencyセマンティクス、締め切り、再試行、重複排除。
3.Autogeneration：クライアント/サーバスタブ、タイプ、SDK、テストコントラクト、moks、 Postmanコレクション、Terraform/OpenAPI Gateway構成。
4.ガバナンス：linters/policies（ネーミング、ページネーション、フィルタ、エラー）、APIギルドによるレビュー、メジャーバージョンの変更アドバイザリー。
5.互換性：「additive-only」拡散の厳密な検証、セマンティックバージョニング、カナリア/コンシューマー主導のテスト。
6.契約レベルでの観察可能性：相関ID、エラーモデル、遅延予算がプロトコルに綴られています。

プロセスがどのように見えるか（スケルトン）

1.開始：製品概要→ユーザージャーニー→API/PRD（リソース/メソッド/イベント、SLA/SLO、エラー、制限）。
2.モデリング：ドラフト仕様（OpenAPI/AsyncAPI/Proto）+データスキーマ、用語辞書。
3.契約とUXの統合：ペイロードの例、エラーの契約、ステータスマップ、バージョン管理ルール。
4.レビューとガバナンス：linters/standards、ドメイン不変量の議論、ロックインMGC（最低保証契約）。
5.アーティファクトの自動生成：SDK、スタブ、テスト修正、インフラストラクチャスタブ（ゲートウェイ、IAMスコープ）。
6.実装テストと契約テスト：サプライヤーと消費者は、CIで互換性チェックを受けます。
7.観測性とSLO：相関IDトレース、エラーカタログ、リトレイ/タイムアウト予算。
8.リリースと進化：additive-first、 rejection policy、 canary、 A/B capability flags。

インタラクションプロトコルとスタイル

REST/HTTP

標準：リソースモデル、'GET/POST/PATCH/DELETE'、ページネーション（カーソル）、フィルタ、並べ替え。
フィールドとスキーム：JSONスキーマ、フォーマット（'date-time'、 'uuid'）、不変量（regex/enum/min-max）。
エラー：単一のフォーマット（'type'、 'code'、 'title'、 'detail'、 'trace_id'）、 HTTPスタックへのマッピング。
変更制御：ETag/If-Match、 POSTのidempotentキー、明示的な意味409/422。

gRPC/RPC

Protobuf：安定したタグ番号付け、'optional'、削除されたフィールドの再利用を許可しません。
契約の締め切りと優先順位；安定した状態（OK、 INVALID_ARGUMENT、 FAILED_PRECONDITION、等）。
ストリーミング：メッセージの順序の指定、backpressure、最終的なトレーラー。

イベント駆動型（カフカ/NATS/SNS/SQS）

AsyncAPI： テーマ/チャンネル、パーティションキー、重複排除キーの規則、リテンション、正確に1回のセマンティクス「vs少なくとも1回」

コアイベントとエンリッチメント： 個別の最小ペイロードと拡張；バージョン'event_type'/'schema_version'

Idempotency： 'event_id'、 'producer_id'、リトレイと重複除外のポリシー。

GraphQL

コントラクトとしてのSDL、非推奨のためのディレクティブ、深さと複雑さの制限、エラーコード/拡張コントラクト。

建築理念との統合

Inverse Pyramid/Critical Path First：仕様では、MGC（必須最小）、拡張-through？include='/capabilities。
舗装された道路：既製の仕様テンプレート（支払い、KYC、監査、検索、ファイル）+lintersのセット。
APIゲートウェイとサービスメッシュ：契約ベースのポリシー（rate-limit、 auth scope、 retries、 circuit-breakers）。

バージョン管理と進化

• マイナー=添加フィールド/チャンネルのみ。
• Major=breaking changes（削除、名前変更、セマンティクスの変更）。
• 拒否ポリシー：サポートウィンドウ、'Sunset'ヘッダー、通知イベント。
• 消費者主導の契約（CDC）：現在のAPIが特定の消費者を満足させることを確認します。
• スキーマディレクトリ：スキーマレジストリ/アーティファクトレジストリ履歴と互換性ルール（BACKWARD/FORWARD/FULL）。

安全性とコンプライアンス

契約の一部としての認証/承認（OAuth2/OIDCスコープ、mTLS、 JWTクレーム）。
PII/PCI：マスキング、トークン化フォーマット、特殊なストレージモード/TTLを持つフィールド。
監査ポリシー：必須属性（'actor'、 'subject'、 'action'、 'overced_at'、 'trace_id'）。
制限：レートリミットヘッダー、クォータ、メッセージサイズ、期限。

契約の可視性

相関/Request-ID：仕様に必要です。
エラーカタログ-解決するコードとSLAの固定リスト。
SLI/SLO： p50/p95レイテンシ、成功した応答の割合、互換性のあるイベントの割合、idempotentリピートの割合。

テストと品質

契約テスト（プロバイダ↔消費者）、CIのスキーマ差分、モックサーバの生成。
ゴールデンサンプル：要求/応答の参照例、e2eのための据え付け品。
カオス/レイテンシーインジェクション：タイムアウト/リトレイチェック、MGC保存時の拡張機能の劣化。

サンプルドメインテンプレート

お支払い（REST+イベント）

'POST/payments'→'201 Created' with 'payment_id'、 'status=authorized'。
イベントの支払い。承認されました。'{payment_id、金額、通貨、メソッド、occurred_at}'。
延長の支払い。豊かになりました。v1'：リスクレート、地理、デバイス指紋。
エラー：'422'（検証）、'402'（支払いが必要）、'409'（重複）。
SLA：承認≤ 800ms p95；カーネルイベント≤ 2c lag p95です。

KYC （gRPC+キュー）

RPC 'StartVerification （user_id）'→'operation_id'。
トピック'kycのプログレスイベント。ステータス。v1'（'保留中'→'承認/拒否'）。
契約は、PIIフィールド、保存期間、マスキング、因果障害コードを規定しています。

監査（イベントのみ）

「オーディット」記録された。v1'：'actor'、'subject'、'action'、'overced_at'、'trace_id'。
Enrichment： IP、 device、 geo-別のイベント/スレッドで、カーネルをブロックしません。

ツールとオートメーション（おおよそのスタック）

技術：OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL。
Spectral、 OpenAPI Diff、 Buf （protobuf）、 Confluent SR互換性チェック。
Генерация： OpenAPI Generator、 Buf/A、 GraphQL Codegen、 AsyncAPI Generator。
ゲートウェイ：Kong/Apigee/Azure/GCP GW、 Envoy。
技術：Pact/CDC、 Dredd、 Schemathesis、 Hoverfly、 MockServer。
レジスタ：スキームのGitディレクトリ+スキーマレジストリ/アーティファクトレジストリ。
ドキュメント：Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer。

アンチパターン

偶然のコードファースト：「MVP first on controller」、事後事実仕様、ドキュメントと動作の不一致。
Swagger-wash：実際のルール（エラー、制限、SLA、バージョン）のない正式なOpenAPI。
互換性の破断：メジャーバージョンなしで削除されたフィールド/変更されたタイプ；protobufタグを再利用します。
ペジネーション/フィルタなしの「厚い」応答。独自性の欠如。
Off-contract security： auth/Scopeはwikiに記述されていますが、仕様には記載されていません。

プロセス組織との関係

APIギルド：標準評議員、変更レビュー、トレーニング。
設計ドキュメント：各API-PRD、 ADR（ソリューション）、SLA、リスクマトリックス。
変更管理：RFCプロセス、リリースノート、移行ガイド、偏差タイムライン。
Paved Road&Templates：仕様からのサービスフレームワークジェネレータ（ハンドラスケルトン、検証、ロギング）。

チェックリスト

開始前

• PRDとドメイン用語集があります。
• 選択したスタイル（REST/gRPC/Event/GraphQL）とスキーマ形式。
• MGC、エラー、SLA/SLO、 idempotencyルール定義。

開発中

• 指定はlintersおよびレビューを渡します。
• SDK/Stable/Fixtureの自動生成が設定されています。
• 契約テスト（CDC）はCIに含まれています。schema-diffは互換性のない変更をブロックします。

リリース前

• 例とエラーコードを含むインテグレータドキュメント。
• 契約上の観察可能：相関ID、エラーカタログ、SLIダッシュボード。
• バージョン管理ポリシーと非推奨が宣言されています。

よくあるご質問

Protocol-firstとAPI-firstの違いは何ですか？
多くの場合、用語は相互に使用されます。Protocol-firstの下のこの記事では、契約の厳格さとSLA、安全性と観測性を含むすべてのスタイル（REST/RPC/Events/GraphQL）のカバレッジを強調しています。

これは開発を遅らせるでしょうか？
スタートは少し長いかもしれませんが、統合、安定性、並列開発速度（自動生成、安定したSDK）で勝っています。

迅速な実験で何をすべきか？
スキーム（ドラフト）、フィーチャーフラグ、サンドボックスの「ドラフト」バージョンを使用しますが、Linterや基本的な互換性ルールはスキップしません。

合計

プロトコルファースト設計は、コントラクトをアーキテクチャの中心にします。行動の調整、スキームの修正、生成とテストの自動化、追加的な進化を行います。その結果、予測可能な統合、高速な開発、システムのスケールとコマンドの変更に対する耐性が得られます。