NestJS で例外をどのように処理しますか？

Question

Accepted Answer

NestJS には、**組み込みの例外レイヤー**があり、未処理のエラーを自動的にキャッチして適切な HTTP レスポンスに変換します。例外を**スロー**（通常は組み込みの HTTP 例外クラス）することでエラーを通知し、Nest はそれを正しいステータスコードを含む構造化された JSON レスポンスにフォーマットします。

## 組み込みの HTTP 例外をスローする

```ts
import { NotFoundException, BadRequestException, UnauthorizedException } from "@nestjs/common";

@Get(":id")
findOne(@Param("id") id: string) {
  const user = this.usersService.findOne(id);
  if (!user) {
    throw new NotFoundException("User not found");   // → 404 with a JSON error body
  }
  return user;
}
```

NestJS は HTTP ステータスコードにマップされた例外クラスを提供しており、1 つをスローすると正しく構造化されたレスポンスが自動的に生成されます：

```json
{ "statusCode": 404, "message": "User not found", "error": "Not Found" }
```

## よく使われる組み込みの HTTP 例外

```text
BadRequestException        → 400
UnauthorizedException      → 401
ForbiddenException         → 403
NotFoundException          → 404
ConflictException          → 409
UnprocessableEntityException → 422
InternalServerErrorException → 500
```

一般的な HTTP エラーごとにクラスが存在します — 正しいステータスを通知するために適切なものを使用してください。

## カスタムメッセージと汎用 HttpException

```ts
// custom status + body via the base HttpException
throw new HttpException(
  { status: HttpStatus.FORBIDDEN, error: "custom message" },
  HttpStatus.FORBIDDEN,
);
```

## カスタム例外クラス

```ts
export class UserNotFoundException extends NotFoundException {
  constructor(id: string) {
    super(`User with id ${id} not found`);   // domain-specific, reusable
  }
}
throw new UserNotFoundException(id);
```

## 未処理のエラーは 500 になります

```text
If code throws a non-HttpException error (e.g. a plain Error or an unexpected
exception), NestJS's default exception filter catches it and returns a generic
500 Internal Server Error (without leaking internal details to the client).
```

## グローバルカスタマイズのための例外フィルター

```ts
// a custom exception filter customizes how errors are formatted/logged globally
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // log, format the response, etc.
  }
}
app.useGlobalFilters(new AllExceptionsFilter());   // apply app-wide
```

一貫性のあるエラーフォーマット、ロギング、または HTTP 以外のエラー処理については、**例外フィルター**（関連するより高度な機能）を使用します。

## なぜ重要なのか

適切な例外処理は信頼性の高い API を構築するために不可欠であり、NestJS の組み込みの例外レイヤーはそれをクリーンで一貫したものにしてくれます。

**HTTP 例外**（`NotFoundException`、`BadRequestException` など）を**スローする方法**を理解することは日常的な知識です — これは正しいステータスコードと構造化されたクライアントフレンドリーな JSON レスポンスでエラーを通知する慣用的な方法であり、すべてのハンドラーでエラーレスポンスを手動で構築する必要はありません。

フレームワークはこれらを自動的にキャッチしてフォーマットし、予期しないエラーを安全に汎用的な 500 に変換して内部の詳細を漏らしません（セキュリティにおいて重要）。

一般的な例外クラス、カスタムメッセージ/例外をスロー方法、グローバルカスタマイズのための**例外フィルター**（一貫性のあるフォーマット、ロギング）が存在することを知ることは、堅牢でプロフェッショナルな NestJS API を構築するために基本的です。

クリーンで一貫したエラー処理は高品質なバックエンドコードの特徴であり、これはフレームワークのコア機能で頻繁に使用される側面です。