이 글은 제가 현장에서 쓰는 Clean F.S.D(Feature‑Sliced Design × Server‑first) 기준을 정리한 실전 가이드입니다. 한 줄 원칙은 **“읽기는 Entities, 쓰기는 Features”** 입니다. ## 핵심 규칙(요약) ### Entities ↔ Features의 구분 = **읽기(Read)** ↔ **쓰기(Write)** * **Entities(읽기)** * **RSC(Server Component) + SELECT 전용**. * 입력(데이터)이 같으면 **항상 같은 마크업**을 내는 **순수 뷰**. * **상태/이벤트/라우터/부수효과 없음**(JS 번들·하이드레이션 제로 지향). * **Features(쓰기)** * **모든 쓰기**(도메인 DB, URL, 클라이언트 상태, 브라우저/네트워크 부수효과). * **상호작용/핸들러/로직의 소유권**. * 클라 컴포넌트(버튼/폼/옵저버)와 서버 액션을 **여기**에 둠. ### Features 쓰기: **두 가지 종류** 1. **도메인(server 데이터) 쓰기** * 예: Quiz 생성/수정/삭제, User 등록 등 **DB 쓰기** * **구성(권장)** * `features///action/*.ts` — **Server Action**(POST/PUT/DELETE) * `features///model/type.server.ts` — 서버 타입/스키마 * `features///ui.tsx` — 클라 폼/버튼/제출 2. **상태(client) 쓰기** * 예: **Infinite Scroll, Filter, Sort, Search, Pagination** … * **구성(권장)** * `features///model/state.ts` — 클라 상태/훅 * `features///ui.tsx` — 관찰자/토글/검색 입력 등 * 필요 시 `shared/lib/url/*`(쿼리 빌더)와 조합 ## 왜 이렇게 나누나? (현실적인 이유) * **번들/성능**: Entities는 **RSC**로 남겨 **JS/하이드레이션 제로**. 버튼 로직 섞이면 번들↑. * **재사용/조합**: 읽기 레이어를 **페이지 독립**으로 유지 → 다른 화면에서도 그대로 재사용. * **캐싱/불변성**: Entity는 **“같은 입력 = 같은 출력”**이라 캐시/스트리밍이 단순. * **테스트 경계**: Entity는 스냅샷/접근성, Feature는 상호작용(E2E)로 **관심 분리가 선명**. ## 현장의 룰 오브 썸(Thumb) 1. **`on*` 핸들러가 보이면 Features**로 옮긴다. 2. **라우터/URL을 만지면 Features**다. 3. **링크는 Entities**에 둬도 된다. * 단, 링크로 **조건 변경(필터/커서)**을 만들면 그 **href 계산은 Feature**가 책임. 4. 모호하면 **“Entities=읽기, Features=쓰기”**로 판단. > 결론: **클릭 이벤트가 있다는 이유만으로 “모든 버튼=Features”는 아니다.** > 다만 **현실적으로 버튼=행동** 이 성립하므로 **대부분 버튼은 Features**, **예외는 단순 링크** 정도. ## 분류표(빠르게 보기) | 상황 | 예시 | 분류 | 이유/가이드 | | ------------- | ------------------------- | -------------------- | ------------------------------------------- | | 상세 페이지로 이동 | \ | Entities | “자원 링크”는 서버 우선 흐름 보존. | | 리스트 정렬/필터 토글 | “제목 ↑/↓”, 검색 적용 | Features | URL/상태를 쓴다(query 변경). | | 페이지네이션/무한 스크롤 | 다음 페이지/커서 | Features | URL/상태 또는 관찰자 로직 소유. | | 삭제/수정/생성 | 행별 Delete | Features | 도메인 쓰기(서버 액션). | | 복사/다운로드 | 클립보드, CSV 생성 | Features | 클라 부수효과/스트리밍. | | 단순 파일 링크 | 정적 CSV \ | Entities or Features | 정적 경로면 Entities, 접근 제어나 준비 로직 있으면 Features. | | 모달 열기 | “자세히 보기” 모달 | Features | 클라 상태 소유. | ### 모달의 경우(경계 잡기) * 모달 열기 버튼이 **단순 자원 접근**이면 → **Entities(버튼)** * 모달이 **쓰기 진입 경로**(생성/수정/삭제)면 → **Features(버튼)** * 기능 묶음을 한 폴더에 모아 **경계 고정** → 유지보수/테스트 용이 ## 치트시트(프로덕션에서 자주 나오는 케이스) 핵심 질문 두 개만 기억하세요: **“무엇을 쓰는가(상태·URL·도메인·부수효과)?”** + **“행동의 소유권은 누구인가?”** ### A. 탐색/내비게이션 | 케이스 | 분류 | 설명 | | --------------------- | -------- | --------------------------------- | | 자원 상세로 이동(/posts/123) | Entities | 순수 읽기 흐름. RSC 내부 \ 허용. | | 뷰 상태 바꾸는 링크(필터/정렬/커서) | Features | URL 쿼리 쓰기. href 계산은 Feature 소유. | | 언어/로케일 전환(경로 기반) | Entities | 경로 자체가 자원 변화. 쿼리/쿠키 토글은 Features. | | 브레드크럼/사이드 내비(정적) | Entities | 조건/권한 분기는 Feature에서 props로 주입. | | 프리페치(hover/onView) | Features | 클라 부수효과/상태 쓰기. | ### B. 폼/입력/쓰기 플로우 | 케이스 | 분류 | 설명 | | -------------------- | ----------------------------- | --------------------------------------- | | Create/Update/Delete | Features | 서버 액션 POST/PUT/DELETE. | | Optimistic Update | Features | 롤백/토스트 등 UX 로직 포함. | | Draft/Autosave | Features | 로컬/IndexedDB/쿠키 쓰기. | | Inline Edit(셀) | Features | 입력·검증·제출 모두 행동 소유. Entity 테이블엔 슬롯으로 주입. | | 파일 업로드 | Features | presigned URL, 진행률/재시도/취소. | | CSV/Excel 내보내기 | Entities(정적) / Features(온디맨드) | 온디맨드는 서버 작업 트리거=쓰기. | ### C. 읽기 뷰 + 상호작용 | 케이스 | 분류 | 설명 | | -------------- | -------- | ------------------------------------ | | 테이블/카드/차트 표시 | Entities | DTO → 마크업(상태/이벤트 없음). | | 차트 줌/브러시/범례 토글 | Features | 상태/이벤트 소유. 프리미티브는 shared/ui. | | 멀티 선택/체크박스 | Features | 선택 상태/일괄 액션 소유. | | 태깅/즐겨찾기/핀 | Features | 도메인 쓰기 또는 URL/로컬 상태 쓰기. | | 툴팁/호버 디테일 | Features | 클라 상태/이벤트. 완전 CSS‑only면 Entities 가능. | ### D. 실시간/오프라인/동기화 | 케이스 | 분류 | 설명 | | ---------------- | ----------------------- | ------------------------- | | SSE/WebSocket 구독 | Features | 연결/해제/reconnect/백오프. | | Presence/Typing | Features (+ Entities 뷰) | 구독/머지=Feature, 표시=Entity. | | 오프라인 캐시/재동기화 | Features | SW/IndexedDB/Retry 정책. | | PWA 설치/푸시 | Features | 권한·토큰 관리·브라우저 API. | ### E. 접근 제어/보안 | 케이스 | 분류 | 설명 | | --------------- | -------- | -------------------------------------- | | Auth 가드(로그인/권한) | Features | 라우트 가드/리다이렉트/서버 액션 가드. | | 버튼 가시성/활성 제어 | Features | “행동 가능 여부” 판단=Feature, Entity엔 표시만 전달. | | 세션/토큰 갱신 | Features | 백그라운드 갱신/부수효과. | | CAPTCHA/봇 방지 | Features | 제출 전 검증/토큰 교환. | ### F. 라우팅/레이아웃(Next.js) | 케이스 | 분류 | 설명 | | ----------------------------------- | ------------------------------ | ---------------------------------- | | Parallel/Intercepted로 “읽기 상세를 모달처럼” | Entities(링크/닫기 링크) | 자원 이동=읽기. | | 쿼리 기반 모달/패널 토글 | Features | URL 쓰기. | | Middleware 리다이렉트(i18n/A‑B/권한) | Features | 정책/실험 로직. | | Metadata/SEO | Entities(정적) / Features(동적/실험) | 정적 메타=Entities, 실험/트래킹 결합=Feature. | ### G. 검색/저장된 보기 | 케이스 | 분류 | 설명 | | ------------------ | -------- | ------------------ | | 검색 결과 리스트 | Entities | 서버 읽기+렌더. | | Search‑as‑you‑type | Features | 디바운스/취소/하이라이트 상태. | | 저장된 필터/뷰 | Features | 사용자별 구성 저장=도메인 쓰기. | ### H. 설정/환경/개인화 | 케이스 | 분류 | 설명 | | ---------- | -------------------- | ---------------------------------- | | 테마 토글 | Features | 로컬/쿠키/시스템 프리퍼런스 동기화. | | 사용자 환경설정 | Features | 클라/서버 저장. | | i18n 언어 선택 | Entities or Features | 경로 기반=Entities, 상태/쿠키 토글=Features. | ### I. 통합/결제/백그라운드 | 케이스 | 분류 | 설명 | | ----------------- | -------- | ---------------------------- | | Webhook/Queue 트리거 | Features | 제출→잡 등록=쓰기. | | 결제 체크아웃 버튼 | Features | 세션 생성/리다이렉트/실패·취소 핸들. | | 상태 폴링/진행 표시 | Features | 폴링 주기/중단/리트라이. | | 감사 로그(Audit) 보기 | Entities | 읽기 전용(단, 내보내기 버튼은 Features). | ### J. 에러/로딩/빈 상태/스켈레톤 | 케이스 | 분류 | 설명 | | --------------- | ------------------- | -------------- | | 로딩 스켈레톤/빈 상태 문구 | Entities | 순수 표시(입력→마크업). | | 토스트/재시도 버튼 | Features | 상호작용/부수효과. | | 에러 바운더리 | Features(대개 Client) | 복구/재시도/로그 전송. | ### K. 분석/로그/실험 | 케이스 | 분류 | 설명 | | ------------ | -------- | ---------------------------- | | 뷰 임프레션 로깅 | Features | 클라 부수효과/전송. | | 클릭 트래킹/전환 계측 | Features | 행동과 결합(트래킹을 Entity에 심지 말 것). | | A/B 테스트 스위치 | Features | 배정/변형 노출 제어. | ### L. 지도/위치/DnD/캘린더 | 케이스 | 분류 | 설명 | | ------------------ | -------- | ------------------------------ | | 지도/캘린더 표시 | Entities | 가능하면 서버 스냅샷/이미지, 아니면 프리미티브 래퍼. | | 핀 이동/드래그 정렬/캘린더 생성 | Features | 상호작용/도메인 쓰기. | | 지오로케이션 권한/현재 위치 | Features | 브라우저 권한/부수효과. | ### M. SEO/정적 산출물 | 케이스 | 분류 | 설명 | | ------------------ | -------- | --------------------- | | 사이트맵/robots/OG(정적) | Entities | 읽기 산출물. | | OG 이미지 온디맨드 | Features | 파라미터 설계/트리거(실험 결합 시). | ### N. 페이지 보호/리디렉션 | 케이스 | 분류 | 설명 | | --------------- | -------- | ------------------------------- | | 권한 없는 접근 → 리디렉션 | Features | 미들웨어/서버 컴포넌트 가드. | | 임시 배너/공지 닫기 | Features | 로컬/쿠키 상태 쓰기(배너 뷰 자체는 Entities). | ## 폴더 구조 가이드(요약) ```json src/ ├─ app/ # 라우팅(RSC) · 조합 지점 │ └─ (routes …) ├─ entities/ │ └─ // # RSC + SELECT 전용 도메인 함수 │ ├─ action/get*.ts # Server(GET): 읽기 전용 │ └─ ui/*.tsx # 이벤트/상태 없는 순수 뷰 ├─ features/ │ └─ // # 상호작용(상태/URL/도메인 쓰기) │ ├─ action/*.ts # Server(POST/PUT/DELETE …) │ ├─ model/state.ts # (옵션) 클라 상태/훅 │ └─ ui.tsx # Client 컴포넌트(버튼/폼/옵저버/링크) ├─ widgets/ # 특정 조합 캡슐화(서버 컴포넌트) ├─ shared/ │ ├─ ui/ # 프리미티브(표시 전용) │ ├─ lib/ # url builders, schema, formatters │ ├─ auth/, db/, config/ # 공용 클라/서버 유틸 │ └─ analytics/, experiments/ # 계측·실험(Feature가 사용) ``` ## 결정 트리(헷갈릴 때) 1. 이 컴포넌트가 **어떤 형태로든 “쓰기”**(DB/URL/클라 상태/부수효과)를 **유발**하는가? → **예**: **Features** / **아니오**: 2로 2. 같은 입력을 넣으면 **항상 같은 마크업**을 내나? → **예**: **Entities** / **아니오**(시간/환경/권한에 따라 달라짐): 대개 **Features**에서 판단 후 **Entities**에 props로 주입 3. **링크**인가? * **자원 이동**이면 **Entities** * **뷰 조건 변경(쿼리/패널/모달 토글)**이면 **Features** ## 실무에서 자주 빠지는 함정(피해야 함) * **Entity 안에서 `useSearchParams`/`router.*` 호출** → **경계 붕괴**. * **Entity에 `onClick` 하나쯤…** → 번들/캐싱/테스트 전부 꼬인다. * **GET을 Server Action으로 남발** → 캐시/리트라이/중복 제거/DevTools 부재. * (필요 시 **API Route + React Query**를 Feature에서 사용해 **클라 캐싱/리트라이**를 명시적으로 관리) * **트래킹/실험 코드를 Entity에 심음** → 나중에 제거/변경 어려움, 테스트 흔들림. * **권한 로직을 Entity에서 분기** → UI 조각은 **표시만**, “허용/차단”은 **Feature**가 결정. > 주: 제 원칙은 **Server‑first + 최소 API 라우트**이지만, **디버깅/리트라이/오프라인** 요구가 큰 **상호작용적 읽기**라면, Feature 레이어에서 **API Route + 클라 캐시**로 전술 전환을 고려합니다. “순수 읽기(Entity)”와 “상호작용적 읽기(Feature)”를 구분하세요. ## 세 줄 요약 * **Entities = 읽기 전용 RSC 뷰 + SELECT 함수** (입력→마크업, **상태/이벤트/라우터/부수효과 없음**) * **Features = 모든 쓰기**(도메인·URL·클라 상태·부수효과) + **상호작용의 소유권** * 모호하면 **“행동의 소유권”**과 **“순수성(같은 입력=같은 출력)”**으로 결정하라. 핵심은 **경계 유지**와 **소유권 분리**입니다. 경계가 선명해질수록 번들·캐시·테스트가 쉬워지고, 유지보수 비용이 내려갑니다.

Clean F.S.D: Entities=읽기 / Features=쓰기 — 실무 치트시트

댓글 0개

Clean F.S.D: Entities=읽기 / Features=쓰기 — 실무 치트시트

댓글 0개