React UI 패턴
핵심 원칙
- 오래된 UI 표시 금지 - 실제 로딩 중일 때만 로딩 스피너 표시
- 오류 항상 표시 - 사용자는 실패가 발생했음을 반드시 알아야 함
- 낙관적 업데이트 - UI가 즉각적으로 반응하는 경험 제공
- 점진적 공개 - 콘텐츠가 준비되는 대로 표시
- 우아한 성능 저하 - 부분적 데이터라도 없는 것보다 나음
로딩 상태 패턴
황금률
표시할 데이터가 없을 때만 로딩 표시기를 보여주십시오.
// 올바른 예 - 데이터가 없을 때만 로딩 표시
const { data, loading, error } = useGetItemsQuery();
if (error) return <ErrorState error={error} onRetry={refetch} />;
if (loading && !data) return <LoadingState />;
if (!data?.items.length) return <EmptyState />;
return <ItemList items={data.items} />;
// 잘못된 예 - 캐시된 데이터가 있어도 스피너 표시
if (loading) return <LoadingState />; // 다시 가져올 때 깜빡임!
로딩 상태 결정 트리
오류가 있습니까?
→ 예: 재시도 옵션이 있는 오류 상태 표시
→ 아니오: 계속 진행
로딩 중이고 데이터가 없습니까?
→ 예: 로딩 표시기 표시 (스피너/스켈레톤)
→ 아니오: 계속 진행
데이터가 있습니까?
→ 예, 항목 있음: 데이터 표시
→ 예, 빈 상태: 빈 상태 표시
→ 아니오: 로딩 표시 (대체)
스켈레톤 vs 스피너
| 스켈레톤을 사용하는 경우 | 스피너를 사용하는 경우 |
|---|---|
| 콘텐츠 모양을 알 때 | 콘텐츠 모양을 모를 때 |
| 목록/카드 레이아웃 | 모달 작업 |
| 초기 페이지 로드 | 버튼 제출 |
| 콘텐츠 플레이스홀더 | 인라인 작업 |
오류 처리 패턴
오류 처리 계층 구조
1. 인라인 오류 (필드 수준) → 양식 유효성 검사 오류
2. 토스트 알림 → 복구 가능한 오류, 사용자가 재시도 가능
3. 오류 배너 → 페이지 수준 오류, 데이터가 부분적으로 사용 가능
4. 전체 오류 화면 → 복구 불가능, 사용자 조치 필요
항상 오류 표시
중요: 절대 오류를 조용히 무시하지 마십시오.
// 올바른 예 - 오류가 항상 사용자에게 표시됨
const [createItem, { loading }] = useCreateItemMutation({
onCompleted: () => {
toast.success({ title: '항목 생성됨' });
},
onError: (error) => {
console.error('createItem 실패:', error);
toast.error({ title: '항목 생성 실패' });
},
});
// 잘못된 예 - 오류가 조용히 잡히고 사용자는 알 수 없음
const [createItem] = useCreateItemMutation({
onError: (error) => {
console.error(error); // 사용자에게 아무것도 보이지 않음!
},
});
오류 상태 컴포넌트 패턴
interface ErrorStateProps {
error: Error;
onRetry?: () => void;
title?: string;
}
const ErrorState = ({ error, onRetry, title }: ErrorStateProps) => (
<div className="error-state">
<Icon name="exclamation-circle" />
<h3>{title ?? '문제가 발생했습니다'}</h3>
<p>{error.message}</p>
{onRetry && (
<Button onClick={onRetry}>다시 시도</Button>
)}
</div>
);
버튼 상태 패턴
버튼 로딩 상태
<Button
onClick={handleSubmit}
isLoading={isSubmitting}
disabled={!isValid || isSubmitting}
>
제출
</Button>
작업 중 비활성화
중요: 비동기 작업 중에는 항상 트리거를 비활성화하십시오.
// 올바른 예 - 로딩 중 버튼 비활성화
<Button
disabled={isSubmitting}
isLoading={isSubmitting}
onClick={handleSubmit}
>
제출
</Button>
// 잘못된 예 - 사용자가 여러 번 탭할 수 있음
<Button onClick={handleSubmit}>
{isSubmitting ? '제출 중...' : '제출'}
</Button>
빈 상태
빈 상태 요구 사항
모든 목록/컬렉션에는 반드시 빈 상태가 있어야 합니다:
// 잘못된 예 - 빈 상태 없음
return <FlatList data={items} />;
// 올바른 예 - 명시적 빈 상태
return (
<FlatList
data={items}
ListEmptyComponent={<EmptyState />}
/>
);
상황별 빈 상태
// 검색 결과 없음
<EmptyState
icon="search"
title="검색 결과 없음"
description="다른 검색어를 시도해보세요"
/>
// 아직 항목이 없는 목록
<EmptyState
icon="plus-circle"
title="아직 항목이 없습니다"
description="첫 번째 항목을 만드세요"
action={{ label: '항목 만들기', onClick: handleCreate }}
/>
폼 제출 패턴
const MyForm = () => {
const [submit, { loading }] = useSubmitMutation({
onCompleted: handleSuccess,
onError: handleError,
});
const handleSubmit = async () => {
if (!isValid) {
toast.error({ title: '오류를 수정하세요' });
return;
}
await submit({ variables: { input: values } });
};
return (
<form>
<Input
value={values.name}
onChange={handleChange('name')}
error={touched.name ? errors.name : undefined}
/>
<Button
type="submit"
onClick={handleSubmit}
disabled={!isValid || loading}
isLoading={loading}
>
제출
</Button>
</form>
);
};
안티 패턴
로딩 상태
// 잘못된 예 - 데이터가 있는데 스피너 표시 (깜빡임 발생)
if (loading) return <Spinner />;
// 올바른 예 - 데이터 없을 때만 로딩 표시
if (loading && !data) return <Spinner />;
오류 처리
// 잘못된 예 - 오류 무시
try {
await mutation();
} catch (e) {
console.log(e); // 사용자는 알 수 없음!
}
// 올바른 예 - 오류 표시
onError: (error) => {
console.error('작업 실패:', error);
toast.error({ title: '작업 실패' });
}
버튼 상태
// 잘못된 예 - 제출 중에 버튼이 비활성화되지 않음
<Button onClick={submit}>제출</Button>
// 올바른 예 - 비활성화 및 로딩 표시
<Button onClick={submit} disabled={loading} isLoading={loading}>
제출
</Button>
체크리스트
UI 컴포넌트를 완료하기 전에:
UI 상태:
- 오류 상태가 처리되고 사용자에게 표시됨
- 로딩 상태가 데이터가 없을 때만 표시됨
- 컬렉션에 빈 상태 제공됨
- 버튼이 비동기 작업 중에 비활성화됨
- 버튼이 적절한 경우 로딩 표시기를 표시함
데이터 및 변이:
- 변이에 onError 핸들러가 있음
- 모든 사용자 작업에 피드백 (토스트/시각적)이 있음
다른 스킬과의 통합
- graphql-schema: 적절한 오류 처리와 함께 변이 패턴 사용
- testing-patterns: 모든 UI 상태 (로딩, 오류, 빈 상태, 성공) 테스트
- formik-patterns: 폼 제출 패턴 적용