비동기 및 에러 처리 관련 문서 작성

[Cyjin-jani]

Summary

React 애플리케이션에서 비동기 처리와 에러 대응을 일관되게 설계하기 위한 핵심 지침 문서를 보강했습니다.
Suspense/Boundary 기반 선언적 처리, 실패 격리, 다중 쿼리 동시성, 에러 복구 기준을 팀 공통 규칙으로 정리하는 것이 목적입니다.

배경

프로젝트에서 비동기 처리와 에러 처리를 하는 경우, 아래와 같은 반복 이슈가 있었습니다.

• isLoading/isError 분기가 컴포넌트마다 반복되어 Happy Path가 흐려짐
• 페이지 최상단 단일 Boundary로 인해 일부 기능 실패가 전체 화면 실패로 확산됨
• 다중 쿼리 호출 위치 문제로 Waterfall이 발생해 체감 성능이 저하됨
• 인증 에러(401)와 도메인/서버 에러를 동일하게 처리해 UX가 어색해짐
• 에러 후 복구 경로가 불명확하거나 resetKeys 기준이 모호함

이 문제들에 대해 팀 차원의 일관된 판단 기준을 문서로 정리했습니다.

팀 합의 내용

• 선언적 비동기 처리: 로딩/에러는 상위 Boundary에 위임하고 하위 컴포넌트는 성공 상태 렌더링에 집중
• Boundary 설계: 독립 영역은 분리해 Partial Failure 허용, 결합된 과업은 묶어 UX 파편화 방지
• 다중 쿼리 동시성: 독립 쿼리는 같은 시점에 시작해 Waterfall 제거, 일부 실패 허용 시 Boundary 분리 또는 useQueries 선택
• 에러 복구 전략: 인증/권한 에러는 전역 처리, 지역 에러는 Boundary 위임. QueryErrorResetBoundary + resetKeys로 재시도/초기화 기준 명시

작성한 문서

문서	핵심 내용
docs/async-error-handling/declarative-async-basics.md	useSuspenseQuery 중심 선언적 패턴 정리, 예외 케이스(enabled, mutation 에러)의 명시적 처리 원칙 보강
docs/async-error-handling/boundary-design.md	도메인 경계 기준 분리/통합 원칙 정리, Partial Failure 허용과 UX 일관성 균형 제시
docs/async-error-handling/suspense-query-concurrency.md	same component/parent-child Waterfall 패턴과 제거 전략 추가, 일부 실패 허용 시 선택 기준 정리
docs/async-error-handling/error-handling-strategy.md	Global vs Local 처리 분리, 선언적 Retry, resetKeys 운영 기준 및 사용자 중심 메시지 원칙 보강
docs/async-error-handling/index.md	지침 목록 및 설명 문구 업데이트

변경 파일

• docs/async-error-handling/declarative-async-basics.md (신규)
• docs/async-error-handling/boundary-design.md (신규)
• docs/async-error-handling/suspense-query-concurrency.md (신규)
• docs/async-error-handling/error-handling-strategy.md (신규)
• docs/async-error-handling/index.md (지침 업데이트)
• docs/.vitepress/config.mts (사이드바 네비게이션 추가)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sipe_frontend_principles	Ready	Preview, Comment	May 1, 2026 1:16pm