16. 例外フィルタ — エラーレスポンスの統一

例外フィルタは、処理中に投げられた例外を捕まえてエラーレスポンスの形を決める部品です。@Catch(HttpException) を付けたクラスで ExceptionFilter を実装し、catch() の中でステータスコードとレスポンスボディを組み立てます。

NestJS は未処理の例外を標準形式の JSON で返してくれますが、実務では「エラーコードや発生時刻を必ず含める」など自社フォーマットへの統一が求められます。フィルタを1つ作って app.useGlobalFilters() で全体に適用すれば、すべてのエラーが同じ形で返るようになります。

注意点は、例外の握りつぶしです。catch() の中でレスポンスを返し忘れるとクライアントが応答を受け取れず固まります。また内部エラーの詳細メッセージをそのまま返すと情報漏えいにつながるため、500 系では汎用メッセージに置き換えるのが定石です。

サンプルコード(フレームワーク環境が必要なため表示のみ)

import {
  ExceptionFilter, Catch, ArgumentsHost, HttpException,
} from "@nestjs/common";

@Catch(HttpException) // HttpException とその派生を捕まえる
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const statusCode = exception.getStatus();

    // どの例外もこの形に統一して返す
    response.status(statusCode).json({
      statusCode,
      message: exception.message,
      timestamp: new Date().toISOString(),
    });
  }
}
// main.ts 側: app.useGlobalFilters(new HttpExceptionFilter());

公式ドキュメントで詳しく ↗