2025년 9월 14일한국어

견고한 오류 처리와 정상적인 UI 장애 극복을 위해 React에서 JavaScript 오류 경계를 이해하고 구현하는 종합 가이드입니다.

JavaScript 오류 경계(Error Boundary): React 오류 처리 구현 가이드

React 개발 영역에서 예기치 않은 오류는 사용자 경험을 저해하고 애플리케이션의 불안정성을 초래할 수 있습니다. 잘 정의된 오류 처리 전략은 견고하고 신뢰할 수 있는 애플리케이션을 구축하는 데 매우 중요합니다. React의 오류 경계(Error Boundaries)는 컴포넌트 트리 내에서 발생하는 오류를 정상적으로 처리하여 전체 애플리케이션의 중단을 방지하고 대체 UI를 표시할 수 있는 강력한 메커니즘을 제공합니다.

오류 경계(Error Boundary)란 무엇인가요?

오류 경계는 자식 컴포넌트 트리 어디에서든 JavaScript 오류를 포착하여 기록하고, 충돌이 발생한 컴포넌트 트리 대신 대체 UI를 표시하는 React 컴포넌트입니다. 오류 경계는 렌더링 중, 생명주기 메서드, 그리고 하위 전체 트리의 생성자에서 발생하는 오류를 포착합니다.

오류 경계를 React 컴포넌트를 위한 try...catch 블록이라고 생각할 수 있습니다. try...catch 블록이 동기적인 JavaScript 코드에서 예외를 처리하는 것처럼, 오류 경계는 React 컴포넌트 렌더링 중에 발생하는 오류를 처리할 수 있게 해줍니다.

중요 참고: 오류 경계는 다음 경우의 오류는 포착하지 않습니다:

이벤트 핸들러 (다음 섹션에서 자세히 알아보기)
비동기 코드 (예: setTimeout 또는 requestAnimationFrame 콜백)
서버 사이드 렌더링
오류 경계 자체에서 발생하는 오류 (자식 컴포넌트가 아닌)

왜 오류 경계를 사용해야 하나요?

오류 경계를 사용하면 다음과 같은 여러 가지 중요한 이점이 있습니다:

향상된 사용자 경험: 빈 흰색 화면이나 알 수 없는 오류 메시지를 표시하는 대신, 사용자 친화적인 대체 UI를 보여주어 사용자에게 문제가 발생했음을 알리고 잠재적으로 복구할 방법을 제공할 수 있습니다 (예: 페이지 새로고침 또는 다른 섹션으로 이동).
애플리케이션 안정성: 오류 경계는 애플리케이션의 한 부분에서 발생한 오류가 전체 애플리케이션을 중단시키는 것을 방지합니다. 이는 상호 연결된 컴포넌트가 많은 복잡한 애플리케이션에서 특히 중요합니다.
중앙 집중식 오류 처리: 오류 경계는 오류를 기록하고 문제의 근본 원인을 추적할 수 있는 중앙 집중식 위치를 제공합니다. 이는 디버깅과 유지보수를 단순화합니다.
정상적인 기능 저하(Graceful Degradation): 애플리케이션의 여러 부분에 전략적으로 오류 경계를 배치하여 일부 컴포넌트가 실패하더라도 나머지 애플리케이션이 계속 작동하도록 할 수 있습니다. 이를 통해 오류 발생 시 정상적인 기능 저하가 가능해집니다.

React에서 오류 경계 구현하기

오류 경계를 생성하려면 다음 생명주기 메서드 중 하나 또는 둘 다를 구현하는 클래스 컴포넌트를 정의해야 합니다:

static getDerivedStateFromError(error): 이 생명주기 메서드는 하위 컴포넌트에서 오류가 발생한 후에 호출됩니다. 발생한 오류를 인수로 받으며, 오류가 발생했음을 나타내기 위해 컴포넌트의 상태를 업데이트할 값을 반환해야 합니다 (예: hasError 플래그를 true로 설정).
componentDidCatch(error, info): 이 생명주기 메서드는 하위 컴포넌트에서 오류가 발생한 후에 호출됩니다. 발생한 오류와 함께 어떤 컴포넌트에서 오류가 발생했는지에 대한 정보가 포함된 info 객체를 인수로 받습니다. 이 메서드를 사용하여 Sentry나 Bugsnag 같은 서비스에 오류를 기록할 수 있습니다.

다음은 오류 경계 컴포넌트의 기본 예시입니다:


class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      hasError: false,
      error: null,
      errorInfo: null
    };
  }

  static getDerivedStateFromError(error) {
    // 다음 렌더링에서 대체 UI를 표시하도록 상태를 업데이트합니다.
    return {
      hasError: true,
      error: error
    };
  }

  componentDidCatch(error, info) {
    // "componentStack" 예시:
    //   in ComponentThatThrows (created by App)
    //   in MyErrorBoundary (created by App)
    //   in div (created by App)
    //   in App
    console.error("Caught an error:", error, info);
    this.setState({
        errorInfo: info.componentStack
    });
    // 오류 보고 서비스에 오류를 기록할 수도 있습니다
    //logErrorToMyService(error, info.componentStack);
  }

  render() {
    if (this.state.hasError) {
      // 원하는 사용자 정의 대체 UI를 렌더링할 수 있습니다
      return (
        <div>
          <h2>문제가 발생했습니다.</h2>
          <p>오류: {this.state.error ? this.state.error.message : "알 수 없는 오류가 발생했습니다."}</p>
          <details style={{ whiteSpace: 'pre-wrap' }}>
            {this.state.errorInfo && this.state.errorInfo}
          </details>
        </div>
      );
    }

    return this.props.children; 
  }
}

오류 경계를 사용하려면 보호하려는 컴포넌트 트리를 감싸기만 하면 됩니다:


<ErrorBoundary>
  <MyComponentThatMightThrow/>
</ErrorBoundary>

오류 경계 사용의 실제 예시

오류 경계가 특히 유용할 수 있는 몇 가지 실제 시나리오를 살펴보겠습니다:

1. API 오류 처리

API에서 데이터를 가져올 때 네트워크 문제, 서버 문제 또는 유효하지 않은 데이터로 인해 오류가 발생할 수 있습니다. 데이터를 가져와 표시하는 컴포넌트를 오류 경계로 감싸 이러한 오류를 정상적으로 처리할 수 있습니다.


function UserProfile() {
  const [user, setUser] = React.useState(null);
  const [isLoading, setIsLoading] = React.useState(true);

  React.useEffect(() => {
    async function fetchData() {
      try {
        const response = await fetch('/api/user');
        if (!response.ok) {
          throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data = await response.json();
        setUser(data);
      } catch (error) {
        // 오류는 ErrorBoundary에 의해 포착됩니다
        throw error; 
      } finally {
        setIsLoading(false);
      }
    }

    fetchData();
  }, []);

  if (isLoading) {
    return <p>사용자 프로필 로딩 중...</p>;
  }

  if (!user) {
    return <p>사용자 데이터가 없습니다.</p>;
  }

  return (
    <div>
      <h2>{user.name}</h2>
      <p>이메일: {user.email}</p>
    </div>
  );
}

function App() {
  return (
    <ErrorBoundary>
      <UserProfile />
    </ErrorBoundary>
  );
}

이 예시에서 API 호출이 실패하거나 오류를 반환하면 오류 경계가 오류를 포착하고 (오류 경계의 render 메서드 내에 정의된) 대체 UI를 표시합니다. 이는 전체 애플리케이션의 중단을 방지하고 사용자에게 더 유익한 메시지를 제공합니다. 대체 UI를 확장하여 요청을 재시도하는 옵션을 제공할 수도 있습니다.

2. 서드파티 라이브러리 오류 처리

서드파티 라이브러리를 사용할 때 예기치 않은 오류가 발생할 수 있습니다. 이러한 라이브러리를 사용하는 컴포넌트를 오류 경계로 감싸면 이러한 오류를 정상적으로 처리하는 데 도움이 될 수 있습니다.

데이터 불일치나 다른 문제로 인해 가끔 오류를 발생시키는 가상의 차트 라이브러리를 생각해보세요. 다음과 같이 차트 컴포넌트를 감쌀 수 있습니다:


function MyChartComponent() {
  try {
    // 서드파티 라이브러리를 사용하여 차트 렌더링
    return <Chart data={data} />;
  } catch (error) {
    // 이 catch 블록은 React 컴포넌트 생명주기 오류에는 효과가 없습니다
    // 주로 이 특정 함수 내의 동기적 오류를 위한 것입니다.
    console.error("Error rendering chart:", error);
    // ErrorBoundary가 포착하도록 오류를 던지는 것을 고려하세요
    throw error; // 오류 다시 던지기
  }
}

function App() {
  return (
    <ErrorBoundary>
      <MyChartComponent />
    </ErrorBoundary>
  );
}

만약 Chart 컴포넌트에서 오류가 발생하면 오류 경계가 이를 포착하고 대체 UI를 표시합니다. MyChartComponent 내의 try/catch는 컴포넌트의 생명주기가 아닌 동기 함수 내의 오류만 포착한다는 점에 유의하세요. 따라서 여기서 오류 경계는 매우 중요합니다.

3. 렌더링 오류 처리

유효하지 않은 데이터, 잘못된 prop 타입 또는 기타 문제로 인해 렌더링 과정에서 오류가 발생할 수 있습니다. 오류 경계는 이러한 오류를 포착하여 애플리케이션이 중단되는 것을 방지할 수 있습니다.


function DisplayName({ name }) {
  if (typeof name !== 'string') {
    throw new Error('Name must be a string');
  }

  return <h2>안녕하세요, {name}님!</h2>;
}

function App() {
  return (
    <ErrorBoundary>
      <DisplayName name={123} />  <!-- 잘못된 prop 타입 -->
    </ErrorBoundary>
  );
}

이 예시에서 DisplayName 컴포넌트는 name prop이 문자열일 것으로 예상합니다. 대신 숫자가 전달되면 오류가 발생하고 오류 경계가 이를 포착하여 대체 UI를 표시합니다.

오류 경계와 이벤트 핸들러

앞서 언급했듯이, 오류 경계는 이벤트 핸들러 내에서 발생하는 오류를 포착하지 않습니다. 이는 이벤트 핸들러가 일반적으로 비동기적이며, 오류 경계는 렌더링 중, 생명주기 메서드, 그리고 생성자에서 발생하는 오류만 포착하기 때문입니다.

이벤트 핸들러의 오류를 처리하려면 이벤트 핸들러 함수 내에서 전통적인 try...catch 블록을 사용해야 합니다.


function MyComponent() {
  const handleClick = () => {
    try {
      // 오류를 발생시킬 수 있는 일부 코드
      throw new Error('이벤트 핸들러에서 오류가 발생했습니다');
    } catch (error) {
      console.error('이벤트 핸들러에서 오류를 포착했습니다:', error);
      // 오류 처리 (예: 사용자에게 오류 메시지 표시)
    }
  };

  return <button onClick={handleClick}>클릭하세요</button>;
}

전역 오류 처리

오류 경계는 React 컴포넌트 트리 내의 오류를 처리하는 데 훌륭하지만, 모든 가능한 오류 시나리오를 다루지는 않습니다. 예를 들어, 전역 이벤트 리스너의 오류나 React가 초기화되기 전에 실행되는 코드의 오류와 같이 React 컴포넌트 외부에서 발생하는 오류는 포착하지 못합니다.

이러한 유형의 오류를 처리하기 위해 window.onerror 이벤트 핸들러를 사용할 수 있습니다.


window.onerror = function(message, source, lineno, colno, error) {
  console.error('전역 오류 핸들러:', message, source, lineno, colno, error);
  // Sentry나 Bugsnag 같은 서비스에 오류 기록
  // 사용자에게 전역 오류 메시지 표시 (선택 사항)
  return true; // 기본 오류 처리 동작 방지
};

window.onerror 이벤트 핸들러는 포착되지 않은 JavaScript 오류가 발생할 때마다 호출됩니다. 이를 사용하여 오류를 기록하거나, 사용자에게 전역 오류 메시지를 표시하거나, 오류를 처리하기 위한 다른 조치를 취할 수 있습니다.

중요: window.onerror 이벤트 핸들러에서 true를 반환하면 브라우저가 기본 오류 메시지를 표시하는 것을 방지합니다. 그러나 사용자 경험을 염두에 두어야 합니다. 기본 메시지를 억제하는 경우, 명확하고 유익한 대안을 제공해야 합니다.

오류 경계 사용을 위한 모범 사례

다음은 오류 경계를 사용할 때 염두에 두어야 할 몇 가지 모범 사례입니다:

전략적으로 오류 경계 배치: 오류를 격리하고 연쇄적으로 퍼지는 것을 방지하기 위해 애플리케이션의 여러 부분을 오류 경계로 감싸세요. 전체 라우트나 UI의 주요 섹션을 감싸는 것을 고려해보세요.
유익한 대체 UI 제공: 대체 UI는 사용자에게 오류가 발생했음을 알리고 잠재적으로 복구할 방법을 제공해야 합니다. "문제가 발생했습니다."와 같은 일반적인 오류 메시지를 표시하는 것을 피하세요.
오류 기록: componentDidCatch 생명주기 메서드를 사용하여 Sentry나 Bugsnag 같은 서비스에 오류를 기록하세요. 이는 문제의 근본 원인을 추적하고 애플리케이션의 안정성을 향상시키는 데 도움이 됩니다.
예상된 오류에 오류 경계 사용하지 않기: 오류 경계는 예기치 않은 오류를 처리하도록 설계되었습니다. 예상된 오류(예: 유효성 검사 오류, API 오류)의 경우, try...catch 블록이나 사용자 정의 오류 처리 컴포넌트와 같은 더 구체적인 오류 처리 메커니즘을 사용하세요.
여러 수준의 오류 경계 고려: 오류 경계를 중첩하여 여러 수준의 오류 처리를 제공할 수 있습니다. 예를 들어, 처리되지 않은 모든 오류를 포착하여 일반적인 오류 메시지를 표시하는 전역 오류 경계와 특정 컴포넌트의 오류를 포착하여 더 자세한 오류 메시지를 표시하는 더 구체적인 오류 경계를 가질 수 있습니다.
서버 사이드 렌더링을 잊지 마세요: 서버 사이드 렌더링을 사용하는 경우, 서버에서도 오류를 처리해야 합니다. 오류 경계는 서버에서도 작동하지만, 초기 렌더링 중에 발생하는 오류를 포착하기 위해 추가적인 오류 처리 메커니즘을 사용해야 할 수도 있습니다.

고급 오류 경계 기법

1. 렌더 프롭(Render Prop) 사용하기

정적인 대체 UI를 렌더링하는 대신, 렌더 프롭을 사용하여 오류 처리 방식을 더 유연하게 만들 수 있습니다. 렌더 프롭은 컴포넌트가 무언가를 렌더링하는 데 사용하는 함수형 prop입니다.


class ErrorBoundary extends React.Component {
  // ... (이전과 동일)

  render() {
    if (this.state.hasError) {
      // 렌더 프롭을 사용하여 대체 UI 렌더링
      return this.props.fallbackRender(this.state.error, this.state.errorInfo);
    }

    return this.props.children;
  }
}

function App() {
  return (
    <ErrorBoundary fallbackRender={(error, errorInfo) => (
      <div>
        <h2>문제가 발생했습니다!</h2>
        <p>오류: {error.message}</p>
        <details style={{ whiteSpace: 'pre-wrap' }}>
          {errorInfo.componentStack}
        </details>
      </div>
    )}>
      <MyComponentThatMightThrow/>
    </ErrorBoundary>
  );
}

이를 통해 오류 경계별로 대체 UI를 맞춤 설정할 수 있습니다. fallbackRender prop은 오류 및 오류 정보를 인수로 받아, 오류에 따라 더 구체적인 오류 메시지를 표시하거나 다른 조치를 취할 수 있게 해줍니다.

2. 고차 컴포넌트(HOC)로서의 오류 경계

다른 컴포넌트를 오류 경계로 감싸는 고차 컴포넌트(HOC)를 만들 수 있습니다. 이는 동일한 코드를 반복하지 않고 여러 컴포넌트에 오류 경계를 적용하는 데 유용할 수 있습니다.


function withErrorBoundary(WrappedComponent) {
  return class WithErrorBoundary extends React.Component {
    render() {
      return (
        <ErrorBoundary>
          <WrappedComponent {...this.props} />
        </ErrorBoundary>
      );
    }
  };
}

// 사용법:
const MyComponentWithErrorHandling = withErrorBoundary(MyComponentThatMightThrow);

withErrorBoundary 함수는 컴포넌트를 인수로 받아 원본 컴포넌트를 오류 경계로 감싸는 새로운 컴포넌트를 반환합니다. 이를 통해 애플리케이션의 모든 컴포넌트에 쉽게 오류 처리를 추가할 수 있습니다.

오류 경계 테스트하기

오류 경계가 올바르게 작동하는지 확인하기 위해 테스트하는 것이 중요합니다. Jest나 React Testing Library와 같은 테스트 라이브러리를 사용하여 오류 경계를 테스트할 수 있습니다.

다음은 React Testing Library를 사용하여 오류 경계를 테스트하는 예시입니다:


import { render, screen, fireEvent } from '@testing-library/react';
import ErrorBoundary from './ErrorBoundary';

function ComponentThatThrows() {
  throw new Error('이 컴포넌트는 오류를 발생시킵니다');
}

test('오류가 발생했을 때 대체 UI를 렌더링합니다', () => {
  render(
    <ErrorBoundary>
      <ComponentThatThrows />
    </ErrorBoundary>
  );

  expect(screen.getByText('문제가 발생했습니다.')).toBeInTheDocument();
});

이 테스트는 오류를 발생시키는 ComponentThatThrows 컴포넌트를 렌더링합니다. 그런 다음 테스트는 오류 경계에 의해 렌더링된 대체 UI가 표시되는지 확인합니다.

오류 경계와 서버 컴포넌트 (React 18+)

React 18 이상에서 서버 컴포넌트가 도입되면서, 오류 경계는 오류 처리에서 계속해서 중요한 역할을 합니다. 서버 컴포넌트는 서버에서 실행되고 렌더링된 결과물만 클라이언트로 보냅니다. 핵심 원칙은 동일하지만, 고려해야 할 몇 가지 미묘한 차이가 있습니다:

서버 사이드 오류 로깅: 서버 컴포넌트 내에서 발생하는 오류를 서버에서 기록하고 있는지 확인하세요. 여기에는 서버 사이드 로깅 프레임워크를 사용하거나 오류 추적 서비스로 오류를 보내는 것이 포함될 수 있습니다.
클라이언트 사이드 대체 UI: 서버 컴포넌트가 서버에서 렌더링되더라도, 오류 발생 시를 대비하여 클라이언트 사이드 대체 UI를 제공해야 합니다. 이는 서버가 컴포넌트를 렌더링하지 못하더라도 사용자가 일관된 경험을 할 수 있도록 보장합니다.
스트리밍 SSR: 스트리밍 서버 사이드 렌더링(SSR)을 사용할 때 스트리밍 과정에서 오류가 발생할 수 있습니다. 오류 경계는 영향을 받는 스트림에 대한 대체 UI를 렌더링하여 이러한 오류를 정상적으로 처리하는 데 도움이 될 수 있습니다.

서버 컴포넌트의 오류 처리는 계속 발전하는 분야이므로, 최신 모범 사례와 권장 사항을 최신 상태로 유지하는 것이 중요합니다.

피해야 할 일반적인 함정

오류 경계에 대한 과도한 의존: 오류 경계를 컴포넌트 내의 적절한 오류 처리를 대체하는 수단으로 사용하지 마세요. 항상 오류를 정상적으로 처리하는 견고하고 신뢰할 수 있는 코드를 작성하도록 노력하세요.
오류 무시하기: 오류 경계에 의해 포착된 오류를 기록하여 문제의 근본 원인을 추적할 수 있도록 하세요. 단순히 대체 UI를 표시하고 오류를 무시하지 마세요.
유효성 검사 오류에 오류 경계 사용하기: 오류 경계는 유효성 검사 오류를 처리하는 데 적합한 도구가 아닙니다. 대신 더 구체적인 유효성 검사 기법을 사용하세요.
오류 경계 테스트하지 않기: 오류 경계가 올바르게 작동하는지 확인하기 위해 테스트하세요.

결론

오류 경계는 견고하고 신뢰할 수 있는 React 애플리케이션을 구축하기 위한 강력한 도구입니다. 오류 경계를 효과적으로 구현하고 사용하는 방법을 이해함으로써 사용자 경험을 개선하고, 애플리케이션 충돌을 방지하며, 디버깅을 단순화할 수 있습니다. 오류 경계를 전략적으로 배치하고, 유익한 대체 UI를 제공하며, 오류를 기록하고, 오류 경계를 철저히 테스트하는 것을 기억하세요.

이 가이드에서 설명한 지침과 모범 사례를 따르면, React 애플리케이션이 오류에 대해 복원력을 갖추고 사용자에게 긍정적인 경험을 제공하도록 할 수 있습니다.