external-api-adapters

外部 API アダプター

コードがプロセスやベンダーの境界を越える場合に、このスキルを使用します。

基本ルール

• 外部 API はアダプターの背後に配置します。ドメインコードやユースケースコードは、SDK や HTTP クライアントの詳細ではなく、ポートに依存させます。
• 境界で外部 DTO を内部のドメイン型またはアプリケーション型に変換します。
• 外部エラーを少数のアプリケーションエラーに正規化します。
• すべてのネットワーク呼び出しに明示的なタイムアウトを設定します。
• リトライの動作は、意図的かつ制限付きで、操作に対して安全なものにします。
• 相関 ID、リクエスト ID、ベンダー ID、ページネーションカーソルを構造化された証拠として記録します。
• 認証情報や機密性の高い生のペイロードを、ログ、スナップショット、スローするメッセージに含めないようにします。

アダプターの形

export interface ErpCustomerGateway {
  fetchCustomer(id: CustomerId): Promise<ExternalCustomerResult>;
}

export class HttpErpCustomerAdapter implements ErpCustomerGateway {
  async fetchCustomer(id: CustomerId): Promise<ExternalCustomerResult> {
    // HTTP or SDK details stay here.
  }
}

外部の機能または境界づけられた統合ごとに、アダプターを 1 つ用意することを推奨します。無関係な操作を混在させた大規模な「ベンダークライアント」クラスは避けてください。

境界チェックリスト

• アプリケーションの外部に渡る前に、入力を検証します。
• アプリケーションに入る前に、出力を解析して検証します。
• タイムアウトを設定し、テストします。
• 操作ごとにリトライポリシーを文書化します。
• 冪等でない呼び出しには、冪等性キーを使用するか、自動リトライを行いません。
• ページネーションとカーソルには、決定的な終了条件を設けます。
• レート制限レスポンスを明示的に処理します。
• ログには操作、外部システム、リクエスト ID、安全な識別子を含めます。
• アダプターには、成功、検証失敗、タイムアウト、リトライ可能な失敗、リトライ不可能な失敗、不正なレスポンスのテストを用意します。

リトライのガイダンス

操作が冪等であるか、冪等性キーがある場合にのみリトライします。検証失敗、認証失敗、認可失敗、または恒久的なビジネスルールに関するレスポンスはリトライしないでください。

一時的なネットワーク障害や 5xx レスポンスに対しては、ジッターを加えた少数の回数に制限されたリトライを使用します。失敗が繰り返された場合は、型付きアプリケーションエラーとして通知します。

エラーの正規化

ベンダー固有の詳細をアプリケーションエラーにマッピングします。

type ExternalServiceError =
  | { kind: "unavailable"; retryAfterMs?: number; requestId?: string }
  | { kind: "unauthorized"; requestId?: string }
  | { kind: "not-found"; requestId?: string }
  | { kind: "invalid-response"; requestId?: string; reason: string };

アダプターの契約で明示的に公開されている場合を除き、アプリケーションの他の部分で SDK の例外名や生の HTTP ステータスコードに応じた分岐を行わないでください。

テストのガイダンス

• 焦点を絞ったフィクスチャを使って、マッピングとエラーの正規化をユニットテストします。
• 実際の外部レスポンス形式、または記録した外部レスポンス形式には、コントラクトテストを使用します。
• フェイククライアントは、アサーションだけのモックではなく、振る舞いに基づいて作成します。
• 不正なレスポンス、一部のみのレスポンス、予期しないレスポンスに対するネガティブフィクスチャを含めます。
• 運用チームが必要とする場合は、失敗時の可観測性フィールドを検証します。

よくある間違い

• 外部 DTO を変更せずにアプリケーション内へ渡す。
• 冪等でない操作をリトライする。
• 空の配列や undefined によって部分的な失敗を隠す。
• すべての 4xx レスポンス、またはすべての 5xx レスポンスを同じように扱う。
• ユースケースコードやドメインコード全体に SDK のインポートを追加する。