정산 시스템 개선 (2024.07 ~ 2024.10)

React tanstack-table tanstack-query ts-pattern Vite Vitest Storybook Vercel

배경

정산 시스템의 신뢰성 문제를 해결하고 사용자 경험을 개선하기 위한 프로젝트를 진행했습니다. 특히 테이블 컴포넌트의 구조적 문제와 상태 관리의 비효율성이 주요 개선 대상이었습니다.

주요 도전 과제

모듈화된 테이블 컴포넌트 개발

기존 시스템에서는 React Table v6, v7과 Antd Table이 혼재되어 사용되고 있어 일관성이 떨어지고 유지보수가 어려웠습니다. 이를 Tanstack Table를 사용한 새로운 컴퍼넌트로 표준화하는 과정에서 새로운 문제에 직면했습니다.

문제점:

• 다양한 사용 케이스를 하나의 컴포넌트로 처리하다 보니 props가 무분별하게 증가
• 컴포넌트의 복잡도 증가로 유지보수성 저하
• 새로운 요구사항 추가 시 기존 코드 수정이 불가피하고 기존 코드의 검수도 동반되어야 함

<NewTable
  columns={columns}
  data={data}
  onRowClick={handleRowClick}
  onSortChange={handleSortChange}
  onFilterChange={handleFilterChange}
  virtualized={virtualized}
  pagination={pagination}
  sorting={sorting}
  filtering={filtering}
  controlled={controlled}
  // 일부 컴퍼넌트에서 사용되는 프롭스들이 추가되면 더 복잡해짐
  // 옵셔널한 props로 인해 컴퍼넌트 내부에서는 분기처리가 많아지며 코드 가독성이 떨어지고
  // 새로운 요구사항에 대응하기 어려워짐
/>

해결 방안:

• 핵심 테이블 기능을 core로 분리하고, 이를 기반으로 특화된 테이블 컴포넌트들을 구현하는 구조로 재설계
• Tanstack의 라이브러리 구조를 참고하여 제어/비제어/가상화 등 각각의 사용 케이스에 최적화된 테이블 컴포넌트 개발
• 확장에 열려있고 수정에는 닫혀있는 구조로 설계하여 새로운 요구사항에 유연하게 대응

<VirtualizedTable
  columns={columns}
  data={data}
  pagination={pagination}
  sorting={sorting}
  filtering={filtering}
/>
 
<UncontrolledTableTable
  columns={columns}
  data={data}
  pagination={pagination}
  sorting={sorting}
  filtering={filtering}
/>

컴포넌트 신뢰성 확보

표준화하는 컴퍼넌트의 신뢰성 향상을 위해서 다음과 같은 작업을 함께 진행했습니다.

• Storybook을 통한 컴포넌트 문서화
• Storybook을 기반으로 한 비개발자도 이해할 수 있는 명확한 사용 가이드 제공

온보딩 중인 개발자 A님 스토리 북을 통해 테이블 컴퍼넌트를 파악 후 기능 추가를 진행해 주세요!

기획자 B님 여기에 있는 테이블을 사용해서 스토리보드를 작성해 주시면 어떨까요?

상태 관리 표준화

Tanstack Query 사용 시 쿼리키 관리 기준이 없어 발생하는 문제들을 해결해야 했습니다.

문제점:

• 쿼리키 생성 패턴이 명확하지 않아 중복 발생
• 쿼리 간의 관계를 명확히 하지 못해 상태 관리 효율성 저하
• 쿼리키 파일의 위치가 작업자마다 제각각이라 커뮤니케이션 비용 증가

해결 방안:

• query-key-factory 도입으로 쿼리키 생성 패턴 표준화
• 정해진 규칙에 따라 자동으로 쿼리키가 생성되어 고민 시간 최소화
• 쿼리 간의 관계를 명확히 하여 상태 관리 효율성 향상
• 쿼리키 충돌이나 중복 없이 즉각적인 캐시 무효화 가능

타입 안정성 강화

복잡한 정산 관련 타입을 안전하고 가독성 있게 다루는 것이 중요했습니다.

문제점:

• 타입 가드의 중첩으로 인한 가독성 저하
• 타입가드 생성에 대한 피로감으로 인해 타입 단언들이 무분별하게 추가됨

해결 방안:

• ts-pattern을 활용한 패턴 매칭 도입으로 기존 타입 가드의 문제를 해결
• 패턴 매칭을 통해 타입 가드 생성 시간 단축
• 타입 단언 감소로 코드의 신뢰성 향상

결과

개발 생산성 향상

• 재사용 가능한 테이블 컴포넌트로 개발 시간 단축
• 새로운 기능을 제공하는 테이블을 추가해야 할때 기존 core를 바탕으로 새로운 API를 추가하여 빠른 개발
• 테스트와 문서화를 통한 커뮤니케이션 비용 감소
• 표준화된 쿼리 키로 상태 관리 효율성 증가

사용자 경험 개선

• 필터와 정렬 상태가 URL 파라미터로 유지되어 검색 경험 향상
• 테이블 성능 향상으로 렌더링 속도 개선
• 일관된 UI/UX로 사용자 학습 곡선 감소

코드 품질 향상

• 타입 안정성 강화로 런타임 에러 감소
• 패턴 매칭을 통한 코드 가독성 향상
• 테스트 커버리지 증가로 버그 발생 가능성 감소

이러한 개선을 통해 정산 시스템의 신뢰성과 사용성이 크게 향상되었으며, 개발팀의 생산성도 함께 개선되었습니다.