✅ [22편] 리액트 프로젝트 아키텍처 설계 가이드

대규모 프로젝트를 위한 폴더 구조 · 상태 관리 · 서비스 계층 설계 (3000~4000자)
리액트는 비교적 자유도가 높은 라이브러리입니다.
이 때문에 작은 프로젝트에서는 장점이 되지만,
대규모 프로젝트에서는 구조가 무너지기 쉽고 유지보수성이 크게 떨어질 수 있습니다.
이번 글에서는 대규모 리액트 프로젝트의 설계 기준과 구조화 방법을 실무 중심으로 정리합니다.

🟦 1. 왜 리액트 아키텍처 설계가 중요한가?

리액트는 “어떻게 사용해야 한다”는 명확한 가이드가 없습니다.
그래서 다음과 같은 문제가 자주 발생합니다.
컴포넌트가 점점 비대해짐
폴더 구조 난잡
API 파일 여기저기 흩어짐
상태 관리 방식 제각각
같은 로직이 여러 곳에서 중복 발생
유지보수할수록 리스크 증가
이 문제들의 공통 원인은 초기 아키텍처 설계 부족입니다.

🟦 2. 실무에서 가장 많이 쓰는 폴더 구조 (베스트 프랙티스)

src/
├ components/
├ layouts/
├ pages/
├ hooks/
├ styles/
├ utils/
├ services/
├ store/
├ assets/
└ App.tsx
각 폴더의 역할을 살펴보겠습니다.
✔ components
재사용 가능한 UI들을 모아두는 영역
Button, Modal, Card 등
✔ layouts
페이지의 기본 틀
헤더/사이드바/푸터
✔ pages
각 라우트별 페이지 구성
✔ hooks
재사용 가능한 로직
useFetch, useInput, useToggle 등
✔ utils
순수 함수, 포맷터, 계산 로직
✔ services
API 통신 로직
axios 인스턴스, API 요청 함수 등
✔ store
전역 상태 관리
Redux, Zustand, Recoil 등
✔ assets
이미지, 아이콘, 폰트 파일 저장

🟦 3. Atomic Design 기반 컴포넌트 구조화

대규모 UI 시스템에서는 Atomic Design이 널리 쓰입니다.
✔ 구조
components/
├ atoms/
├ molecules/
├ organisms/
├ templates/
atoms: 버튼, 아이콘, 인풋
molecules: 입력폼, 검색박스
organisms: 헤더, 카드 리스트
templates: 페이지 기본 레이아웃
UI가 명확하게 계층화되어 협업 및 확장성이 뛰어납니다.

🟦 4. 서비스 계층(Service Layer) 분리

실무에서는 “API 요청 코드”를 컴포넌트 안에 넣으면 절대 안 됩니다.
잘못된 예:
useEffect(() => {
fetch("/api/product");
}, []);
올바른 예:
import ProductService from "@/services/ProductService";
이렇게 API 호출, 데이터 조작, 비즈니스 로직 등은 서비스 계층에서 관리해야 합니다.

🟦 5. 전역 상태 관리 전략 (Redux / Recoil / Zustand 선택 기준)

대규모 프로젝트에서는 상태 관리 라이브러리 선택이 매우 중요합니다.
✔ Redux
대규모 서비스에 적합
DevTools 강력
구조 명확
다소 코드량 많지만 안정성 최고
✔ Recoil
React스럽고 사용 쉬움
비동기 흐름 관리 편함
중·소규모 프로젝트 적합
✔ Zustand
매우 가벼운 상태관리
코드 적고 러닝커브 낮음
빠르게 만들고 유지보수 쉬움

🟦 6. 컴포넌트의 관심사 분리 (UI vs Logic)

컴포넌트에 너무 많은 로직을 넣으면 유지보수성이 떨어집니다.
✔ UI → 컴포넌트
✔ 로직 → 커스텀 훅 / 서비스 계층
이렇게 나누면 컴포넌트가 매우 간결해지고 테스트도 쉬워집니다.

🟦 7. 예측 가능하고 유지보수하기 쉬운 프로젝트 만들기

프로젝트가 커질수록 다음 두 가지가 핵심입니다.
✔ 일관성
이름 짓기 규칙, 폴더 구조, 컴포넌트 구조 유지
✔ 확장성
새 기능을 추가하더라도 기존 구조를 깨지 않는 방식 유지

🟦 8. 대규모 프로젝트에서 피해야 할 구조

다음 같은 구조는 절대 지양해야 합니다.
❌ 모든 파일이 components 폴더에 몰려 있는 구조
❌ API 요청을 컴포넌트마다 넣는 방식
❌ 상태 관리 라이브러리를 혼용하는 경우
❌ util, hook, component가 뒤섞인 폴더
❌ 페이지 파일에 500줄 넘는 거대한 컴포넌트
이런 구조는 프로젝트가 커질수록 유지가 거의 불가능합니다.

🟦 결론

리액트 아키텍처는 단순히 폴더를 나누는 수준이 아니라
프로젝트의 성장 속도와 유지보수성을 결정하는 핵심 요소입니다.
깔끔한 구조, 명확한 역할 분리, 일관된 규칙만 잘 적용해도
대규모 리액트 프로젝트는 훨씬 안정적이고 확장 가능한 애플리케이션이 됩니다.