중급 프로젝트: Linkbrary

📢 프로젝트 소개

• 프로젝트 인원 : 프론트엔드 4명
• 기간 : 24.12.13 - 25.01.02
• 프로젝트 : 원하는 링크를 저장, 검색, 공유 및 폴더로 관리할 수 있는 서비스
• GitHub: https://github.com/codeit-fe11-part3-team4/linkbrary
• 협업 : GitHub, Notion, Discord
• 기술 스택 : React, Next.js(App Route), Typescript, Tailwind CSS

 

👩🏻‍💻 내 역할

• 파일 구조 및 tailwind 설정
• 헤더, 페이지네이션 공통 컴포넌트 구현
• 링크 카드 컴포넌트 구현 (링크 페이지, 즐겨찾기 페이지 공통)
• 즐겨찾기 페이지 구현
• 발표

 

💻 프로젝트 과정

🔗 API 연동 – Swagger 기반 백엔드 API 사용

이번 프로젝트에서는 코드잇 측에서 제공한 Swagger 문서를 기반으로 한 API를 사용했습니다. Swagger 문서는 명세가 잘 정리되어 있었기 때문에, 빠르게 데이터 구조를 파악하고 프론트엔드에서 필요한 요청을 구현할 수 있었습니다.

🧩 컴포넌트 구조와 역할 분담

프로젝트는 다음과 같은 페이지 단위로 구성되어 있었으며, 각각을 컴포넌트 중심으로 분할하여 개발했습니다.

• 메인 랜딩 페이지
• 로그인/회원가입 페이지
• 링크 페이지
• 즐겨찾기 페이지

컴포넌트는 재사용성과 유지보수성을 고려하여 기능 단위로 나누었으며, 각 기능별 디렉토리 구조를 통해 파일 관리를 체계화했습니다.

---

🎓 문제 및 해결 과정

문제 (1) - 링크 카드 컴포넌트 공통화 및 조건부 UI 렌더링

1. 문제

링크 페이지와 즐겨찾기 페이지 모두 링크 카드를 사용하는데, 각각의 페이지에서 별도 로직과 UI 구조로 중복 구현이 발생하고 있었습니다. 특히 케밥 버튼이나 즐겨찾기 버튼과 같은 기능은 페이지별로 노출 조건이 달랐지만 명확하게 분리되지 않았습니다.

 

2. 해결방식

Card 컴포넌트를 공통화하고, 내부에서 usePathname()을 통해 현재 페이지 경로(/links, /favorite)를 판별하여 boolean 값을 생성했습니다. 이를 기반으로 케밥 버튼, 즐겨찾기 버튼을 조건부로 렌더링했습니다. 또한 즐겨찾기 페이지에서는 해당 버튼들이 숨겨지고, 링크 페이지에서는 클릭 시 API를 호출해 즐겨찾기 상태를 토글하도록 구현했습니다.

 

3. 결과

동일한 UI 컴포넌트를 기반으로 페이지별 동작을 자연스럽게 분리할 수 있었고, props 없이도 페이지 구분이 가능해지며 컴포넌트 재사용성과 유지보수성이 향상되었습니다.

 

→ 개선 방향 : pathname 의존이 강해지면서 라우팅 변경 시 UI 로직 변경이 필요한 구조가 되었기 때문에, 추후에는 상태 기반 혹은 context 기반으로 구분하는 구조도 고려할 수 있음

 

문제 (2) - CardList 컴포넌트 도입 실패와 Card 내부 통합

1. 문제

초기 설계에서는 CardList 컴포넌트에서 전체 링크 데이터를 요청하고 상태를 관리한 뒤, 각각의 Card 컴포넌트로 props를 내려보내는 방식으로 구성하려 했습니다. 이 방식은 컴포넌트 간의 역할을 분리할 수 있는 구조였지만, 실제 구현 과정에서는 다음과 같은 문제가 발생했습니다:

• props 깊이와 양이 많아져 컴포넌트 간의 연결이 점점 복잡해졌고, 중간에서 데이터를 가공하는 과정도 많아졌습니다.
• 페이지 전환, 즐겨찾기 상태, 검색 필터링, 폴더 아이디, 페이지 사이즈 등 다양한 상태의 흐름이 연동되면서, 상태 전달 구조가 꼬이기 시작했고, 그에 따라 특정 동작이 한 쪽 컴포넌트에서만 반영되거나 비동기 흐름이 어긋나는 경우도 있었습니다.

 

2. 해결방식

결국 CardList는 제거하고, 다음과 같은 이유로 Card 컴포넌트 내부에서 상태 요청과 관리, 렌더링을 통합적으로 처리하는 구조로 구현했습니다

• useEffect로 pathname, folderId, searchQuery, currentPage, pageSize가 변경될 때마다 API를 호출해 데이터 요청을 직접 처리
• putFavoriteLink API 요청 후 전체 링크 상태를 갱신하는 흐름도 컴포넌트 내부에서 통합 관리
• searchQuery에 따라 filteredLinks 상태를 만들어 검색 필터링도 Card 내부에서 처리

 

3. 결과

 

• props 전달이 복잡하게 얽혀있던 구조가 단순화되어 코드의 추적 가능성과 디버깅 편의성이 높아졌습니다.
• 내부 상태 기반 렌더링 흐름이 명확해졌고, 버튼 조건부 렌더링, 즐겨찾기 동작 등도 페이지 기준으로 잘 동작했습니다.
• 하지만 컴포넌트가 점점 커지면서 렌더링, 요청 처리, UI 제어 로직이 하나에 몰리게 되어 관심사의 분리가 부족한 구조가 되었습니다.

 

 

→ 개선 방향

현 구조는 빠른 구현에는 유리했지만, 장기적으로는 유지보수성과 확장성에 있어 구조적인 한계가 있었습니다.
현재는 Card 컴포넌트 내부에서 링크와 즐겨찾기 관련 API 요청, 상태 관리, 렌더링까지 모두 처리하고 있어 컴포넌트가 점점 무거워지고 있으며, 관심사의 분리 측면에서도 아쉬움이 있었습니다.

원래는 CardList에서 API 요청과 상태를 전역적으로 관리하고 Card에는 렌더링만 위임하려 했지만, props 전달 구조가 복잡해지고 비동기 흐름이 꼬이면서 실패했습니다. 그러나 이는 props 전달이 반드시 문제라는 것보다는, 역할과 흐름이 명확히 정의되지 않은 설계의 문제였습니다.

이에 따라 각 페이지에서 필요한 API 호출과 상태 관리를 담당하고, Card 컴포넌트는 UI 렌더링만 맡도록 관심사를 분리하는 방향이 적합할 수 있겠다는 생각을 하게 되었습니다. 페이지는 어떤 데이터를 가져올지 결정하고, Card는 그 데이터를 어떻게 보여줄지에만 집중하게 됨으로써 구조적 명확성과 테스트 용이성이 향상됩니다. 또한 페이지 단에서는 React Query, Suspense, 에러 핸들링 등 다양한 전략을 자유롭게 적용할 수 있고, 즐겨찾기 페이지와 링크 페이지처럼 데이터 소스가 명확히 다른 경우에는 페이지 단에서 API를 분기하는 것이 더 명료한 흐름을 만들어냅니다.

props가 많아지는 상황은 필연적일 수 있으나, 이는 반드시 안티패턴이 아니며 명확한 설계를 기반으로 하면 오히려 데이터 흐름을 더 쉽게 추적하고 통제할 수 있고, 불필요한 전역 상태 관리 도구의 도입을 방지할 수 있습니다. 반대로, 컴포넌트 간 데이터 공유가 실제로 필요한 경우에는 Context, Zustand와 같은 상태 관리 도구를 유연하게 도입하여 역할 분리를 유지하면서도 필요한 공유는 효율적으로 처리할 수 있습니다.

향후 리팩토링 시에는 컴포넌트의 책임 단위를 재정의하고, CardList → Card 구조를 재도입하되 상태 흐름을 페이지 또는 래퍼 컴포넌트에서 컨트롤하는 방향으로 개선해보려 합니다.

 

• 페이지: 어떤 데이터를 가져올지 결정 (API 호출, 필터링, 페이지네이션 등)
• CardList: 반복 렌더링, key 및 layout 구성 등 목록 UI 책임
• Card: 데이터 시각화와 유저 인터랙션 담당 (UI 중심)

 

 

문제 (3) - 반응형 페이지네이션을 위한 useViewport 훅 구현

1. 문제

초기에는 pageSize 값을 고정(하드코딩)하거나, 부모 컴포넌트에서 조건문으로 화면 크기를 판별해 props로 전달하는 방식으로 구현했습니다. 그러나 이 구조에서는 다음과 같은 문제가 발생했습니다:

• window.innerWidth를 기반으로 한 조건 분기가 여러 곳에 흩어져 있어 로직 중복이 발생했고,
• 페이지 크기 변경 시 pageSize가 실시간으로 반영되지 않아,
  화면 너비가 변경되어도 보여주는 카드 수가 동적으로 바뀌지 않았습니다.

또한 prop 전달 과정에서도 viewportWidth와 pageSize 간의 동기화가 꼬여 페이지네이션이 비정상적으로 작동하거나 초기화되지 않는 오류가 발생했습니다.

 

2. 해결방식

useViewport라는 커스텀 훅을 도입해 화면 크기와 페이지 크기를 통합적으로 관리했습니다. 내부에서 resize 이벤트를 감지하여 width, pageSize, 디바이스 구분 상태(isPC, isTablet, isMobile)를 함께 관리했으며, 컴포넌트에서는 이 훅만 호출하면, 현재 화면에 맞는 pageSize를 바로 사용할 수 있도록 구성했습니다.

 

3. 결과

기존에 발생하던 prop 전달 오류와 하드코딩 문제를 해결할 수 있었고, 브라우저 크기에 따라 페이지 카드 수가 자동으로 변경되면서 UX가 향상되었습니다.

 

→ 개선 방향 : 초기 상태가 window 객체에 의존하기 때문에, 서버 사이드 렌더링 환경(window는 에러 발생)에서 예외 처리를 위한 조건 분기를 보완할 필요가 있으며(useEffect 내부에서만 window 관련 작업하도록 구조화), 추후에는 상태 관리를 더 명확히 하기 위해 Context 기반 또는 상태 동기화를 위한 로직 최적화도 고려

---

🎓 배운 점/느낀 점

1. App Router 기반의 페이지 구조 설계 및 구현 경험

이번 프로젝트에서는 Next.js의 App Router 방식을 사용하여 파일 구조를 설계하고 직접 구현했습니다. 기존 Pages Router와는 다르게, App Router는 폴더 기반의 구조와 레이아웃, 클라이언트/서버 컴포넌트의 분리, 서버 액션 등 다양한 개념이 도입되어 있어 처음에는 낯설었지만, 프로젝트를 진행하면서 실제 적용 방식을 익히고 디렉토리 구조를 효율적으로 설계하는 법을 배울 수 있었습니다. 이 경험을 통해 Next.js의 최신 라우팅 방식을 더 깊이 이해하게 되었고, 구조적인 개발에 대한 감각도 높일 수 있었습니다.

 

2. Context를 활용한 전역 상태 관리 방식에 대한 실전 경험

로그인 상태 관리를 위해 Context API를 기반으로 한 AuthContext를 팀원이 구현하였고, 저는 해당 구조를 활용해 useAuth() 훅을 통해 사용자 정보를 사용하는 흐름을 이해하고 적용했습니다. 단순히 사용하는 것에서 그치지 않고 Context 내부의 흐름을 분석하면서 상태를 전역에서 어떻게 관리하는지를 파악할 수 있었고, 이를 통해 전역 상태 관리의 필요성과 장점을 체감할 수 있었습니다.

 

3. API 흐름과 백엔드 로직 파악의 중요성

카드 컴포넌트를 공통화하고 즐겨찾기 페이지에 적용하는 과정에서, 즐겨찾기 API 호출 흐름을 정확히 이해하지 못한 상태로 작업을 시작해 시간이 지체되는 문제가 있었습니다. 즐겨찾기된 링크를 불러오기 위해서는 먼저 즐겨찾기 폴더에 링크를 추가해야 한다는 전제 조건을 파악하지 못했기 때문에, 아무리 데이터를 호출해도 결과가 나타나지 않았습니다. 이후 팀원의 도움을 받아 API 사용 흐름을 다시 정리하고 나서야 문제를 해결할 수 있었습니다.
이 과정을 통해 단순히 화면 UI 구현뿐만 아니라, 기능 작동을 위해 필요한 백엔드 로직까지 정확히 이해한 뒤 작업에 들어가는 습관이 얼마나 중요한지를 깨달았습니다.

---

😢 아쉬운 점

1. API 명세 확인 및 흐름 파악의 부족

즐겨찾기 페이지를 구현하면서, 즐겨찾기 링크를 불러오기 전에 별도의 API를 통해 해당 링크를 즐겨찾기 폴더에 등록해야 한다는 과정을 놓치고 작업을 시작했습니다. 이로 인해 아무 데이터도 받아오지 못하는 상태가 지속되었고, 문제 원인을 찾는 데 많은 시간이 소요되었습니다. 이후 팀원과의 소통을 통해 API 구조와 흐름을 재정비하면서 해결했지만, 개발 초기 단계에서 백엔드 로직까지 충분히 이해하고 흐름을 먼저 설계했더라면 더 수월하게 구현할 수 있었을 것이라는 아쉬움이 남았습니다.

 

2. Context 구조에 대한 사용 위주 접근

로그인 상태 관리를 위해 Context API를 사용하는 구조가 도입되었고, 저는 이를 활용하여 필요한 데이터에 접근할 수 있었지만, 직접 Context를 설계하고 구성하는 과정에는 참여하지 못했습니다. 해당 구조의 장점은 분명히 체감했지만, 단순히 제공된 구조를 사용하는 수준에 머무른 점이 아쉬웠습니다. 다음 프로젝트에서는 직접 Context나 전역 상태 관리 도구를 구현해보며, 상태 흐름을 설계하는 경험도 쌓고자 합니다.

 

3. 카드 컴포넌트와 리스트 컴포넌트 분리 실패

처음에는 링크 목록을 CardList와 Card 형태로 분리된 구조로 구현하고자 했지만, API 호출 흐름과 상태 관리가 엇갈리면서 예상보다 복잡한 구조가 되었고, 결국 Card 컴포넌트 하나에서 모든 로직을 처리하게 되었습니다. 이로 인해 컴포넌트가 무거워지고 관심사 분리 측면에서도 아쉬움이 남았습니다. 컴포넌트 간 데이터 흐름을 명확히 정의하지 않고 로직을 추가한 점이 원인이었으며, 이후에는 설계 단계에서 상태 관리 흐름과 컴포넌트 역할을 더 명확히 구분한 뒤 구현하는 방향으로 개선할 필요가 있다고 느꼈습니다.