Next.js Error Handling Strategy 2 - 중앙화된 에러 처리

// error/code.ts
 
export const ERROR_CODE = {
  // --- 서버로부터 받은 의도한 에러 ---
  VALIDATION: "VALIDATION",
  AUTH_REQUIRED: "AUTH_REQUIRED",
  FORBIDDEN: "FORBIDDEN",
  NOT_FOUND: "NOT_FOUND",
  RATE_LIMITED: "RATE_LIMITED",
 
  // --- 클라이언트 경계에서 발생한 시스템 레벨 에러 ---
  NETWORK_ERROR: "NETWORK_ERROR",
  TIMEOUT_ERROR: "TIMEOUT_ERROR",
 
  // --- 모든 경계에서 발생할 수 있는 최후의 에러 ---
  INTERNAL_SERVER_ERROR: "INTERNAL_SERVER_ERROR",
  UNKNOWN_CLIENT_ERROR: "UNKNOWN_CLIENT_ERROR",
 
  // ... (추가 가능)
};
 
// 객체의 key로부터 Union 타입을 유도
export type ErrorCode = keyof typeof ERROR_CODE;

// error/schema.ts
 
import { z } from "zod";
import { ERROR_CODE, type ErrorCode } from "./code";
 
export const ErrorDetailsSchema = {
  [ERROR_CODE.VALIDATION]: z.object({
    fieldErrors: z.record(z.array(z.string()).optional()),
  }),
  [ERROR_CODE.RATE_LIMITED]: z.object({ retryAfter: z.number().positive() }),
  [ERROR_CODE.AUTH_REQUIRED]: z.void(), // 값이 없음을 z.void()로 명시적으로 표기
  [ERROR_CODE.FORBIDDEN]: z.void(),
  [ERROR_CODE.NOT_FOUND]: z.void(),
  [ERROR_CODE.NETWORK_ERROR]: z.void(),
  [ERROR_CODE.TIMEOUT_ERROR]: z.void(),
  [ERROR_CODE.INTERNAL_SERVER_ERROR]: z.void(),
  [ERROR_CODE.UNKNOWN_CLIENT_ERROR]: z.void(),
 
  // ... (추가 가능)
 
  // 'satisfies'를 활용해 모든 ErrorCode에 대한 스키마가 정의되었는지 컴파일 타임에 검사
} as const satisfies Record<ErrorCode, z.ZodTypeAny>;
 
// 스키마로부터 타입을 유도
export type ErrorDetails = {
  [K in ErrorCode]: z.infer<(typeof ErrorDetailsSchema)[K]>;
};

// error/domain-error.ts
import type { ErrorCode } from "./code";
import type { ErrorDetails } from "./schema";
 
export type ErrorArgs<C> = {
  code: C;
  details: ErrorDetails[C];
  messages?: string;
  cause?: unknown;
};
 
export class DomainError<C extends ErrorCode = ErrorCode> extends Error {
  public readonly code: C;
  public readonly details: ErrorDetails[C];
  public readonly cause?: unknown;
 
  constructor(args: ErrorArgs<C>) {
    super(args.message ?? args.code);
    this.name = "DomainError";
    this.code = args.code;
    this.details = args.details;
    this.cause = args.cause;
  }
}
 
// 타입 가드 함수
export const isDomainError = <C extends ErrorCode>(
  e: unknown,
  code?: C,
): e is DomainError<C> =>
  e instanceof DomainError && (!code || e.code === code);

// error/make-error.ts
import { ERROR_CODE, type ErrorCode } from "./code";
import { DomainError, type ErrorArgs } from "domain-error";
import { ErrorDetailsSchema } from "./schema";
 
type Params = {
  [C in ErrorCode]: {
    code: C;
    details: ErrorDetails[C];
    message?: string;
    cause?: unknown;
  };
}[ErrorCode];
 
export const makeError = ({
  code,
  details,
  messages,
  cause,
}: Params): DomainError => {
  const validation = ErrorDetailsSchema[code].safeParse(details);
 
  if (!validation.success) {
    console.error(`Invalid details for error code ${code}: `, validation.error);
 
    return new DomainError({
      code: ERROR_CODE.UNKNOWN_CLIENT_ERROR,
      message: "잘못된 에러 details 정보로 에러 객체가 생성되었습니다.",
      details: undefined,
      cause: { validationError: validation.error, originalCause: cause },
    });
  }
 
  return new DomainError({ code, details: validation.data, message, cause });
};

// error/policies.ts
import { ERROR_CODE, type ErrorCode } from "./code";
 
export type BaseUxAction = "toast" | "alert" | "none";
export type ErrorPolicy<UxAction = BaseUxAction> = {
  ux: UxAction;
  log: "info" | "error" | "warning" | "none";
};
 
export const ERROR_POLICIES: Record<ErrorCode, ErrorPolicy> = {
  [ERROR_CODE.VALIDATION]: { ux: "none", log: "warning" },
  [ERROR_CODE.AUTH_REQUIRED]: { ux: "alert", log: "error" },
  [ERROR_CODE.NETWORK_ERROR]: { ux: "toast", log: "error" },
  [ERROR_CODE.INTERNAL_SERVER_ERROR]: { ux: "toast", log: "error" },
  [ERROR_CODE.UNKNOWN_CLIENT_ERROR]: { ux: "toast", log: "error" },
 
  // ... (추가 가능)
};
 
// 기본 정책
export const DEFAULT_ERROR_POLICY: ErrorPolicy = { ux: "toast", log: "info" };

// error/handler.ts
import { toast } from "sooner";
import { Sentry } from "@event/sentry";
import { ERROR_CODE, type ErrorCode } from "./code";
import { DomainError, isDomainError } from "./domain-error";
import { makeError } from "./make-error";
import {
  ERROR_POLICIES,
  DEFAULT_ERROR_POLICY,
  type ErrorPolicy,
  type BaseUxAction,
} from "./policies";
 
type ErrorPolicyWithCustomOptions = Partial<
  ErrorPolicy<BaseUxAction & ((error: DomainError) => void)>
>;
 
export const handleError = (
  error: unknown,
  options: ErrorPolicyWithCustomOptions = {},
) => {
  const domainError = isDomainError(error)
    ? error
    : makeError({
        code: ERROR_CODE.UNKNOWN_CLIENT_ERROR,
        details: undefined,
        message: "알 수 없는 에러가 발생했습니다.",
        cause: error,
      });
 
  const policy: ErrorPolicy =
    ERROR_POLICIES[domainError.code] || DEFAULT_ERROR_POLICY;
  const finalUx = options.ux ?? policy.ux;
  const finalLog = options.log ?? policy.log;
 
  // UX 처리
  if (typeof finalUx === "function") {
    finalUx(domainError);
  } else if (finalUx === "toast") {
    toast.error(domainError.message);
  } else if (finalUx === "alert") {
    alert(domainError.message);
  }
 
  // 로깅 처리
  if (finalLog === "info") {
    console.info(domainError);
  } else if (finalLog === "warning") {
    console.warning(domainError);
  } else if (finalLog === "error") {
    console.error(domainError);
    Sentry.captureException(domainError);
  }
};