[1팀 박용태] Chapter 3-3 기능 중심 아키텍처와 프로젝트 폴더 구조

[piggggggggy]

과제 체크포인트

기본과제

목표 : 전역상태관리를 이용한 적절한 분리와 계층에 대한 이해를 통한 FSD 폴더 구조 적용하기

• 전역상태관리를 사용해서 상태를 분리하고 관리하는 방법에 대한 이해
• Context API, Jotai, Zustand 등 상태관리 라이브러리 사용하기
• FSD(Feature-Sliced Design)에 대한 이해
• FSD를 통한 관심사의 분리에 대한 이해
• 단일책임과 역할이란 무엇인가?
• 관심사를 하나만 가지고 있는가?
• 어디에 무엇을 넣어야 하는가?

체크포인트

• 전역상태관리를 사용해서 상태를 분리하고 관리했나요?
• Props Drilling을 최소화했나요?
• shared 공통 컴포넌트를 분리했나요?
• shared 공통 로직을 분리했나요?
• entities를 중심으로 type을 정의하고 model을 분리했나요?
• entities를 중심으로 ui를 분리했나요?
• entities를 중심으로 api를 분리했나요?
• feature를 중심으로 사용자행동(이벤트 처리)를 분리했나요?
• feature를 중심으로 ui를 분리했나요?
• feature를 중심으로 api를 분리했나요?
• widget을 중심으로 데이터를 재사용가능한 형태로 분리했나요?

심화과제

목표: 서버상태관리 도구인 TanstackQuery를 이용하여 비동기코드를 선언적인 함수형 프로그래밍으로 작성하기

• TanstackQuery의 사용법에 대한 이해
• TanstackQuery를 이용한 비동기 코드 작성에 대한 이해
• 비동기 코드를 선언적인 함수형 프로그래밍으로 작성하는 방법에 대한 이해

체크포인트

• 모든 API 호출이 TanStack Query의 useQuery와 useMutation으로 대체되었는가?
• 쿼리 키가 적절히 설정되었는가?
• fetch와 useState가 아닌 선언적인 함수형 프로그래밍이 적절히 적용되었는가?
• 캐싱과 리프레시 전략이 올바르게 구현되었는가?
• 낙관적인 업데이트가 적용되었는가?
• 에러 핸들링이 적절히 구현되었는가?
• 서버 상태와 클라이언트 상태가 명확히 분리되었는가?
• 코드가 간결하고 유지보수가 용이한 구조로 작성되었는가?
• TanStack Query의 Devtools가 정상적으로 작동하는가?

최종과제

• 폴더구조와 나의 멘탈모데일이 일치하나요?
• 다른 사람이 봐도 이해하기 쉬운 구조인가요?

과제 셀프회고

배포 링크

구조

src/
  ├── app/
  │   └── query/
  │       └── query-client.ts
  │
  ├── pages/
  │   ├── index.ts
  │   └── posts-manager/
  │       ├── index.ts
  │       ├── hooks/
  │       │   └── use-post-table-data-query.ts   ← 페이지 전용 데이터 조합
  │       ├── lib/
  │       │   └── mappers.ts                     ← URL → API 파라미터 변환
  │       ├── model/
  │       │   ├── index.ts
  │       │   ├── types.ts                       ← PostsUrlQueryParams (조합 타입)
  │       │   ├── posts-url-query-params.ts      ← URL 파싱/빌드
  │       │   ├── PostsUrlQueryContext.tsx       ← Provider, usePostsUrlQuery
  │       │   └── use-posts-url-query-model.ts
  │       └── ui/
  │           └── PostsManagerPage.tsx           ← features 조합, 의존성 주입
  │
  ├── widgets/
  │   ├── index.ts
  │   └── layout/
  │       ├── index.ts
  │       ├── Header.tsx
  │       └── Footer.tsx
  │
  ├── features/
  │   ├── index.ts
  │   ├── post/
  │   │   ├── index.ts
  │   │   ├── model/
  │   │   │   └── types.ts                       ← PostTableData, PostFormData
  │   │   └── ui/
  │   │       ├── PostTable.tsx                  ← props 기반 (onUserClick, renderComments)
  │   │       ├── PostCreateModal.tsx
  │   │       ├── PostEditModal.tsx
  │   │       └── PostDetailModal.tsx
  │   │
  │   ├── post-filter/
  │   │   ├── index.ts
  │   │   ├── model/
  │   │   │   ├── index.ts
  │   │   │   └── types.ts                       ← PostFilterParams
  │   │   └── ui/
  │   │       ├── PostsFilters.tsx               ← props 기반 (filter, onFilterChange)
  │   │       └── PostsSearchBar.tsx
  │   │
  │   ├── comment/
  │   │   ├── index.ts
  │   │   ├── model/
  │   │   │   └── types.ts
  │   │   └── ui/
  │   │       ├── CommentList.tsx
  │   │       ├── CommentCreateModal.tsx
  │   │       └── CommentEditModal.tsx
  │   │
  │   └── user/
  │       ├── index.ts
  │       └── ui/
  │           └── UserModal.tsx
  │
  ├── entities/
  │   ├── index.ts
  │   ├── post/
  │   │   ├── index.ts
  │   │   ├── api/
  │   │   │   ├── post-api.ts
  │   │   │   ├── posts-keys.ts
  │   │   │   └── dto.ts
  │   │   ├── hooks/
  │   │   │   ├── use-posts-query.ts
  │   │   │   ├── use-posts-with-search-query.ts
  │   │   │   ├── use-posts-with-tag-query.ts
  │   │   │   ├── use-tags-query.ts
  │   │   │   ├── use-post-add-mutate.ts
  │   │   │   ├── use-post-edit-mutate.ts
  │   │   │   └── use-post-delete-mutate.ts
  │   │   └── model/
  │   │       └── types.ts                       ← PostModel
  │   │
  │   ├── user/
  │   │   ├── index.ts
  │   │   ├── api/
  │   │   │   ├── user-api.ts
  │   │   │   ├── user-keys.ts
  │   │   │   └── dto.ts
  │   │   ├── hooks/
  │   │   │   ├── use-user-query.ts
  │   │   │   └── use-users-query.ts
  │   │   └── model/
  │   │       └── types.ts                       ← UserModel
  │   │
  │   └── comment/
  │       ├── index.ts
  │       ├── api/
  │       │   ├── comment-api.ts
  │       │   ├── comment-keys.ts
  │       │   └── dto.ts
  │       ├── hooks/
  │       │   ├── use-comments-query.ts
  │       │   ├── use-comment-add-mutate.ts
  │       │   ├── use-comment-edit-mutate.ts
  │       │   └── use-comment-delete-mutate.ts
  │       └── model/
  │           └── types.ts                       ← CommentModel
  │
  ├── shared/
  │   ├── api/
  │   │   └── types.ts                           ← BaseListApiResponse
  │   ├── config/
  │   │   ├── api-config.ts                      ← API_URL (환경별)
  │   │   └── query-config.ts                    ← STALE_TIME 상수
  │   ├── modal/
  │   │   ├── ModalComponent.tsx
  │   │   ├── ModalContext.tsx
  │   │   ├── ModalRoot.tsx
  │   │   └── types.ts
  │   ├── types/
  │   │   ├── index.ts
  │   │   └── pagination.ts                      ← PaginationParams (범용)
  │   ├── ui/
  │   │   ├── index.ts
  │   │   ├── primitives.tsx
  │   │   ├── Pagination.tsx
  │   │   └── SelectDropdown.tsx
  │   └── utils/
  │       └── highlight.tsx
  │
  ├── App.tsx
  ├── main.tsx
  ├── index.tsx
  └── vite-env.d.ts

의존성 흐름

요렇게 준수하려고 노력했습니다.

app → pages → widgets → features → entities → shared

이번 과제를 통해 이전에 비해 새롭게 알게 된 점이 있다면 적어주세요.

FSD에 대한 이해도가 조금 올라왔습니다.. 그동안은 FSD는 왜 생겼을까? 구조는 왜 이 모냥인가? 라는 생각을 해왔었는데, FSD 철학을 준수하며 쪼개고, 기계적으로 각 요소들의 역할을 준수하기 보다는 책임을 분리한다는 관점으로 폐관수련하다보니,, FSD가 뭔지? 왜 떠올랐는지? 조금이나마 체감할 수 있었습니다. 특히 이런 구조 속에서 의존의 방향을 준수하는 구조는 어떤 구조인지, 현재 의존의 방향을 잘 준수하고 있는지 고민하다보니 어려운 문제의 실마리가 풀리는 경험을 했습니다.

이제 다음 스텝은 이 느낌을, 얻은 인사이트를 저만의 언어로 만들어 볼 예정입니다. 그래서 팀에 공유도 하고, 실제로 업무와 작업에도 적극 활용해 볼 생각입니다.

본인이 과제를 하면서 가장 애쓰려고 노력했던 부분은 무엇인가요?

1. FSD 철학을 최대한 준수하되, 스스로 프로젝트 스코프에서 납득할 수 있는 구조.

2. FSD의 요소 중,, features / entities 위주로 최대한 이해하기..

• 선택과 집중했습니다... 덕분에 다른 요소인 processes는 어깨 넘어로 해보지도 못했습니다..

3. FSD 구조가 왜 좋은지 최대한 실무감각적으로 체화하기

아직은 막연하다거나 더 고민이 필요한 부분을 적어주세요.

url-query (src/shared/url-query)는 원래 페이지에서 URLSearchParams을 타입-안정성 / 추적-용이 / 사용성 등을 고려해 다루기 위해 개발한 부분입니다. 원래는 pages 내부에서 관리되었는데, 초반에 의존 설계를 잘못해 결국 shared 레벨로 이동시켰습니다... 크게 문제는 되지 않지만, 제가 생각하기엔 이것은 Pages 레벨의 관심사를 가지고 있는 코드라고 생각되어 다시 개선을 시도해볼 예정입니다...

이번에 배운 내용 중을 통해 앞으로 개발에 어떻게 적용해보고 싶은지 적어주세요.

'FSD 구조를 적극 활용해야겠다~', 'FSD로 리팩터링해야겠다~' 보다는, FSD의 철학을 멘탈 모델로 활용하는 정도로만 개발에 적용해볼 예정입니다..

이번 과제를 통해 FSD 철학에 공감되는 부분이 명확하게 있었고, 익숙해지기만 하면 구조에 의존의 방향이나 책임의 분리가 위임되는 경험을(= 노력에 비해 의존 관리 책임 분리가 쉬워지는 느낌) 했기에 기계적으로 FSD를 적용하는 것 보다는 자연스럽게 납득이 가는 선에서 노력해보려고 합니다.

챕터 셀프회고

클린코드와 아키테쳑 챕터 함께 하느라 고생 많으셨습니다!
지난 3주간의 여정을 돌이켜 볼 수 있도록 준비해보았습니다.
아래에 적힌 질문들은 추억(?)을 회상할 수 있도록 도와주려고 만든 질문이며, 꼭 질문에 대한 대답이 아니어도 좋으니 내가 느꼈던 인사이트들을 자유롭게 적어주세요.

클린코드: 읽기 좋고 유지보수하기 좋은 코드 만들기

• 더티코드를 접했을 때 어떤 기분이었나요? ^^; 클린코드의 중요성, 읽기 좋은 코드란 무엇인지, 유지보수하기 쉬운 코드란 무엇인지에 대한 생각을 공유해주세요

결합도 낮추기: 디자인 패턴, 순수함수, 컴포넌트 분리, 전역상태 관리

• 거대한 단일 컴포넌트를 봤을때의 느낌! 처음엔 막막했던 상태관리, 디자인 패턴이라는 말이 어렵게만 느껴졌던 시절, 순수함수로 분리하면서 "아하!"했던 순간, 컴포넌트가 독립적이 되어가는 과정에서의 깨달음을 들려주세요

응집도 높이기: 서버상태관리, 폴더 구조

• "이 코드는 대체 어디에 둬야 하지?"라고 고민했던 시간, FSD를 적용해보면서의 느낌, 나만의 구조를 만들어가는 과정, TanStack Query로 서버 상태를 분리하면서 느낀 해방감(?)등을 공유해주세요

리뷰 받고 싶은 내용이나 궁금한 것에 대한 질문

Q-1) FSD 질문

FSD는 익숙해질 수록 정말 강력한 구조인 것 같습니다. 핵심 요소인 page / feature / entities이 단방향 흐름(참조 방향)을 갖는 구조라는 것도 정말 마음에 듭니다. 다만, 이런 철학을 준수하는 것 아래 너무 많은 분리가 일어나는 것 같습니다. 지난주 함수형 사고/프로그래밍으로 리팩터링을 진행할 때도 비슷한 느낌을 받았는데, 때로는 분리되지 않은 투박한 코드가 더 읽기 좋고 관리하기 편할 때도 있다고 느낍니다. 코치님은 어떻게 생각하시나요? 이론적인 지점과 직관/실용적인 지점에서 의사결정을 하는 기준이 있으신가요?

Q-2) TanStack Query 관련 코드 리뷰 부탁드립니다!

저는 현 회사에서는 Vue 위주로 다루고 있습니다. 작년에 규모있고 복잡도 높은 제품에 TanStack Query를 도입하며, 밀도 있게 TanStack Query를 다뤄왔습니다. 그런데 Vue에서만 다루다가 이번 작업에서 크게 느낀 것은, React의 State-컴포넌트 생명주기 기반의 useQuery 활용 구조와 Vue 의 반응성 기반의 활용 구조는 관점이 많이 다르고 느껴집니다. Vue에서는 반응성 있는 변수의 변화를 감지하여 동작하기에, queryKey나 enabled에 의존성 관리를 하는 것을 넘어서, 조금 더 디테일 한 부분까지 제어가 가능했고(필요했고,,) React 생태계에서 많이 사용하고 TanStack 공식 문서에서도 권장하는 QueryKey Factory 패턴(현 작업에도 적용한..)이 Vue의 반응성 시스템에는 어울리지 않았다고 느낍니다. 사설이 길었네요.. 무튼, 그렇다보니 이번 프로젝트에서도 기존에 Vue에서 작성하던 방식으로 useQuery와 useMutation, 그리고 queryClient를 이용한 캐시 조작/무효화를 활용했습니다. 때문에 현재 작성/활용된 방식이 적절한지 리뷰받고 싶습니다!
(실제로 useQuery, useMutation 활용의 실무적 패턴, 특히 react 생태계에서의 패턴과 비교해서 제가 작성한 방식의 문제점이 뭔지 개선할점이 뭔지 등이 궁금합니다)