FSD 아키텍처 정리

FSD란 무엇인가?

FSD(Feature Sliced Design) 는 프론트엔드 애플리케이션을 위한 아키텍처 방법론입니다.
그 뿌리는 FDA(Feature Driven Architecture) 에 두고 있으며, 핵심 아이디어는 코드를 기능(Feature) 단위로 슬라이싱하여 관심사를 명확하게 분리하고, 모듈 간 의존성을 항상 단방향으로 유지하는 것입니다.

💡 왜 FSD가 필요할까?
프로젝트 규모가 커질수록 코드 간 의존성이 복잡해지고, 어떤 파일을 수정했을 때 어디까지 영향을 미치는지 파악하기 어려워집니다. FSD는 이 문제를 구조적으로 해결합니다.

전체 구조 한눈에 보기

FSD는 3단계 계층 구조로 이루어져 있습니다.
계층 순서는 Layers → Slices → Segments 입니다.

1. Layers (레이어)

레이어는 FSD의 첫 번째 계층으로, 애플리케이션 전반에 걸친 코드를 역할에 따라 분류한 단위입니다.

핵심 규칙

상위 레이어는 하위 레이어를 의존할 수 있지만, 하위 레이어는 절대로 상위 레이어를 의존할 수 없습니다.
이 규칙 덕분에 의존성 그래프가 항상 한 방향(위 → 아래)으로만 흐르고, 특정 레이어를 수정했을 때 영향 범위가 명확하게 한정됩니다.

• 아래로 내려갈수록 → 추상화가 심화 (비즈니스를 모르는 순수한 코드)
• 위로 올라갈수록 → 비즈니스 로직이 심화 (도메인 지식이 담긴 코드)

레이어 목록

레이어별 코드 예시

shared — 비즈니스 로직 없는 순수 공통 코드

// shared/api/base.ts — axios 인스턴스 설정
import axios from 'axios';

export const httpClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  withCredentials: true,
});

entities — 도메인 모델 및 API 호출

// entities/user/api/getUser.ts
import { httpClient } from '@/shared/api/base';
import { UserDTO } from '../model/types';

export const getUser = (id: string): Promise<UserDTO> =>
  httpClient.get(`/users/${id}`).then(res => res.data);

features — 사용자 인터렉션 로직

// features/auth-form/model/useLogin.ts
import { login } from '@/entities/session';

export const useLogin = () => {
  const handleSubmit = async (form: LoginForm) => {
    await login(form); // entities 레이어 의존 (허용)
  };
  return { handleSubmit };
};

2. Slices (슬라이스)

슬라이스는 FSD의 두 번째 계층으로, 각 레이어 안에서 비즈니스 도메인 단위로 코드를 묶는 폴더입니다.

핵심 규칙

• 이름은 비즈니스 도메인 기반으로 자유롭게 결정합니다. (auth-form, user-profile, cart 등)
• app과 shared 레이어에는 슬라이스를 두지 않습니다.
  • app → 앱 전체에 관련된 단일 코드 집합
  • shared → 도메인 지식이 없는 순수 추상 코드이므로 도메인 분리 불필요
• 슬라이스 내부 파일은 반드시 세그먼트 폴더 안에 위치해야 합니다. 세그먼트 없이 파일을 직접 두면 안 됩니다.
• 슬라이스는 반드시 index.ts** (Public API)** 를 가져야 합니다.

Public API가 중요한 이유

슬라이스 내부 구조가 어떻게 바뀌든, 외부에서는 index.ts를 통해서만 접근합니다. 덕분에 내부 리팩토링을 해도 외부 코드에 영향을 주지 않습니다.

// features/auth-form/index.ts
export { AuthForm } from './ui';         // UI 컴포넌트 공개
export * as authFormModel from './model'; // 모델 네임스페이스로 공개

외부에서는 이렇게 사용합니다:

import { AuthForm, authFormModel } from '@/features/auth-form';
//                                         ↑ index.ts를 통해서만 접근

디렉토리 구조 예시

features/
  ├── auth-form/
  │     ├── ui/
  │     │     └── AuthForm.tsx
  │     ├── model/
  │     │     ├── useLogin.ts
  │     │     └── types.ts
  │     ├── api/
  │     │     └── loginApi.ts
  │     └── index.ts     ← Public API (필수!)
  └── user-profile/
        ├── ui/
        ├── model/
        └── index.ts

3. Segments (세그먼트)

세그먼트는 FSD의 마지막 계층으로, 슬라이스 내부에서 기술적인 역할에 따라 코드를 분류하는 폴더입니다.

세그먼트 종류

💡 세그먼트 이름이 정해진 것은 아닙니다. 프로젝트에 맞게 hooks/, store/ 등을 추가할 수 있습니다.

의존성 흐름 정리

[app]
  ↓ 의존 가능
[pages]
  ↓
[widgets]
  ↓
[features]
  ↓
[entities]
  ↓
[shared]

• features에서 entities를 import하는 것 ✅
• entities에서 features를 import하는 것 ❌
• shared에서 어떤 상위 레이어도 import하는 것 ❌

핵심 원칙 5가지

1. 단방향 의존성 — 상위 레이어 → 하위 레이어 방향만 허용
2. Public API 필수 — 각 슬라이스는 index.ts로만 외부에 노출
3. 도메인 기반 슬라이싱 — 슬라이스 이름은 비즈니스 도메인 기반으로 결정
4. 세그먼트 내 배치 — 모든 파일은 반드시 세그먼트 폴더 안에 위치
5. 영향 범위 최소화 — 의존성 그래프의 영향이 일부 레이어에만 국한되도록 설계

자주 하는 실수

참고 자료

• FSD 공식 문서
• FSD GitHub