와인두잔 - 중급 프로젝트 회고

배포사이트: https://winedoojan-project.vercel.app/

1. 프로젝트 개요

이번 프로젝트에서는 저희 팀원끼리 상의해서 와인두잔이라는 프로젝트를 하기로 결정했습니다. 와인두잔은 사용자들이 다양한 와인에 대한 솔직한 리뷰를 읽고, 자신에게 맞는 와인을 쉽게 찾아 구매 결정을 내릴 수 있도록 돕는 플랫폼입니다. 또한 와인의 종류, 맛, 가격대, 별점 등 다양한 기준을 바탕으로 리뷰를 작성하고 공유하며, 필터링 기능을 통해 원하는 와인을 탐색할 수 있습니다.

사용 기술

• Frontend: Next.js, TailwindCSS, Zustand, Framer
• Backend: Amazon S3
• Authentication: OAuth 2.0, Kakao
• Development Environment & Tools: Github, Vercel

팀 구성: 김영호 (본인), 홍승원, 나예진, 최권진, 이지은

개발 기간: 2025-04-20 ~ 2025-05-10

2. 기술적 측면

• Next,js (App Router): 대표적으로 이번에 사용한 기술은 Next.js와 타입스크립트를 활용해 프로젝트를 진행했습니다. Next.js를 사용한 이유는 최신 앱라우터 기반 기술을 사용하는 동시에 SSR과 CSR 컴포넌트를 사용할 수 있기 때문에 선택했습니다.
• Typescript: 정적 타입 시스템을 통해 개발 과정에서 타입 관련 오류를 조기에 발견하고, 특히 와인 데이터 모델과 API 응답 타입을 명확하게 정의함으로써 코드 안정성을 크게 향상시켰습니다.
• Zustand: Redux보다 가벼우면서도 강력한 상태 관리 라이브러리로, 사용자 인증 상태와 와인 목록 데이터를 효율적으로 관리했습니다. 특히 보일러플레이트 코드가 적어 개발 생산성이 향상되었습니다.
• 인증 시스템: JWT 기반 자체 회원가입/로그인 구현하였으며 Kakao SDK를 Next.js 환경에 통합하여 소셜 로그인 구현을 했습니다.

3. 프로젝트 진행 과정

프로젝트의 일정은 노션으로 관리했으며, 진행 과정은 노션이랑 깃허브의 이슈와 PR를 동해 관리했습니다.

저희 팀은 프로젝트를 시작하기 전에 피그마 디자인을 확인하며 각 페이지별 공통 컴포넌트와 폴더 구성을 정해 놓고 시작했습니다. 간단한 컨벤션도 정하였고 브랜치 전력은 깃허브 플로우로 하게 되었습니다.

짧은 개발 기간이였던 만큼 저희는 빠르게 기초 작업부터 시작해야 됬기 때문에 스프린트 기간은 크게 1주일로 정하고 데일리 스크럼 미팅으로 프로젝트를 진행했습니다. 개발 우선 순위로는 각 페이지별로 역할을 분담한 후 여러 공통 컴포넌트와 API를 먼저 개발하기로 정하였습니다. 각자 맡은 역활과 기능을 잘 이해하고 넘어갔기 때문에 프로젝트는 계획 대비 진행은 아주 수월했으며 각 컴포넌트별 개발을 기간 내에 잘 완성할 수 있었습니다.

4. 성공 요소

이번 프로젝트에서 저는 핵심 기능인 로그인 시스템과 전역 상태 관리를 담당했으며, 다양한 기본 컴포넌트와 로그인 및 404 페이지 구현을 맡았습니다. 프로젝트 아키텍처의 근간이 되는 이 두 영역은 전체 애플리케이션의 성패를 좌우하는 중요한 부분이었기에, 기술적 성장을 이룰 수 있는 귀중한 경험이었습니다.

인증 시스템 구현

JWT 기반의 강력한 인증 시스템을 구축했습니다. 특히 보안과 사용자 경험을 모두 고려한 토큰 관리 전략을 수립했습니다:

• Access 토큰과 Refresh 토큰의 이중 토큰 구조 설계
• 모든 API 요청에 인증 토큰을 자동으로 포함시키는 인터셉터 구현
• Refresh 토큰을 활용한 Access 토큰 자동 갱신 커스텀 훅 개발
• 토큰 만료 시 자연스러운 사용자 경험을 위한 상태 처리 로직 구현

카카오 소셜 로그인 연동도 성공적으로 구현했습니다. OAuth 2.0 프로토콜을 활용하여 리다이렉트 URI 기반의 인증 플로우를 설계하고, 카카오 API로부터 받은 사용자 정보를 우리 서비스의 사용자 모델과 통합하는 과정을 완성했습니다.

폼 관리 및 유효성 검증 고도화

로그인 및 회원가입 폼 개발에서 최신 기술 조합을 활용했습니다:

• React Hook Form을 도입하여 폼 상태 관리를 단순화하고 리렌더링을 최소화
• Zod 스키마 기반의 타입 안전한 유효성 검증 시스템 구축
• TypeScript와의 완벽한 통합으로 컴파일 타임에 오류 감지
• 선언적인 유효성 검증 로직으로 코드 가독성과 유지보수성 향상

이러한 접근 방식은 사용자 입력 처리의 신뢰성을 높이는 동시에, 개발 경험과 코드 품질을 크게 개선했습니다.

Zustand를 활용한 효율적인 상태 관리

처음 도입한 Zustand는 기대 이상의 성과를 가져왔습니다:

• 보일러플레이트 코드를 최소화한 간결한 상태 관리 설계
• Persist 미들웨어를 활용한 브라우저 스토리지 연동으로 사용자 세션 유지
• 사용자 인증 상태, 토큰 관리, 로그인/로그아웃 로직의 중앙화
• 컴포넌트 간 상태 공유의 복잡성 제거

특히 Redux 대비 훨씬 직관적인 API와 TypeScript와의 우수한 통합성은 개발 생산성을 크게 향상시켰습니다.

Github PR의 활용

저희 팀은 이번 프로젝트에서 Github Pull Request를 협업의 핵심 도구로 적극 활용했습니다. 프로젝트 초기에 "서로의 코드를 확인하고 건설적인 피드백을 공유하는 문화"가 품질 향상의 핵심이라는 공감대를 형성하고, PR이 생성되면 모든 팀원이 다음 미팅 전까지 코드를 검토하여 구체적인 피드백을 제공하는 체계를 확립했습니다. 이를 통해 과도한 useState 사용을 줄이고 컴포넌트의 역할을 적절히 분리하는 등 코드 품질이 크게 향상되었으며, 각 팀원이 담당하는 기능과 구현 방식을 투명하게 공유함으로써 프로젝트의 전체 흐름을 파악하기 쉬워져 개발 효율성이 높아졌습니다. 이러한 PR 중심의 워크플로우는 단순히 코드 품질만 향상시킨 것이 아니라, 팀의 소통과 협업 문화 자체를 한 단계 성장시키는 계기가 되었습니다.

기술적 성장과 프로젝트 기여

이번 프로젝트를 통해 모던 웹 개발의 핵심 영역인 인증 시스템과 상태 관리에 대한 깊은 이해를 얻었습니다. JWT 기반의 인증 흐름을 완전히 구현해본 경험과 Zustand와 같은 최신 상태 관리 라이브러리의 실전 활용 능력은 프론트엔드 개발자로서의 역량을 한 단계 높이는 계기가 되었습니다.

무엇보다 이러한 핵심 기능들이 전체 프로젝트의 안정적인 토대를 형성하여 팀원들이 각자의 기능 개발에 집중할 수 있는 환경을 조성했다는 점에서 큰 보람을 느꼈습니다. 특히 개발 초기에 설계한 인증 및 상태 관리 구조가 프로젝트 후반부까지 큰 수정 없이 견고하게 작동한 것은 기술 선택과 설계의 적절성을 증명해주었습니다.

5. 어려웠던 점 및 개선할 점

API의 분리

이번 프로젝트에서 가장 어려웠던 점은 API 로직의 분리와 일관성 유지였습니다. 개발 기간이 짧고 인증 토큰이 필요한 요청이 많아 초기에는 각자 파일에 임시로 API 로직을 작성한 후 나중에 통합하려 했으나, 팀원마다 다른 방식으로 구현하기 시작했습니다. BASE URL의 분리가 제대로 이루어지지 않았고, API 요청 함수가 다양한 이름과 형태로 작성되어 통합 과정이 복잡해졌습니다. 특히 제가 개발한 handleResponseWithAuth 같은 토큰 처리 및 갱신 함수가 공통으로 사용되지 않아 중복 코드가 발생했고, 결과적으로 일관된 API 컨벤션을 초기에 명확하게 설정하지 않은 것이 프로젝트 후반부에 많은 어려움을 야기했습니다. 이러한 경험을 통해 프로젝트 초기 단계에서 API 아키텍처와 컨벤션을 명확히 수립하고, 공통 유틸리티 함수를 먼저 개발하여 공유하는 것의 중요성을 깊이 깨달았습니다.

Next.js 앱라우터 기능과 Zustand 상태관리

프로젝트에서 Next.js의 앱라우터 기능을 충분히 활용하지 못한 점이 아쉬움으로 남았습니다. SSR 컴포넌트를 활용한 페이지가 매우 적었고, Next.js에서 제공하는 다양한 기능들을 제대로 활용하지 못했습니다. 주된 이유는 Zustand의 persist 기능을 사용하여 상태를 로컬스토리지에 저장했기 때문에, 사용자 인증이 필요한 페이지에서 SSR 컴포넌트를 효과적으로 사용할 수 없었습니다. 이는 제가 Zustand를 처음 사용하면서 사용자 상태를 쿠키 대신 로컬스토리지에 저장하도록 구현한 전략적 실수였습니다. 서버 사이드에서 접근 가능한 쿠키 기반 상태 관리를 채택했다면 Next.js의 SSR 기능과 앱라우터의 이점을 더 효과적으로 활용할 수 있었을 것입니다. 이번 경험을 통해 프레임워크의 특성과 상태 관리 전략을 더 깊이 이해하게 되었고, 다음 프로젝트에서는 쿠키 기반 인증을 통해 Next.js의 강력한 기능들을 더 효과적으로 활용할 계획입니다.

HOC 패턴의 활용

프로젝트에서 아쉬웠던 또 다른 점은 HOC(Higher Order Component) 패턴을 제대로 활용하지 못한 것입니다. 사용자 상태에 따른 페이지 접근 제어와 기능 제한이 필요했음에도, 각 페이지마다 동일한 인증 로직을 반복적으로 구현하여 코드 중복이 발생하고 컴포넌트의 역할 분리가 제대로 이루어지지 않았습니다. 인증 검사와 리다이렉트 로직을 추상화한 HOC 패턴을 적용했다면 코드의 재사용성을 높이고 관심사 분리를 더 효과적으로 달성할 수 있었을 것입니다. 안타깝게도 이러한 문제점을 개발 막바지에 발견하여 실제 수정에는 이르지 못했지만, 이번 경험을 통해 HOC 패턴과 같은 고급 컴포넌트 패턴의 중요성을 깊이 깨닫게 되었습니다. 다음 프로젝트에서는 초기 설계 단계부터 이러한 패턴을 적극적으로 도입하여 더 체계적이고 유지보수하기 좋은 코드베이스를 구축하겠습니다.