TypeScript로 서버 API 타입 설계하기: 견고한 Type 설계 가이드

Typescript로 설계하는 프로젝트: 견고한 서버 API Type 설계하기

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

웹 개발

대상자

프론트엔드 개발자(타입스크립트 사용자), API 통합 담당자

핵심 요약

  • 타입 안전성 확보 : HttpResponse 인터페이스와 제네릭 활용으로 요청/응답 타입 명시
  • 표준화된 응답 형식 : 모든 API 응답이 data, status, headers 구조로 통일
  • 유연한 타입 정의 : Omit, Pick 유틸리티 타입을 통해 도메인 모델 재사용

섹션별 세부 요약

1. 기존 HTTP 클라이언트의 문제점

  • 타입 단언 남용 : as User[]로 인한 런타임 오류 위험 증가
  • 타입 중복 및 불일치 : 동일 API에 대해 서로 다른 타입 정의로 혼란 발생
  • 유지보수성 저하 : API 변경 시 모든 호출 지점 수동 수정 필요

2. Type-Safe HTTP 클래스 설계 원칙

  • 제네릭 적용 : post(url: string, data?: D): Promise>로 요청/응답 타입 명시
  • 에러 처리 강제 : response.ok 검증 실패 시 Error 던짐
  • 인터페이스 통일 : HttpResponse로 응답 구조 표준화

3. HTTP 클라이언트 인스턴스 생성

  • 기본 URL 및 헤더 관리 : baseURL, defaultHeaders 속성으로 공통 설정 관리
  • 메서드 체인 : get, post, put, delete 메서드가 모두 request로 통일

4. API 타입 정의

  • 도메인 모델 재사용 : User 모델 기반으로 CreateUserReq, UserRes 등 정의
  • 명확한 네이밍 : UserReq (요청 타입), UserRes (응답 타입)으로 구분

5. 테스트 용이성

  • MSW 모킹 : http.post로 타입 안전한 모의 응답 생성
  • 타입 일관성 : 테스트 코드와 실제 코드에서 동일한 타입 사용

결론

  • 실무 적용 팁 : Omit 유틸리티 타입 활용, MSW로 타입 안전한 테스트 환경 구축
  • 핵심 전략 : HttpResponse 인터페이스로 응답 구조 통일, 제네릭을 통한 타입 명시로 컴파일 타임 오류 사전 방지