과제 체크포인트

배포링크

https://ckdwns9121.github.io/front_6th_chapter2-3/

기본과제

목표 : 전역상태관리를 이용한 적절한 분리와 계층에 대한 이해를 통한 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가 정상적으로 작동하는가?

최종과제

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

과제 셀프회고

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

이전에 FSD의 개념을 들어는 봤는데 글로만 봤다보니 명확하게 이해하지 못했습니다. 이번 과제를 통해 실제 프로젝트에 적용해보면서 단순히 폴더를 잘 나눈다기 보단 어떤 관점을 가지고 기능 단위로 책임을 명확하게 분리하는 설계를 해본 좋은 경험이였습니다.

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

폴더 구조에 대한 고민

entities와 features의 개념이 처음엔 매우 헷갈렸습니다. 많은 블로그 글과 유튜브 영상을 찾아봤지만, 각자 하는 이야기가 조금씩 다르고 주관적이어서 결국 테오 말씀대로 정해진 정답은 없구나 하는 생각이 들었습니다.

그래서 이번엔 여러 자료를 참고하되 내 관점과 주관적인 판단을 기준으로 폴더를 설계해봤습니다.

• entities: 도메인 모델과 API 요청이 있는 폴더, 도메인 최소단위의 컴포넌트, 쿼리 키 관련된 모음
• features: 도메인 단위의 기능 폴더, 비즈니스 로직, 커스텀 훅 (model), 사용자 인터렉션이 일어나는 컴포넌트(ui)

한 가지 더 고민했던 부분은 features 폴더를 나누는 관점에 있어서 동사 중심일지 도메인 중심일지 고민했습니다. 만약 동사 중심으로 설계한다하면 엔티티 하나당 최소 4개의 CRUD 동작이 있기때문에 폴더가 너무 많아지는 문제가 발생할 수 있을 것 같았습니다.

예를들어 features/create-post, features/update-post, features/delete-post, features/read-post

이런식으로 엔티티 하나당 동사 4개가 추가되어 폴더가 커질 수 있는 문제가 생겼습니다.

반대로 명사(도메인) 중심으로 설계를 하면 그 폴더 내부에도 결국 똑같은 문제가 발생한다고 생각했습니다. 예를들어 features/post/ui 안에 create,update,delete,read를 담당하는 모든 컴포넌트가 모여있습니다.

결국 저는 이 두 관점을 합쳐보기로했고 관심사에 대한 관점을 도메인 + 기능 중심으로 봤습니다. (도메인 + 기능이 1 Depth)

예를들어 post/create-post, post/update-post처럼 도메인(post) 아래에 관련 기능들을 배치하는 식으로 설계했고, 이렇게 하니 관련 기능이 한 곳에 모여 관리가 편리하고 확장성이 좋을것 같다는 결론을 내렸습니다.

쿼리 키 관리

이번 과제에서 URL의 QueryParams로 업데이트되는 키들을 쿼리 키로 어떻게 관리할지가 큰 고민이었습니다.

처음에는 단순히 쿼리 키를 하드코딩하는 방식으로 접근했는데, 재사용성 문제와 누락 또는 오타로 인해 캐시가 제대로 업데이트되지 않는 문제가 발생했습니다. 게다가 쿼리 키가 페이지 번호, 검색어, 필터링, 정렬 등 URL SearchParams 기반으로 생성되고 여러 곳에서 사용되고 있어서, 하드코딩 방식으로는 관리가 쉽지 않았습니다.

import { useSearchParams } from "react-router-dom"
import { useMemo } from "react"
import { BaseQueryParams } from "../lib"

type BaseQueryParamsReturnType = BaseQueryParams

export function useBaseQueryParams(): BaseQueryParamsReturnType {
  const [searchParams] = useSearchParams()

  return useMemo(
    () => ({
      skip: Number(searchParams.get("skip")) || 0,
      limit: Number(searchParams.get("limit")) || 10,
      search: searchParams.get("search") || "",
      tag: searchParams.get("tag") || "",
      sortBy: (searchParams.get("sortBy") as "id" | "title" | "reactions" | "none") || "none",
      sortOrder: (searchParams.get("sortOrder") as "desc" | "asc") || "desc",
    }),
    [searchParams],
  )
}

그래서 위와 같이 QueryParams를 관리할 수 있는 중앙 훅을 만들었습니다.

또한 과제에서는 더미 데이터를 사용했기 때문에 실제 데이터가 반영되지 않았고, 이로 인해 낙관적 업데이트를 적용할 때 캐시 안의 데이터를 직접 갱신해야 했습니다. 이를 위해 qc.setQueryData를 사용하여 쿼리 캐시 안의 데이터를 바로 업데이트하는 방식을 시도했습니다.

그러나 동적으로 변하는 쿼리 키를 안정적으로 관리하기 위해 중앙에서 쿼리 키를 관리하고, 정규화(normalize) 하는 방법을 적용했습니다. 정규화 함수는 빈 값(undefined, null, "")을 제거하고, 키를 정렬하여 순서가 달라도 동일하게 인식되도록 하며, 모든 값을 원시 타입으로 단정하여 참조 불일치 문제를 방지합니다.

export function normalize<T extends Record<string, unknown>>(obj: T) {
  // 1) 비어있는 값 제거
  const entries = Object.entries(obj).filter(([, v]) => v !== undefined && v !== null && v !== "")
  // 2) 키 정렬로 일관성 확보
  entries.sort(([a], [b]) => (a > b ? 1 : -1))
  // 3) 원시 타입으로 단정
  const normalized = Object.fromEntries(entries) as Record<string, string | number | boolean>
  return normalized
}

이 방식을 통해 다양한 페이지 상태와 검색/필터 조건을 가진 쿼리 키를 안정적으로 관리할 수 있었고, 낙관적 업데이트 시 여러 곳에서 일관되게 캐시를 갱신할 수 있었습니다.

동작하지 않는 API를 클라이언트에서 구현하기

이번에 TanStack Query의 select 옵션을 활용하여 클라이언트 단에서 데이터를 가공하고 변환하는 기능을 구현해 보았습니다. 특히 좋아요 정렬이나 오름차순/내림차순 정렬과 같은 기능은 실제로 동작하지 않았는데 백엔드 API 요청 없이도 클라이언트에서 처리하면 되지 않을까? 싶어서 직접 구현해봤습니다.

구현 과정에서 알게 된 점은, select 함수가 서버에서 받아온 원본 데이터를 화면에 전달하기 전에 후처리할 수 있는 역할을 한다는 것이었습니다.

특히 정렬이나 검색, 태그 필터링처럼 사용자 상호작용이 빈번한 기능은 클라이언트에서 처리하는 편이 훨씬 자연스럽고 빠르게 한다고 생각합니다. 서버에 매번 요청을 보내지 않으니 사용자 경험(UX)도 개선되고, 성능적인 측면에서도 이점이 있었습니다.

export function usePosts() {
  const baseQueryParams = useBaseQueryParams()

  const { data, isLoading, error } = useQuery({
     ...
    select: (data) => {
      if (!data) return data

      const { search: searchQuery, tag: selectedTag, skip, limit, sortBy, sortOrder } = baseQueryParams

      const sortedPosts = [...data.posts]

      if (sortBy === "reactions") {
        sortedPosts.sort((a, b) => {
          const aLikes = a.reactions?.likes || 0
          const bLikes = b.reactions?.likes || 0

          if (sortOrder === "desc") {
            return bLikes - aLikes // 내림차순 (좋아요 많은 순)
          } else {
            return aLikes - bLikes // 오름차순 (좋아요 적은 순)
          }
        })
      }

      // 검색이나 태그 필터가 적용된 경우에만 페이지네이션 처리
      const shouldPaginate =
        (searchQuery || (selectedTag && selectedTag !== "all")) && sortedPosts.length > (limit || 0)

      if (shouldPaginate) {
        const startIndex = skip || 0
        const endIndex = startIndex + (limit || 0)
        const paginatedPosts = sortedPosts.slice(startIndex, endIndex)

        return {
          posts: paginatedPosts,
          total: data.total,
        }
      }

      return {
        posts: sortedPosts,
        total: data.total,
      }
    },
  })

  return { posts: data?.posts, total: data?.total, isLoading, error }
}

이 경험을 통해, "어떤 부분은 서버에 맡기고, 어떤 부분은 클라이언트에서 처리하는 것이 더 효율적인가?"라는 주제에 대해서도 얕게 고민할 수 있는 계기가 되었습니다.

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

제가 FSD를 체험해보면서 느낀점은 이 아키텍처가 정말 좋은 구조인지에 대해 계속 고민하게 됩니다.

장점이 분명하지만 진입 장벽이 상당히 높은거같아요. 처음 접하면 구조를 이해하고 적응하는 데 시간이 많이 걸릴것 같다 생각했습니다.

특히 특정 기능을 담당하는 파일을 index.ts로 배럴 익스포트하는 방식에서, 실제 파일을 찾거나 참조할 때 불편함이 많이 느껴졌습니다. 그리고 이 과정에서 단일 파일만 만들어서 예를 들어 CartItem.tsx를 작성하고, 또 index.ts를 만들어서 배럴 익스포트를 하는 방식이 최선인지에 대한 의문도 계속 남습니다. 이런 점들이 반복되면서 작업 과정에서 스트레스가 발생하기도 했습니다.

또한, FSD를 언제 적용해야 하는지도 큰 고민입니다. FSD는 프로젝트가 큰 규모에 적합하다는 이야기를 많이 봤습니다. 하지만 초기 프로젝트는 대부분 작을 수밖에 없습니다. 팀원들도 FSD 구조에 익숙하지 않은 상태에서 프로젝트를 시작해야 하고, 동시에 컨벤션을 맞추고 구조를 공부해야 하는 과정도 비용으로 작용합니다. 이런 이유로 초기에는 일반적인 React 폴더 구조로 설계하는 경우가 많을것 같다고 생각합니다.

그런데 프로젝트가 예상치 못하게 커졌을 때, 기존 구조에서 FSD로 전환하는 것이 의미가 있는지 의문이 듭니다. 기존에 작성한 코드와 구조를 점진적으로 FSD 구조로 리팩토링하려면 상당한 비용이 발생할 것 같다는 생각이 듭니다. 구조를 처음부터 다시 잡는거기 때문에 아파트의 뼈대만 남기고 리모델링 하는 느낌이 들었어요 또한 이 과정에서 발생할 수 있는 버그나 설계 충돌도 무시할 수 없을것 같았습니다.

결국 가장 큰 문제는 FSD를 언제 적용하는 것이 적절한가 하는 점입니다.

1. 초기부터 FSD를 도입하면 프로젝트 규모가 작을 때는 오버엔지니어링이 될 수 있음, 러닝커브, 팀원들 컨벤션 맞추고 하는것도 비용임. → 그냥 일단 빠르게 프로젝트를 시작하는게 더 좋을 수도 있음.
2. 반대로 프로젝트가 일정 수준 이상 커진 뒤에 도입하려 하면, 기존 구조에서의 전환 비용과 리스크가 크기 때문에 쉽지 않을것 같음.

따라서 FSD 도입 시점은 프로젝트 규모, 팀원의 경험 수준, 러닝 커브, 컨벤션 정립 등 여러 요소를 종합적으로 고려해야 한다는 결론을 내렸습니다. 이런 생각들 때문에 아직도 FSD를 ‘무조건 좋다’라고 판단하기 어렵고, 상황에 따라 유연하게 적용해야겠다라고 생각했습니다.

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

챕터 셀프회고

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

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

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

첫 클린코드 과제를 할때가 생각이 나네요.. 엊그제 같은데 벌써 2주전이라니 시간이 참 빠른것 같습니다.

더티코드를 처음 접했을땐 정말 막막하긴 했던거 같아요. 어디서부터 정리를 시작해야 할지 감도 잡히지 않고, 전체 구조가 뒤엉켜 있어서 손대는 게 부담스러웠습니다. 하지만 어지럽혀진것을 정리하는거에 있어서 쾌감을 느끼고 만족을 하는 성격인데 아마 이런 성향이 작용했던 것 같아서 재밌게 과제를 진행했습니다.

우선 클린한 코드를 짠다는건 계속 깨끗한 코드를 봐야한다는 말이고 그 말은 계속해서 그 프로젝트의 코드를 짜야한다는 말인거겠죠. 이건 단순히 코드를 예쁘게 짠다는게아니라 품질을 높여 지속적으로 관리하는 습관을 갖는다라고 생각합니다. 즉 프로젝트를 계속 개발하고 유지보수할 수 있는 환경을 만드는거겠죠.

읽기 좋은 코드란 동료들이 봤을때도 아무 스트레스가 없는 코드? 의문이 없는 코드? 라고 생각합니다. 이거 왜이렇게 짰어요? 이거 무슨 코드에요? 라는 노이즈가 나오지 않고 바로 구조와 흐름을 직관적으로 잘 이해할 수 있도록 설계된 코드라고 생각합니다. 결국 읽기 좋은 코드는 커뮤니케이션을 코드로 대신하는거라고 생각합니다.

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

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

큰 로봇을 작은 부품 단위로 쪼개는 느낌이었고, 나중에 하나씩 조립하는 과정이 재미있었습니다. 하지만 각 컴포넌트에서 이벤트 핸들러를 어떻게 일관성 있게 관리할지 고민이 많았는데, 테오 QnA 시간에 좋은 방향을 찾을 수 있었습니다.

핵심은 핸들러도 컴포넌트의 책임이라는 점이었습니다. 즉, 이벤트 처리 로직을 컴포넌트 내부에서 관리하면서, 필요한 경우만 외부로 전달하는 구조를 만들면 각 컴포넌트가 독립성을 유지하면서도 일관된 방식으로 동작할 수 있다는 깨달음을 얻었습니다.

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

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

처음에는 create, update, remove 같은 mutations를 하나의 훅(usePostMutation 같은)에서 통합해서 관리하려고 고민했어요. 이렇게 하면 코드가 한 곳에 모여서 관리하기는 편하지만, 동시에 관심사(Responsibilities)가 섞이게 되었습니다. 즉, “생성”과 “삭제”가 같은 훅 안에 섞이면, 나중에 각각의 동작을 독립적으로 관리하거나 재사용하기 어려워진다는 문제점이 발생할 수 있었어요

그래서 최종적으로 선택한 방식은 각 mutation을 개별 훅으로 분리하는 것 (useCreatePost, useUpdatePost, useDeletePost)입니다. 이렇게 하면 각 훅이 자기 역할만 담당하고, 관심사 분리가 명확해진다고 생각했습니다.

또한 위젯에 대해서

TanStack Query의 사용경험은 음.. 해방감이라기보단 약간의 답답함이 컸던거같아요. 더미데이터를 관리하다보니 실제 데이터가 반영이 안되고 캐시를 업데이트 하는 식으로 구현했어야 했습니다. 그러다보니 FSD에 고민하는 시간보다 이 더미데이터를 어떻게 잘 처리해서 실제 기능이 되는것 처럼 보이게하지? 라는 고민을 좀더 많이 했던거같아요ㅎㅎ 하지만 이런 기능을 구현하면서 몰랐던 TanStack Query의 기능에 대해서도 배울 수 있어서 좋았습니다.

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

---

Q1. 아까 회고에도 언급했던 FSD에 대한 적용 시점이 궁금합니다. 제가 고민했던 내용은 아래와 같아요

1. 초기부터 FSD를 도입하면 프로젝트 규모가 작을 때는 오버엔지니어링이 될 수 있음. 러닝커브, 팀원들 컨벤션 맞추고 하는것도 비용임. → 그래서 그냥 일단 빠르게 프로젝트를 시작하는게 더 좋을 수도 있다고 생각했습니다.
2. 반대로 프로젝트가 일정 수준 이상 커진 뒤에 도입하려 하면, 기존 구조에서의 전환 비용과 리스크가 크기 때문에 이 방향으로 리팩토링하기가 쉽지 않을것 같습니다.

코치님이 생각하시기엔 초기부터 FSD를 도입하는게 좋을지, 반대로 점진적으로 리팩토링하면서 FSD를 적용하면 좋을지 궁금합니다.