architecture-paradigm-client-server

クライアント・サーバーとピアツーピアのパラダイム

このパラダイムを採用する場面

• Web クライアントやモバイルクライアントがバックエンド API と通信するような、サービスを一元化した従来型のアプリケーションに適しています。
• ピアツーピア同期に依存する、分散型または「オフラインファースト」機能を検討するシステムに適しています。
• 信頼境界、クライアント・サーバー間のバージョンネゴシエーション、API の進化戦略を正式に文書化する場合に適しています。

使用しない場面

• UI とロジックの間にネットワーク境界がないシステム（ archetypes:architecture-paradigm-modular-monolith を使用してください）
• そもそもパラダイムを選ぶ場合（ archetypes:architecture-paradigms を使用してください）

採用手順

1. 責務を定義する：重複を最小限に抑えることを目指し、クライアントとサーバーのどちらにロジックやデータが存在するかを明確に区分します。
2. コントラクトを文書化する：さまざまなクライアントバージョンに対応するために必要な API、データスキーマ、認証フロー、機能ネゴシエーションをすべて正式に文書化します。
3. バージョンの不一致に備える：フィーチャーフラグ、コンテンツネゴシエーション用の Accept ヘッダー、API のセマンティックバージョニングなどを使って、異なるクライアントバージョンとサーバーバージョンを管理する戦略を実装します。
4. 接続の問題に対処する：アプリケーションが純粋なクライアント・サーバー型でない場合は、断続的な接続を想定して設計します。これには、オフラインキャッシュ、データ同期プロトコル、ピアの検出とメンバーシップサービスの実装が含まれることがあります。
5. すべての通信を保護する：転送中のすべてのデータに TLS を使用します。すべてのエンドポイントに認可ポリシー、レート制限、詳細なテレメトリーを実装します。

主な成果物

• クライアント、サーバー、ピアの役割を扱い、信頼境界を定義し、デプロイに関する前提をまとめたアーキテクチャ決定記録（ADR）。
• 正式な API またはプロトコル仕様と、一連の互換性テスト。
• クライアントの段階的なリリース、後方互換性のサポート、ピアツーピアネットワークの運用手順など、ロールアウトに必要な調整を詳述したランブック。

リスクと軽減策

• 「おしゃべりな」クライアント：
  • 軽減策：クライアントが小さなリクエストを過剰に送信すると、パフォーマンスが低下する可能性があります。ファサードやゲートウェイなどのパターンを使って API 呼び出しをまとめ、クライアント側またはネットワークエッジでキャッシュ戦略を実装します。
• ロジックが重複した「厚い」クライアント：
  • 軽減策：クライアントにビジネスロジックが多すぎると、重複が生じ、サーバーとの不整合につながることがよくあります。検証ロジックを共通ライブラリとしてパッケージ化して共有するか、ルールをサーバー側に明確に移します。
• ピアツーピアのデータ競合：
  • 軽減策：ピアツーピアモデルでは、データ競合は避けられません。正式な競合解決戦略（CRDT、最終書き込み優先など）と合意形成メカニズムを初期段階から設計します。

具体的なコンポーネント

このパラダイムの実装で一般的に使われるツールや抽象化の用語です。依存関係ではなく、tools: フロントマターでもありません。

• api-contract-generator：クライアントとサーバーが共有する、機械可読な OpenAPI/RPC コントラクトを生成します
• networking-debugger：遅延、再試行、タイムアウトの問題を診断するために、リクエストとレスポンスのトレースを取得します

終了条件

• クライアントの役割、サーバーの役割（該当する場合はピアの役割も）、信頼 境界、選択した API バージョニング戦略を明記した ADR が作成されている。
• 文書化されたすべてのエンドポイントまたは機能を網羅する、正式な API またはプロトコル仕様（OpenAPI、protobuf など）が存在する。
• バージョン不一致への対応戦略（フィーチャーフラグ、Accept ヘッダー、セマンティックバージョニング）を、クライアントまたはサーバーのコードを書く前に文書化している。
• オフラインファーストまたは P2P 機能を含める場合、競合解決戦略（CRDT、 最終書き込み優先、または合意形成メカニズム）を ADR に明記している。