AdapterとGateway
Adapterは、既存のAPIやクラスのインターフェースを、利用側が必要とするインターフェースへ変換します。Gatewayは、外部システムや資源へアクセスする単一の入口です。外部API連携では一つの実装が両方の役割を持つことがありますが、目的は区別します。
採用する場面
- 外部API、SDK、データベース、ファイル形式の型や命名が内部モデルと異なる
- 外部仕様の変更を複数の利用箇所へ波及させたくない
- 外部エラーを、アプリケーションが判断できる失敗へ変換する
- テストで外部I/Oを置き換える明確な境界が必要になる
一か所だけの単純な呼び出しを、名前を変えるだけのクラスで包みません。変換する契約や隔離する変化がない場合、薄いラッパーは追跡箇所を増やすだけです。
実装方針
- 利用側の語彙と必要最小限の入出力でAPIを定義する
- 外部SDKの型、レスポンス、例外を境界の内側へ閉じ込める
- 外部データから内部モデルへの変換と検証を一か所に置く
- timeout、再試行、冪等性、rate limitは外部サービスの契約に合わせて明示する
- ログへ資格情報や外部レスポンス全体を無条件に残さない
Adapterは互換性の変換、Facadeは複数機能に対する簡単な入口です。外部アクセスを隠しただけでFacadeとは呼びません。