はじめに
今回は、Honoとその3rd-party MiddlewareであるZod OpenAPIを使ったときのAPIエラーハンドリングについて紹介します。APIのエラーハンドリングというと、主に以下のようなケースが考えられます。
- パスやボディ、クエリなどのリクエストパラメータが不正な場合のバリデーションエラー（400 Bad Request）
- トークンが存在しなかったり、期限切れになっているなどの認証エラー（401 Unauthorized）
- データベース接続の失敗や外部サービスとの連携時に起こるサーバーエラー（500 Internal Server Error）
HonoのミドルウェアやZod OpenAPIを活用することで、エラーハンドリングは簡単に実装することができますが、今回はそれらの機能を組み合わせ、エラー処理を一元管理し、レスポンス形式を統一することを目指します。
サンプルリポジトリ
今回の記事の内容を実装したサンプルリポジトリも用意しました。記事と合わせてご覧ください。
また、各ライブラリの導入手順については、公式ドキュメントやGitHubのガイドの通りなので、ここでは詳細は割愛します。必要な場合は、以下のリンクを参考にしてください。
エラーハンドリングの実装手順
ここからが本題です。Honoでは、下記のようにエラーハンドリングを実装することができます。
- ミドルウェアやルートでは、Honoが提供する
HTTPExceptionを使ってエラーをスローする。 - トップレベルの
app.onErrorにより、スローされたエラーをキャッチし、共通のエラーハンドリングを行う。
それでは、実装例を見ていきましょう。
1. トップレベルの共通エラーハンドリングを実装する
今回は、共通して利用するAPIのエラーレスポンス型ErrorResponseを以下のように定義します。messageはエラーメッセージ、errorsには各フィールドごとのバリデーションエラー等の詳細を格納します。
type ErrorResponse = {
message: string;
errors?: {
[key: string]: string[];
}
}
Honoでは、app.onErrorを使うことで、各ミドルウェアやルートでスローされたエラーをキャッチし、トップレベルで共通の処理を実装することが可能です。
後ほどHTTPExceptionをスローする際に、causeオプションとしてZodのエラーZodErrorが渡ってくるため、errorsの形式に変換して返しています。
2. バリデーションエラーを実装する
Zod OpenAPIでは、各ルートの処理後に実行されるフックを登録することで、バリデーションに失敗した場合のエラーハンドリングが可能です。さらに、OpenAPIHonoのdefaultHookを利用することで、各ルートごとにフックを個別に設定せずに、共通のハンドリングを実現できます。
バリデーションが失敗した場合、result.errorに含まれるZodErrorをHTTPExceptionのcauseにセットして400エラーをスローしています。これにより、バリデーションエラーをapp.onErrorでキャッチし、ErrorResponse型に変換してクライアントに返すことができます。
実際のアプリケーションではルートをファイル分割して管理したくなりますが、その場合は各OpenAPIHonoインスタンスに対して個別にdefaultHookを設定する必要があります。サンプルリポジトリでは、createOpenApiHonoという関数を用意してインスタンスの生成を共通化しています。
3. 認証エラーを実装する
Honoでは、createMiddlewareを利用して独自のミドルウェアを作成することが可能です。今回の例では、Authorizationヘッダを簡単に検証するミドルウェアを実装しています。
Authorizationヘッダが存在しない場合や、アクセストークンの検証に失敗した場合は、それぞれHTTPExceptionを使って401エラーをスローしています。このようにミドルウェアでも、先ほどのバリデーションエラーと同様の形式でHTTPExceptionをスローするだけで、共通のエラーハンドリングが実現できます。
4. APIドキュメントにエラーレスポンスを追加する
Honoでは、Zod OpenAPIとSwagger UIを組み合わせることで、自動生成されたOpenAPI仕様のドキュメントをSwagger UIとして表示できます。
この際、OpenAPIにエラーレスポンスの型を定義することで、Swagger UI上にもエラー時のスキーマが表示されるようになりますが、各ルートに個別に記述するのは面倒なため、共通化しておきます。また、手順1で定義したErrorResponse型は、createErrorResponseSchemaから算出できるため、z.inferを利用してここで定義しておきます。
続いて、各ルートにerrorResponsesを追加していきます。サンプルリポジトリでは、認証のミドルウェアを実装した/protectedルートと、認証不要の/publicルートを用意しており、/publicルートには401エラーを除いたpublicErrorResponsesを指定しています。
さいごに
以上の手順により、各種エラーの処理をapp.onErrorで一元管理し、APIのエラーレスポンスをErrorResponse形式に統一することができました。Zod OpenAPIを利用したエラーハンドリングの一例として、ぜひ参考にしてみてください。
Discussion