初心者がAPIの例外処理を行う場合の考え方

webエンジニアになりたての頃、例外についてどう考えたら良いか分からなかったので
そういう人のための記事。

サービスの機能要件、非機能要件に応じて対応を変える必要があるため、
一概に「これが正解」とは言えないが、良い実装に至るための考え方を紹介する。

この記事では、「APIからデータを取得し、Webページを表示するシステム」を想定して記載する。

ユーザーへの表示の仕方

まず大前提として、APIリクエストに失敗した場合に
Webページがフレームワークのエラー画面を表示するような状態は言語道断である。

理由は２つある。

大抵の場合は、以下のどれかが良いと考えられる。

エラー画面の場合、ユーザーには次に取るべきアクションをメッセージで教えてあげると親切である。

大きく分けて以下の３パターンが考慮されていることが大切で、
発生する可能性によって準正常系とするのか異常系とするのか判断すると良い。

まずはAPIの仕様書を見て、返ってくる可能性のあるステータスコードを理解しておく必要がある。

よく404の例外をどうするか迷うところだが、筆者は以下のように判断している。

取り扱うAPIがどういうポリシーで実装されているかと、
そのAPIを利用する側でどういう想定をしているのか、というところが判断のポイントだ。

大抵のライブラリはAPIから4XX,5XXが返却された場合、例外を投げるような仕様になっているため
テキトーに利用せず、キャッチした後どうするかを考えなければいけない。

まず、リクエストする側で「APIのレスポンスを待つまでは〇〇ms」と
タイムアウトの時間を決めておくのが良い。

この場合は以下３点のどれかに改善余地があり、発生しない方が良いことなので異常系（例外）として扱う。

この世に「絶対に障害が発生しないシステム」は存在しないため、
このケースも考慮しておかなければならない。

ただし、これについても発生しない方が良いことなので異常系として扱う。

本番環境などでエラーが発生した場合、必ずその原因を調査しなければならない。

エラーログをいい加減に出力しておくと「後で調査できない」という痛い目を見ることになる。

発生時刻（これはログ出力の仕組みで出しておく）
接続先API
APIリクエストした時のURLやリクエストボディ
- 同じ状況を後から再現して確かめられるように
- ただしユーザー名やメールアドレスなど機密情報は出力しないように
何がダメだったのか
取得しようとしたデータのIDなど
１リクエストごとに発行される、ログをトレースするためのID
例外が発生した時のスタックトレース

さらに、独自で例外クラスを定義しておくという方法も組み合わせると良い。

ログに出力される例外クラス名で、どこで何が発生したのかが推測しやすくなる
例外クラスのフィールドにデータのIDなどを入れておけば、発生した例外とそのデータを一緒に管理できる
自分が例外としたい単位で処理できる
- タイムアウトした場合と404の場合は投げられる例外が違うが、ロジック的に同じように扱いたいなど
データ取得先が何なのかを利用側が意識する必要がなくなり、取得先が変わっても利用側に影響がない
- とにかくデータ取得ができなかったことを「FailedFetchUserException」と定義しておけば、接続先がAPIからDBに変わっても利用側に影響がないように修正することができる