Skip to Content
API 레퍼런스@asapjs/fastifyfastifyErrorHandler

fastifyErrorHandler

이 페이지에서 찾을 수 있는 것

심볼분류설명
fastifyErrorHandlerFunctionFastify 전역 에러 핸들러

개요

fastifyErrorHandler는 Fastify의 setErrorHandler()에 등록되는 전역 에러 핸들러입니다. FastifyWrapper를 거치지 않고 던져진 에러, 또는 Fastify 내부에서 발생한 에러를 처리합니다. @asapjs/error의 resolveErrorBody()를 사용하여 프레임워크에 독립적인 방식으로 에러 바디를 생성합니다.

import { fastifyErrorHandler } from '@asapjs/fastify';

함수 시그니처

function fastifyErrorHandler(
  error: FastifyError | Error | unknown,
  request: FastifyRequest,
  reply: FastifyReply,
): void
파라미터타입설명
errorFastifyError | Error | unknown처리할 에러 객체. Fastify 내부 에러, HttpError, 일반 Error, 또는 알 수 없는 값 모두 처리합니다.
requestFastifyRequest에러가 발생한 요청 객체. 로그 컨텍스트 수집에 사용합니다.
replyFastifyReply에러 응답을 전송할 응답 객체.

동작 방식

fastifyErrorHandler가 호출되면 다음 순서로 동작합니다:

  1. 에러 컨텍스트 로깅 — 다음 정보를 로그에 기록합니다:

    • requestId — Fastify가 생성한 요청 식별자
    • method — HTTP 메서드 (예: GET, POST)
    • url — 요청 URL
    • ip — 클라이언트 IP 주소
    • file, line, function — 에러 스택에서 추출한 발생 위치

  2. 에러 바디 생성 — @asapjs/error의 resolveErrorBody(error)를 호출하여 HTTP 상태 코드와 응답 바디를 결정합니다.

  3. 응답 전송 — reply.code(errorBody.status).send(errorBody)로 에러 응답을 전송합니다.

resolveErrorBody()의 에러 분류

resolveErrorBody()는 @asapjs/error 패키지에서 제공하는 프레임워크 독립적인 함수입니다. 에러 유형에 따라 다음과 같이 응답 바디를 결정합니다:

에러 유형조건HTTP 상태응답 바디
HttpErrorerror() 팩토리로 생성err.status{ status, errorCode, message, data }
status + message 객체status와 message 속성 있음err.status{ status, errorCode, message }
처리되지 않은 오류위 조건 모두 해당 없음500{ status: 500, errorCode: 'INTERNAL_SERVER_ERROR', message }

등록 방법

fastifyErrorHandler는 FastifyRouterPlugin이 초기화 과정에서 자동으로 등록합니다. 직접 등록할 필요는 없지만, FastifyRouterPlugin 없이 Fastify를 사용하는 경우 수동으로 등록할 수 있습니다:

import Fastify from 'fastify';
import { fastifyErrorHandler } from '@asapjs/fastify';
 
const app = Fastify();
 
app.setErrorHandler(fastifyErrorHandler);

에러 응답 예제

HttpError 응답

import { error } from '@asapjs/error';
 
const UserNotFound = error(404, 'USER_NOT_FOUND', '사용자를 찾을 수 없습니다');
 
// 핸들러에서 던지면:
throw new UserNotFound();
 
// 응답:
// HTTP 404
// {
//   "status": 404,
//   "errorCode": "USER_NOT_FOUND",
//   "message": "사용자를 찾을 수 없습니다"
// }

처리되지 않은 에러 응답

// 핸들러에서 던지면:
throw new Error('예상치 못한 오류');
 
// 응답:
// HTTP 500
// {
//   "status": 500,
//   "errorCode": "INTERNAL_SERVER_ERROR",
//   "message": "예상치 못한 오류"
// }

FastifyWrapper와의 관계

FastifyWrapper도 내부적으로 에러를 처리하지만, 두 에러 처리 경로는 서로 다른 상황에서 동작합니다:

경로동작 시점처리 방식
FastifyWrapper 내부라우트 핸들러에서 에러 발생 시reply.status().send()로 직접 응답
fastifyErrorHandlerFastify 내부 에러, 미들웨어 에러, 기타reply.code().send()로 응답

fastifyErrorHandler는 @asapjs/error의 resolveErrorBody()를 사용하여 에러를 정규화하지만, FastifyWrapper는 자체 에러 처리 로직을 구현합니다. 두 경로의 응답 형식은 유사하지만 세부 동작에 차이가 있습니다:

  • FastifyWrapper: HttpError → error.toJSON(), {status, message} 객체 → errorCode: 'HTTP_EXCEPTION', 기타 → errorCode: 'INTERNAL_SERVER_ERROR'
  • fastifyErrorHandler: resolveErrorBody()를 통해 HttpError, 레거시 HttpException (errorCode: 'LEGACY_HTTP_EXCEPTION'), HttpErrorBody 객체, 기타 에러를 정규화

관련 항목

Last updated on
HTTP Method DecoratorsFastifyExecuteArgs