API 中継サービスの信頼性チェック

これは再利用できる作業テンプレートであり、特定の中継サービスに対する Folkbench の実測結果ではありません。Folkbench の評価事実となるのは、公開された実行（run）、日時、サンプル、制約を備えた公開スナップショットだけです。

目的

新しい API 中継サービスを本番環境の連携に組み込む前に、最小限のリクエスト経路が動作することを確認し、失敗をクライアント、プロトコル、上流、サービスの 4 種類に分類します。受け入れ確認の結果は、別のエンジニアが同じリクエストで再確認できるものにしておきます。

始める前に

実際のユーザーデータを含まない、固定のリクエストサンプルを用意します。モデル ID、リクエストボディ、ストリーミングの有無、タイムアウト、リトライ回数の上限、テスト日時を記録してください。テスト用の認証情報はローカルのシークレットマネージャーか一時的な環境変数にだけ置き、ログ、スクリーンショット、リポジトリ、公開ページには決して書き込まないでください。

ステップ 1：リクエストと観測の範囲を固定する

まず最小限のリクエストで、HTTP ステータスコード、レスポンスヘッダー、レスポンスボディがプロバイダーのドキュメントどおりかを確認します。リクエスト ID、モデル ID、ステータスコード、合計所要時間をテストシートに記録します。完全な Authorization ヘッダーや生のレスポンスを、そのままチケットに貼り付けないでください。

エンドポイントがストリーミングに対応している場合は、ストリーミングのリクエストを別に 1 回実行します。最初の有効なデータチャンクが届くまでの時間、チャンクが途切れずに届き続けるか、完了イベントが現れるか、接続が閉じたときにクライアントが明確な結果を受け取れるかを記録します。SSE はイベントストリームです。ネットワークのパケットの区切りからトークンを推測するのではなく、イベントの境界に沿ってパースしてください。

ステップ 2：失敗を分類する

固定の入力を使って、次のケースをそれぞれ確認します。

1. クライアントエラー：存在しないモデル、パラメーターの欠落、リクエスト上限の超過には、原因を特定できる 4xx の結果が返るべきです。
2. 認証エラー：期限切れや権限不足の認証情報ははっきり拒否されるべきで、レスポンスに他の認証情報や内部アドレスが漏れてはいけません。
3. 上流エラー：上流のタイムアウト、レート制限、一時的な障害では、リトライ可能か不可能かを区別できる必要があります。
4. ストリーミングの異常：接続の中断、完了イベントの欠落、途中で切れた JSON イベントは、完了したテキストとして扱わず、必ず失敗の経路に入れます。

失敗ごとに、少なくともステータスコード、エラー分類、クライアント側の観測時刻、マスキング済みの短い要約を残します。生のレスポンス、トレース、スクリーンショットはプロセスのエビデンスです。プロジェクトの非公開オブジェクトストレージの手順に沿って保存し、公開記事やランキングには載せないでください。

ステップ 3：リトライの範囲を決める

自動リトライの対象にするのは、冪等性が明確なリクエストか、安全に繰り返せるリクエストだけです。リトライには全体の予算を設け、最初と最後のリクエスト ID を関連付けて記録します。認証の失敗、不正なパラメーター、コンテンツポリシーによる拒否は、やみくもにリトライしないでください。

読みやすい受け入れチェック表には、たとえば次の項目を入れられます。

合格基準と後片付け

合格基準はテストの前に書いておきます。たとえば「固定リクエストが 3 回の独立した試行のすべてで完全な結果を返し、ストリーミングには明確な完了イベントがあり、認証の失敗はリトライされない」といった形です。結果を見てから基準を変えないでください。

テストが終わったら一時的な認証情報を失効させ、ローカルに残った生のレスポンスを削除し、要約、タイムスタンプ、バージョンだけを含む受け入れ記録を残します。結果を Folkbench に公開するには、先に実際の run/attempt、エビデンスのマニフェスト、公開スナップショットを関連付ける必要があります。この記事がそれらの事実の代わりになることはありません。