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");   // → JSON 오류 본문과 함께 404
  }
  return user;
}
```

NestJS는 HTTP 상태 코드에 매핑되는 예외 클래스를 제공하며, 하나를 던지면 자동으로 올바르고 구조화된 응답이 생성됩니다:

```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
// 기본 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`);   // 도메인 특화, 재사용 가능
  }
}
throw new UserNotFoundException(id);
```

## 처리되지 않은 오류는 500이 됩니다

```text
코드가 HttpException이 아닌 오류(예: 일반 Error 또는 예상치 못한 예외)를
던지면, NestJS의 기본 예외 필터가 이를 잡아 일반적인 500 Internal Server
Error를 반환합니다 (내부 세부 정보를 클라이언트에 누출하지 않음).
```

## 전역 커스터마이징을 위한 예외 필터

```ts
// 커스텀 예외 필터는 오류가 전역적으로 포맷/로깅되는 방식을 커스터마이징
@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    // 로깅, 응답 포맷 등
  }
}
app.useGlobalFilters(new AllExceptionsFilter());   // 앱 전역 적용
```

일관된 오류 포맷, 로깅, 또는 HTTP가 아닌 오류 처리를 위해 **예외 필터**(관련된 더 고급 기능)를 사용합니다.

## 왜 중요한가

적절한 예외 처리는 신뢰할 수 있는 API를 구축하는 데 필수적이며, NestJS의 내장 예외 계층은 이를 깔끔하고 일관되게 만듭니다.

**HTTP 예외를 던지는** 방법(`NotFoundException`, `BadRequestException` 등)을 이해하는 것은 일상 지식입니다 — 모든 핸들러에서 수동으로 오류 응답을 구성하지 않고도 올바른 상태 코드와 구조화되고 클라이언트 친화적인 JSON 응답으로 오류를 알리는 관용적인 방법입니다.

프레임워크가 이를 자동으로 잡아 포맷하며, 예상치 못한 오류는 내부 세부 정보를 누출하지 않고 안전하게 일반 500으로 변환합니다(보안상 중요).

일반적인 예외 클래스, 커스텀 메시지/예외를 던지는 방법, 그리고 전역 커스터마이징(일관된 포맷, 로깅)을 위한 **예외 필터**가 존재한다는 것을 아는 것은 견고하고 전문적인 NestJS API를 구축하는 데 기본적입니다.

깔끔하고 일관된 오류 처리는 양질의 백엔드 코드의 특징이므로, 이는 프레임워크의 핵심적이고 자주 사용되는 측면입니다.