에러 처리 아키텍처 가이드

[sgoldenbird]

1. ✨ 설계 배경 및 목적

Next.js App Router 기반 RoamReady 프로젝트에서 발생 가능한 다양한 에러를 구조적으로 처리하고, 사용자 경험을 보호하기 위해 다층 에러 처리 구조를 설계했습니다.

• 다양한 API 실패 상황(400, 401, 404, 500 등)에 대해 일관된 UX를 제공하고자 함
• try...catch가 분산된 에러 처리의 유지보수 어려움을 해결
• Tanstack Query, ky, Zod 등 도구를 연결하여 중앙 집중식 에러 처리 흐름을 구축

2. 🧱 구성요소 및 구조

src/
├─ app/
│  ├─ api/
│  │  └─ auth/signup/route.ts         # API 라우트 - 표준 에러 응답 반환
│  ├─ error.tsx                       # 글로벌 렌더링 에러 바운더리
│  └─ (app)/error.tsx                # 세그먼트 렌더링 에러 바운더리
│
├─ shared/
│  ├─ libs/
│  │  ├─ apiClient.ts                # ky 인스턴스 + 공통 훅 연결
│  │  ├─ formatErrorResponseHooks.ts   # ky의 에러 응답 가공 훅
│  │  └─components/              
│  │     └─ errors/ComponentErrorBoundary.tsx  # 컴포넌트 레벨 에러 바운더리(클래스)
│  ├─ schemas/
│  │  └─ error.ts                    # API 에러 응답 Zod 스키마
│
├─ middleware.ts                     # 인증 실패 시 accessToken 자동 갱신 
│
├─ domain/
│  └─ Auth/
│     ├─ services/index.ts           # 순수 API 호출 함수 (try/catch 없음)
│     ├─ hooks/useSignupMutation.ts  # useMutation 예시 (onError 포함)
│     └─ libs/
│        └─ authApiClient.ts         # 인증 전용 ky 인스턴스 + 공통 훅 연결

• app/error.tsx: 앱 전체에서 발생하는 치명적 에러를 처리하는 글로벌 에러 바운더리로, 레이아웃을 포함한 전체 UI를 대체합니다.
• app/(app)/error.tsx: 특정 라우트 그룹 내에서 발생하는 렌더링/페칭 에러만 처리하며, 헤더나 푸터 등의 상위 레이아웃은 유지됩니다.
• shared/components/errors/ComponentErrorBoundary/index.tsx: React 클래스 컴포넌트를 직접 구현하여 특정 UI 영역만 오류가 발생했을 때 격리하여 처리하는 컴포넌트 레벨 에러 바운더리입니다.
• src/shared/libs/apiClient.ts / authApiClient.ts: ky의 beforeError 훅을 통해 모든 API 에러를 중앙 집중식으로 가공하며, 일관된 에러 형식으로 throw합니다.
• src/shared/libs/formatErrorResponseHooks.ts: ky의 beforeError 훅에 연결되어 API 에러 응답을 가공하는 로직이 포함된 파일입니다.
• src/shared/utils/errors/getErrorMessageByStatus.ts: HTTP 상태 코드에 따라 사용자 친화적인 에러 메시지를 반환하는 유틸리티 함수입니다.
• src/domain/*/hooks/*Mutation.ts (예, src/domain/Auth/hooks/useSignupMutation.ts): useMutation 훅을 사용하여 API 호출을 담당하고, onError 콜백을 통해 에러 메시지를 useToast로 전달합니다.
• middleware.ts: 401 Unauthorized 에러에 대한 1차 방어선 역할을 수행하며, refreshToken을 사용한 accessToken 자동 갱신을 시도합니다.

3. ⚙️ 동작 흐름 요약

• 글로벌 에러 처리: src/app/error.tsx는 앱 전체의 마지막 방어선으로, 치명적 오류 발생 시 전체 UI를 대체합니다.

• 세그먼트 에러 처리: src/app/(app)/error.tsx는 특정 페이지 그룹 내 에러만 처리해 상위 레이아웃을 보존하며, UX 일관성을 유지합니다.

• 컴포넌트 레벨 렌더링 에러 처리: ComponentErrorBoundary는 앱 전체가 아닌 특정 영역에서만 문제가 발생했을 때 오류를 격리합니다.

  • 외부 라이브러리 대신 직접 클래스를 구현한 이유는 다음과 같습니다:
    • 프로젝트 요구사항에 맞는 커스텀 로직을 유연하게 처리
    • 외부 의존성 최소화
    • 번들 사이즈 최적화

• API 에러 처리(401 이외):

1. apiClient.ts에 연결된 formatErrorResponseHooks.ts가 서버의 에러 메시지를 파싱하고, getErrorMessageByStatus.ts를 통해 최종 메시지를 결정합니다.
2. 이 메시지는 useMutation 훅의 onError로 전달되어 useToast를 통해 화면에 표시됩니다.

• API 에러 처리(401):
  401 Unauthorized 에러는 middleware.ts와 apiClient.ts가 협력하는 다층 방어 구조로 설계

1. middleware.ts의 1차 방어:
   • 모든 API 요청 전에 실행되는 미들웨어는 먼저 사용자의 accessToken 유효성을 확인합니다.
   • accessToken이 만료되었을 경우, refreshToken을 사용하여 해당 API를 호출해 토큰을 자동으로 갱신합니다.
   • 갱신에 실패하거나 refreshToken이 없는 경우, 401 응답을 그대로 클라이언트에 반환합니다.
2. apiClient.ts의 2차 방어:
   • 미들웨어에서 처리되지 못한 401 응답을 formatErrorResponseHooks.ts가 감지합니다. 이 훅은 클라이언트 전역 사용자 상태를 초기화하고, mypage와 같은 보호된 페이지에서 발생 시 메인 페이지로 리디렉션하여 세션 만료를 알립니다.

• 사용자 피드백: API 호출 실패나 컴포넌트 에러 발생 시 useToast().showError() 등으로 사용자에게 메시지를 표시합니다.

4. 🔮 설계 의도 및 고려사항

API 에러 처리 5 단계 흐름

• UI (컴포넌트): useToast로 시각적 오류를 안내.
• Query 훅: onError에서 상태 관리 및 분기 처리.
• Service: 순수하게 API 호출만 담당(try/catch 없음).
• ky 인스턴스: beforeError 훅에서 에러 응답을 파싱하고 메시지를 가공.
• API 라우트: 모든 응답을 JSON + 상태코드로 통일.

미들웨어의 역할

미들웨어는 오직 refreshToken이 존재하는 경우의 401 에러 자동 갱신만을 처리하여 토큰 관리 로직을 중앙화하고, 다른 모든 에러는 클라이언트로 전달합니다.

선언적 에러 UI

src/app/(app)/error.tsx와 ComponentErrorBoundary를 활용하여 렌더링 에러를 선언적으로 처리하고, 사용자가 어플리케이션의 다른 부분은 계속 이용할 수 있도록 합니다.

5. 🪄 세부 설명: 주요 훅 / 컴포넌트 / 유틸

• formatErrorResponseHooks.ts: ky의 beforeError 훅에서 동작하며, 백엔드에서 반환하는 JSON 형태의 에러 응답을 errorResponseSchema로 파싱합니다. 파싱에 실패하면 fallback 메시지를 구성하여 일관된 에러 형식을 만듭니다.
• src/shared/utils/errors/getErrorMessageByStatus.ts: HTTP 상태 코드에 따라 사용자 친화적인 에러 메시지를 반환하는 유틸리티 함수입니다. formatErrorResponseHooks에서 사용되어 에러 메시지를 가공합니다.
• src/app/api/auth/signup/route.ts: API 라우트에서 try...catch로 모든 에러를 감싸고, JSON 응답으로 통일해 클라이언트로 반환하는 역할을 합니다. 유효성 검증 실패는 ZodError로, 백엔드 실패는 Error + status로 throw합니다.
• src/domain/Auth/services/index.ts: 순수 API 호출 함수만 담고 있어 try...catch 블록이 없습니다. 에러 처리는 상위 계층인 ky와 useMutation 훅에 위임합니다.

6. 🧩 사용 예시 및 패턴

컴포넌트 레벨 ErrorBoundary로 특정 컴포넌트 감싸기

import { ComponentErrorBoundary } from '@/shared/components/errors/ComponentErrorBoundary';
import UserProfile from '@/domain/User/components/UserProfile';

<ComponentErrorBoundary>
  <UserProfile userId={123} />
</ComponentErrorBoundary>

Tanstack Query의 useMutation을 사용한 API 에러 처리

// src/domain/Auth/hooks/useSignupMutation.ts
import { useMutation } from '@tanstack/react-query';
import { useToast } from '@/shared/hooks/useToast';
import { signup } from '../services';

export const useSignupMutation = () => {
  const { showError } = useToast();
  return useMutation({
    mutationFn: (data: SignupRequest) => signup(data),
    onError: (error) => {
      // apiClient.ts에서 가공된 에러 메시지를 사용
      showError(error.message);
    },
    onSuccess: () => {
      // 성공 처리 로직
    }
  });
};

7. ⚠️ 사용 시 주의사항

• middleware.ts는 오직 401 인증 실패만을 1차 처리합니다. 그 외 모든 백엔드 에러(400, 403, 500 등)는 apiClient.ts에서 가공되어 클라이언트로 전달됩니다.
• 서비스 함수(src/domain/Auth/services/index.ts 등)에서는 try...catch를 사용하지 않고, 에러를 ky 인스턴스에 위임해야 useMutation 훅의 상태 관리가 가능합니다.
• 컴포넌트에서 전달받은 error.message는 이미 사용자 친화적으로 가공된 메시지이므로, 별도의 가공 없이 바로 useToast().showError()에 사용하면 됩니다.
• ErrorBoundary 사용 시, 에러 발생 시 상태 초기화가 필요한 케이스인지 여부를 반드시 함께 고려해야 합니다.

8. 📎 참고 파일 및 링크

• src/app/error.tsx
• src/app/(app)/error.tsx
• src/middleware.ts
• src/app/api/auth/signup/route.ts
• src/shared/libs/apiClient.ts
• src/shared/libs/formatErrorResponseHooks.ts
• src/domain/Auth/services/index.ts
• src/domain/Auth/hooks/useSignupMutation.ts
• src/domain/Auth/components/SignUpForm.tsx
• src/shared/components/errors/ComponentErrorBoundary/index.tsx
• src/shared/utils/errors/getErrorMessageByStatus.ts
• Next.js 공식 문서: Error Handling
• React 공식 문서: Error Boundaries