데이터를 그리기 위한 FrontEnd 언어 공부하기 : React 프로젝트의 폴더 구조 FSD(Feature-Sliced Design) 아키텍쳐.

▽ 데이터를 그리기 위한 FrontEnd 언어 공부하기 : React 프로젝트의 폴더 구조 FSD(Feature-Sliced Design) 아키텍쳐.

목  차

1. 📌 FSD 아키텍쳐란?

2. 📌 레이어 (Layers)

3. 📌 슬라이스 (Slices)

4. 📌 세그먼트 (Segments)

5. 📌 엄격한 공개 API 정의 규칙

6. 📌 결론 및 정리.

1. 📌 FSD 아키텍쳐란?

---

Feature-Sliced Design(FSD) 은
대규모 프론트엔드 애플리케이션(특히 React 기반)의 구조를 "기능 단위로 구조화"하는 아키텍처 패턴.!

직역하면 "기능 분할 설계"입니다.
간단히 말하면, 코드를 조직적으로 구성하기 위한 규칙과 관계의 모음.

“기능(feature) 중심의 독립적이고 유지보수 가능한 구조를 만드는 것”
— FSD 공식 철학

• 이 방법론의 주요 목적은 애플리케이션을 '기능 단위로 분할'하여
  프로젝트를 더 이해하기 쉬운 구조로 만들기.
  • 프로젝트의 규모가 커져도 유지보수에 유리하도록 하는 데 있음.

🎯 핵심 목적

• 기능 단위로 코드 분리 → 유지보수성과 재사용성 향상

• UI와 비즈니스 로직의 결합도 최소화

• 확장 가능한 구조로 리팩토링 부담 최소화

💡 기존 구조와 비교.

구조 방식	예시	문제점
폴더 기반 구조	components/, pages/, hooks/	코드가 점점 뒤섞이고 의존성 꼬임
도메인 기반 구조	users/, products/	기능의 경계가 불명확
✅ FSD 구조	features/, entities/, shared/ 등 계층적 구조	의존 방향과 공개 규칙이 명확

• FSD의 계층 구조는 크게 {레이어,슬라이스,세그먼트}로 나뉘며,
  이는 프로젝트의 폴더 구조 트리로 볼 수 있음.

• 폴더 구조의 최상위에는 '레이어(Layers)'가 위치하고,

  • 각 레이어는 슬라이스(Slices)를 포함.
    • 단 app과 shared는 슬라이스를 가지지 않고 직접 세그먼트를 포함.
  • 또한, 각 슬라이스는 세그먼트를 포함.

• 레이어의 이름은 제한적이지만,

  • 슬라이스(Slice)와 세그먼트(segment)의 이름은 자유롭게 선택 가능하며 필요한 만큼 만들 수 있음.
    • 슬라이스는 보통 비즈니스 도메인 별로 분류,
    • 세그먼트는 일반적으로 몇 가지 관례적인 이름을 사용.

2. 📌 레이어 (Layers)

---

레이어란?

"레이어"는
프로젝트를 최상위부터 가장 기본적인 요소까지 단계적으로 나누어 구성한 폴더구조의 기본 계층.

• FSD의 레이어는 [ app, process, pages, widgets, features, entities, shared ]
  총 7개로 구성.(현재는 processes 레이어 제외 6개의 레이어만 사용).
  • 각 레이어는 "명확한 역할과 의존 방향(하위 -> 상위)을 가짐.

src/
├── app/
├── processes/  <-- 현재는 사용되지 않는 레이어.
├── pages/
├── widgets/
├── features/
├── entities/
└── shared/

레이어	역할	예시
shared	공통 리소스 (유틸, UI 컴포넌트, 타입 등)	Button, apiClient, helpers
entities	핵심 도메인 모델	User, Product, Order
features	특정 기능 단위	auth/login, cart/add-item
widgets	UI 단위 조합 (기능+엔티티+뷰)	Header, Sidebar, ProfileWidget
pages	라우트 단위의 화면 조합	/login, /product/:id
processes	전체 프로세스 관리(흐름 제어, 인증 흐름 등)	auth-process, checkout-process
app	앱 초기화 (라우터, 스토어, 전역 설정)	App.tsx, providers/

⚙️ 의존성 방향 규칙:
shared → entities → features → widgets → pages → processes → app
(하위 레이어는 상위 레이어를 절대 import하지 않는다.)

• 말했다시피, 각 레이어는 고유한 목적을 가지고 있으며, 반드시 모든 레이어를 사용할 필요는 없음.

• 그러나, 사용시에는 일관된 구조와 명명 규칙을 지켜 프로젝트를 더 이해하기 쉽고
  유지보수가 용이하게 해야 함.

  • 따라서, 사용 시에는 각 레이어의 이름을 정확히 지켜야 함.

💡 App 레이어.

프로젝트의 진입점이자, 가장 상위의 '전역 설정'을 포함하는 레이어.

• 주로 앱의 시작점이나, 주요 설정을 관리.
• '라우팅', '글로벌 스타일', '최상위 프로바이더' 등을 포함.

• 앱이 시작할 때 특정 테마를 적용하거나, 글로벌 상태 관리를 초기화할 필요가 있는 경우,
  'App' 레이어에서 이를 설정 가능.

• 쉽게 말하자면, 'App' 레이어는 애플리케이션의 전반적인 구성을 관리하는 곳.

  • 프로젝트의 루트 구성과 초기 설정이 이루어지는 곳.
  • 모든 애플리케이션의 구성 요소가 이 레이어에서 시작.
    • Ex) 'ThemeProvider'를 사용해 전체 앱에 다크모드 또는 라이트모드를 적용하는 설정을 포함 가능.

• 'App' 레이어는 "애플리케이션 전체의 전역 설정"만 담당하는 레이어이기에 슬라이스가 없고 세그먼트만 가짐.

  • 애플리케이션의 전역 설정들이 한 곳에서 모여 있어야 관리가 편리하기 때문.
    • 예를 들어, 라우팅, 전역 스타일, 테마 설정은 애플리케이션 전반에 걸쳐서 한 번만 설정해두면 되며,
      여러 위치에 분산될 필요가 없다.

• 세그먼트로 바로 모아두면 프로젝트 시작 시 설정해야 하는 모든 전역 설정들을 쉽게 찾아 수정 가능.

• 반면, 슬라이스는 기능별로 더 세분화해 나누는 구조라 App 레이어의 간단한 전역 설정에 사용될 필요가 없다.

💡 Processes 레이어 (현재는 사용되지 않음).

Processes 레이어는 페이지 간의 복잡한 시나리오나 워크플로를 관리하기 위해 사용.

• 예를 들어, 사용자 가입이나 결제 처리처럼 여러 페이지에 걸쳐 진행되는 복잡한 절차를 포함했었음.

• 복잡성 증가와 다른 레이어와의 중복성 때문에 현재는 사용이 권장되지 않음.

대신!, 이와 같은 흐름은 Pages 또는 Widgets 레이어로 분산하여 관리 가능.

💡 Pages 레이어.

Pages 레이어는 앱 내 개별 페이지를 정의하는 레이어.

• 특정 URL에 매핑되는 전체 페이지를 구성.

• 주로 라우팅과 관련된 파일이나 페이지에 해당하는 최상위 컴포넌트를 포함.

Ex)

• /home, /profile, /settings와 같은 각각의 페이지를 구성하는 컴포넌트들이 이에 해당.

Pages 레이어는 사용자에게 바로 노출되는 UI 요소이므로 복잡한 비즈니스 로직보다는 사용자 인터페이스와 관련된 로직을 처리.

• 이 레이어는 사용자에게 보여지는 완전한 페이지를 구성.

• UserPage와 같은 경우 사용자 관련 정보와 관련된 여러 widgets와 features가 함께 모여 하나의 페이지를 이룸.

  • ex) UserPage는 사용자 프로필 정보, 설정 관리, 활동 내역 등의 다양한 위젯을 포함해 구성

💡 Widgets 레이어.

Widgets 레이어는 페이지 내에서 독립적으로 작동하는 큰 기능 단위를 포함하는 레이어.

• 이 레이어는 독립적으로 기능하는 큰 규모의 UI 컴포넌트나 기능 블록을 구성하여 다양한 페이지에서 재사용 가능.
  • ex) 검색 바, 대시보드, 사이드바 메뉴 등등.

Widgets는 독립적으로 기능할 수 있으며 다양한 페이지에서 재사용 가능.

• 쉽게 말해, 하나의 위젯은 여러 개의 features와 entities를 포함하여 더 높은 수준의 UI를 구성.
  • Ex) UserProfile 위젯은 사용자의 정보(사진, 이름, 팔로워 수 등)를 표시하는 컴포넌트로 구성
    • 이 위젯에는 FollowUser와 같은 features 레이어의 기능이 포함되어
      사용자가 다른 사용자를 팔로우할 수 있는 기능을 제공.
      • 이러한 위젯은 UserPage, HomePage 등 여러 페이지에서 재사용 가능.

💡 Features 레이어.

Features 레이어는 재사용 가능한 비즈니스 기능을 위한 레이어로,
'독립적으로 동작'할 수 있는 하나의 특정 동작을 정의.

EX)

• 사용자 팔로우 기능 (FollowUser)은 features 레이어에 위치해 재사용 가능하고
  독립적인 비즈니스 기능으로 동작.

features는 다양한 페이지와 위젯에서 사용할 수 있도록 기능을 추상화하는 레이어.

일부 슬라이스의 model 세그먼트에 비즈니스 로직이 포함되어 있더라도, features 레이어는 여전히 필요.

• 이유는 features 레이어가 여러 페이지와 위젯에서 재사용 가능한 독립적 비즈니스 로직을 제공하기 때문.
  • 이 레이어가 없으면 동일한 비즈니스 기능을 구현할 때마다 중복 코드가 발생할 가능성이 높아짐.
    • 특정 기능을 유지보수하거나 업데이트할 때 여러 페이지와 위젯에서 동일한 수정이 필요해 비효율적.

• 따라서 특정 레이어의 model 세그먼트에 해당 레이어 전용 로직을 포함할 수는 있지만,
  재사용성과 독립성을 위해 보편적인 비즈니스 로직은 features 레이어에 두는 것이 좋음.

  • 이렇게 하면 여러 페이지에서 동일한 features 기능을 가져다 사용할 수 있어서
    확장성과 유지보수성이 향상된다.

💡 Entities 레이어.

Entities 레이어는 프로젝트에서 다루는 비즈니스의 핵심 데이터를 나타내는 레이어.

• 이 레이어에는 주로 데이터 모델과 해당 데이터에 대한 로직이 포함.

Ex)

• User 엔터티는 사용자 관련 정보를 관리하며,
  이름, 이메일, 프로필 사진 등 사용자의 주요 정보를 다룸.

• Entities 레이어는 다양한 페이지와 위젯에서 사용되는 비즈니스 핵심 데이터와 관련 로직을 제공

💡 Shared 레이어.

Shared 레이어는 프로젝트 전반에서 재사용할 수 있는 유틸리티, 기본적인 컴포넌트, 스타일 등의 전반적인 리소스를 포함하는 레이어

• 이 레이어의 요소들은 특정 기능이나 비즈니스에 국한되지 않고 전반적으로 사용.

Ex)

• Button 컴포넌트는 shared 레이어에서 제공.
  • 이 컴포넌트는 스타일과 인터랙션을 정의해 여러 기능과 페이지에서 재사용.
  • 다양한 스타일을 지원하는 Button 컴포넌트는
    FollowUser 기능이나 UserPage와 같은 여러 페이지와 위젯에서 쉽게 활용.

shared 레이어도 app 레이어와 마찬가지로 슬라이스가 없는데,
이유는 이 레이어가 전역적으로 재사용 가능한 요소들만 모아두기 위한 공간이기 때문.

shared는 프로젝트 전반에서 공통으로 사용할 수 있는 유틸리티, 기본 컴포넌트, 스타일 등을 포함하며, 특정 기능이나 비즈니스 로직과는 무관.

슬라이스는 보통 특정 기능이나 비즈니스 도메인에 맞춰 세분화할 때 사용되는데,

• shared 레이어는 모든 기능에서 공통으로 사용할 수 있는 요소들을 제공하기 때문에
  따로 나누지 않고 하나의 모음으로 관리하는 것이 더 효율적.
  • 이로 인해 shared의 요소들은 프로젝트 어느 부분에서도 자유롭게 사용할 수 있으며,
    코드의 중복을 줄이고 유지보수성을 높일 수 있음.

3. 📌 슬라이스 (Slices)

---

4. 📌 세그먼트 (Segments)

---

5. 📌 엄격한 공개 API 정의 규칙

---

6. 📌 결론 및 정리.

---