DOCS/book/300_architecture/313_React_구조_원칙.md

React 프론트엔드 구조 원칙

작성일: 2025-11-29 수정일: 2025-11-29 참고: 311_FastAPI_구조_원칙.md, 312_문서_작성_원칙.md

1. 컴포넌트 설계 원칙

Single Responsibility Principle (SRP)

• 각 컴포넌트는 하나의 책임만 수행
• 큰 컴포넌트는 작은 서브 컴포넌트나 훅으로 분리
• UI 렌더링과 비즈니스 로직 분리

컴포넌트 분리 기준

• 300줄 이상: 서브 컴포넌트 또는 커스텀 훅으로 분리 검토
• 1000줄 이상: Monolithic Component로 간주, 리팩토링 필수
• UI + API + State + Events 모두 혼재: 계층 분리 필요

2. 비즈니스 로직 분리

Custom Hooks 패턴

• 데이터 fetching 로직: useFetch, useQuery 등 커스텀 훅으로 추출
• 상태 관리 로직: useState 복잡도가 높으면 커스텀 훅으로 분리
• UI 컴포넌트는 렌더링과 이벤트 핸들링만 담당

계층 분리

UI Components (렌더링)
    ↓
Custom Hooks (비즈니스 로직)
    ↓
API Services (통신)
    ↓
State Management (전역 상태)

3. 상태 관리 원칙

Immutability

• 상태 직접 변경 금지: 항상 새로운 객체/배열 생성
• 예측 가능한 상태 업데이트 보장
• React 리렌더링 최적화

상태 관리 전략

• 컴포넌트 내부 상태: useState (로컬 UI 상태)
• 전역 상태: Context API 또는 상태 관리 라이브러리 (Zustand/Recoil)
• 서버 상태: React Query, SWR 등 전용 라이브러리

Prop Drilling 회피

• 3단계 이상 props 전달 시 Context API 또는 상태 관리 도입
• 불필요한 중간 컴포넌트 통과 제거

4. 파일 및 폴더 구조

권장 구조

src/
├── components/          # 재사용 가능한 UI 컴포넌트
│   ├── ui/             # 기본 UI 컴포넌트 (버튼, 입력 등)
│   └── features/       # 기능별 컴포넌트
├── hooks/              # 커스텀 훅
├── services/           # API 통신 로직
├── stores/             # 전역 상태 관리 (선택)
├── utils/              # 유틸리티 함수
├── types/              # TypeScript 타입 정의
└── pages/              # 페이지 컴포넌트

파일 명명 규칙

• 컴포넌트: PascalCase.tsx (예: ChatInterface.tsx)
• 훅: use 접두사 + PascalCase.ts (예: useChat.ts)
• 유틸: camelCase.ts (예: formatDate.ts)
• 타입: PascalCase.ts (예: Message.ts)

5. 네이밍 규칙

명확한 네이밍

• 구체적이고 설명적인 이름 사용
• 축약어 지양, 의도가 명확한 이름
• 예: handleSendMessage > handleSend, chatHistory > data

변수/함수 네이밍

• 컴포넌트: PascalCase
• 함수: camelCase, 동사로 시작 (handle, fetch, update)
• 상수: UPPER_SNAKE_CASE
• boolean: is, has, should 접두사

6. 코드 품질 원칙

useEffect 의존성 관리

• 의존성 배열 정확히 명시
• 중복 호출 및 무한 루프 방지
• cleanup 함수 적절히 사용

성능 최적화

• 불필요한 리렌더링 방지: React.memo, useMemo, useCallback 적절히 활용
• 대용량 리스트: 가상화 (virtualization) 고려
• 이미지/리소스: lazy loading 적용

타입 안전성

• TypeScript 타입 정의 명확히
• any 타입 최소화
• 인터페이스/타입 재사용

7. 금지 사항

• ❌ 하드코딩된 값: 상수, 설정값은 환경변수 또는 설정 파일로 관리
• ❌ Monolithic Component: 1000줄 이상 컴포넌트
• ❌ 컴포넌트 내 비즈니스 로직: 커스텀 훅으로 분리
• ❌ 상태 직접 변경: Immutability 원칙 위반
• ❌ console.log 디버그 코드: 프로덕션 코드에 남기지 않음
• ❌ 순환 import
• ❌ Prop Drilling: 3단계 이상 전달 시 상태 관리 도입

8. 체크리스트

코드 작성 전/후 확인:

• 각 컴포넌트가 단일 책임을 수행하는가?
• 비즈니스 로직이 커스텀 훅으로 분리되었는가?
• 상태 변경이 Immutability 원칙을 따르는가?
• 파일 크기가 300줄 이하인가? (예외: 핵심 컴포넌트는 가급적 유지)
• 하드코딩된 값이 없는가?
• Prop Drilling이 3단계 이상인가? (상태 관리 필요)
• TypeScript 타입이 명확히 정의되었는가?
• useEffect 의존성이 정확한가?

9. 참고

• 상위 원칙: 이 문서는 일반적인 React 프로젝트 원칙을 다룹니다.
• 프로젝트별 특화 규칙: 각 프로젝트의 README나 문서에 추가 규칙 명시
• 백엔드 원칙: 311_FastAPI_구조_원칙.md 참고
• 문서 작성 원칙: 312_문서_작성_원칙.md 참고