2nd/10_Wiki/Topics/Architecture/React_Architecture.md

---
category: Unified
tags: [auto-consolidated, technical-documentation]
title: [[React 기능 중심 아키텍처와 컴포넌트 패턴 (React Architecture)]]
last_updated: 2026-05-02
---

# [[React 기능 중심 아키텍처와 컴포넌트 패턴 (React Architecture)]]

## 📌 Brief Summary
React Architecture는 컴포넌트, 상태 관리, 파일 구조를 체계적으로 설계하여 애플리케이션의 확장성, 유지보수성, 성능을 극대화하는 소프트웨어 시스템 디자인이다. 특정 아키텍처를 강제하지 않는 라이브러리의 특성을 보완하기 위해 기능(Feature) 중심의 모듈화와 단방향 의존성 규칙을 적용하여 비즈니스 로직과 UI의 결합을 최소화하는 것을 목표로 한다.

## 📖 Core Content
1. **기능 기반 구조 (Feature-based Structure)**
   - 기술적 타입(컴포넌트, 훅) 중심의 구조에서 벗어나 비즈니스 도메인별로 코드를 캡슐화하여 응집도를 높인다.
   - 관련된 API, 상태, 타입, 컴포넌트를 하나의 기능 폴더 내에 배치하여 수정 범위를 명확히 한다.
2. **Feature-Sliced Design (FSD)**
   - 현대 React 아키텍처의 표준으로, 앱을 `Shared`, `Entities`, `Features`, `Widgets`, `Pages`, `App` 계층으로 나눈다.
   - 상위 계층이 하위 계층에만 의존하는 **단방향 의존성**과 `index.ts`를 통한 **Public API** 규칙을 강제하여 결합도를 낮춘다.
3. **분산형 상태 관리 아키텍처**
   - 상태를 성격에 따라 로컬, 전역 앱 상태(Zustand/Redux), 서버 상태(TanStack Query), URL 상태로 세분화하여 관리한다.
   - Context API의 리렌더링 한계를 이해하고, 성능이 중요한 전역 상태에는 Selector 패턴이 지원되는 도구를 사용한다.
4. **클린 코드 및 SOLID 원칙**
   - 컴포넌트당 단일 책임(SRP)을 부여하고, 컴포넌트 합성을 통해 수정 없이 기능을 확장(OCP)한다.
5. **성능 및 복원력 설계**
   - React Server Components(RSC)를 통한 번들 최적화와 Error Boundary를 활용한 장애 격리 전략을 아키텍처 수준에서 수립한다.

## ⚖️ Trade-offs & Caveats
- **아키텍처 인지 부하**: FSD와 같은 엄격한 레이어링은 팀의 학습 곡선을 높이며, 간단한 수정에도 여러 파일을 건드려야 하는 'Boilerplate' 오버헤드를 유발할 수 있다.
- **과도한 캡슐화**: 기능을 너무 잘게 쪼갤 경우 기능 간 공통 로직(Shared)의 비대화를 초래하거나, 모듈 간 데이터 통신이 복잡해지는 트레이드오프가 있다.
- **라이브러리 종속성**: 특정 아키텍처에 최적화된 도구(예: Next.js와 RSC)를 선택할 경우, 향후 다른 프레임워크로의 전환 비용이 매우 높아진다.

## 🔗 Knowledge Connections
### Related Concepts
- **Feature-Sliced Design (FSD)**: 구조적 캡슐화와 의존성 제어의 핵심 (관계: 핵심 방법론)
- **State Management Architecture**: 데이터 흐름의 계층화 (관계: 데이터 레이어 설계)
- **SOLID Principles**: 확장 가능한 컴포넌트 설계의 근간 (관계: 설계 철학)

### Deeper Research Questions
1. FSD 구조에서 'Features'와 'Widgets' 계층의 책임 경계가 모호할 때, 어떤 비즈니스 기준을 적용해야 아키텍처의 일관성을 유지할 수 있는가?
2. RSC(서버 컴포넌트) 도입이 기존의 클라이언트 중심 상태 관리 아키텍처를 어떻게 단순화하거나 복잡하게 만드는가?
3. 아키텍처 규칙(단방향 의존성 등)을 어기는 코드 작성을 CI 단계에서 원천적으로 차단하기 위한 린트 규칙 커스터마이징 방안은?
4. 대규모 팀에서 마이크로 프론트엔드로 전환할 때, 중앙 집중식 아키텍처 거버넌스와 팀별 자율성 사이의 균형점은 어디인가?
5. React Compiler가 자동 메모이제이션을 수행할 때, 아키텍처적으로 '불변성(Immutability)'을 강제하는 것이 성능에 미치는 정량적 영향은?

### Practical Application Contexts
- **대규모 제품 설계**: 수백 개의 컴포넌트가 얽힌 엔터프라이즈급 SaaS의 확장 가능한 뼈대 구축.
- **성능 및 품질 개선**: 스파게티 코드로 변한 레거시 React 앱을 기능별 모듈로 격리 및 리팩토링.

### Adjacent Topics
- **Micro-Frontends**
- **Server Components (RSC)**
- **Test-Driven Development (TDD) in React**

---

- [[Framework_Practical_Patterns]]: 프레임워크별 다양한 실전 패턴 모음.
- [[Clean_Code]]: 가독성 높은 컴포넌트 작성을 위한 기반 원칙.
- [[Nextjs_Framework]]: React 기반의 서버 사이드 렌더링 확장 프레임워크.


## 1. 개요
현대적인 React 애플리케이션 설계는 단순히 UI 라이브러리 활용을 넘어, 대규모 프로젝트의 유지보수성과 확장성을 보장하기 위한 아키텍처적 접근을 요구한다. 기능 중심의 폴더 구조(Bulletproof React)와 선언적인 컴포넌트 패턴을 통해 코드 파편화를 방지하고, 비즈니스 로직과 UI 표현을 명확히 분리하는 것이 핵심이다.

## 2. 핵심 아키텍처 및 패턴
- **기능 중심 구조 (Feature-Based Structure)**: `src/features/` 디렉토리 하위에 도메인 기능별로 `components`, `hooks`, `api`, `types`, `store` 등을 응집시켜 캡슐화. 기능 간의 무분별한 참조를 제한하여 결합도를 낮춤.
- **컴포넌트 설계 패턴**:
  - **복합 컴포넌트 (Compound Components)**: 부모와 자식 컴포넌트가 협력하여 상태를 공유(Context 활용)함으로써, 유연하고 선언적인 UI 인터페이스 제공 (예: Tabs, Select, Modal).
  - **고차 컴포넌트 (HOC)**: 컴포넌트 로직을 재사용하기 위해 컴포넌트를 인자로 받아 새로운 컴포넌트를 반환하는 패턴 (예: 인증 처리 가드).
  - **렌더 프롭 (Render Props)**: 컴포넌트의 렌더링 로직을 함수 형태로 전달하여 UI 제어권을 부모에게 위임.
- **커스텀 훅 (Custom Hooks)**: UI와 무관한 비즈니스 로직이나 상태 관리 로직을 함수로 추출하여 여러 컴포넌트에서 재사용 가능하게 격리.

## 3. 상태 관리 전략
- **서버 상태 (Server State)**: TanStack Query (React Query) 등을 활용하여 비동기 데이터 페칭, 캐싱, 동기화를 전담 처리.
- **클라이언트 상태 (Client State)**: Zustand, Jotai 등 가벼운 상태 관리 라이브러리를 사용해 전역적으로 공유가 필요한 UI 상태 관리.
- **컴포넌트 로컬 상태**: `useState`, `useReducer`를 사용하여 개별 컴포넌트 내부에 닫힌 상태 유지.

## 4. 엔지니어링 가치
- **유지보수성 향상**: 기능별로 코드가 응집되어 있어, 특정 요구사항 변경 시 영향 범위를 해당 피처 내부로 한정 가능.
- **재사용성 극대화**: 잘 설계된 컴포넌트 패턴과 커스텀 훅은 프로젝트 전반에서 일관된 로직으로 재사용되어 중복 코드 제거.
- **팀 협업 최적화**: 표준화된 폴더 구조와 컨벤션을 통해 대규모 인원이 참여하는 프로젝트에서도 코드의 파편화 방지 및 예측 가능성 확보.

## 5. 트레이드오프 및 주의사항
- **초기 설계 오버헤드**: 기능 중심 구조를 구축하고 컴포넌트 패턴을 적용하는 과정에서 더 많은 보일러플레이트 코드와 설계적 고민이 필요함.
- **Props Drilling vs Context**: 전역 상태를 위해 Context API를 무분별하게 사용할 경우, 불필요한 리렌더링으로 인한 성능 저하(Provider Hell) 발생 가능.
- **추상화의 깊이**: 지나치게 복잡한 고차 컴포넌트나 렌더 프롭 패턴은 코드의 직관적인 독해를 방해할 수 있으므로 적절한 수준의 추상화 유지 필요.

## 🧪 검증 상태 (Validation)
- **정보 상태**: 검증 완료 (Verified)
- **출처 신뢰도**: A
- **검토 이유**: 대규모 웹 애플리케이션의 복잡성을 제어하고 일관된 고품질 사용자 경험을 제공하기 위한 React 중심의 프론트엔드 설계 표준 정립.