타입 안전한 HTTP 클라이언트 설계: 타입 주도 개발(TDD) 관점에서 API 통신 효율화

핵심 기술

본 콘텐츠는 타입스크립트의 제네릭과 인터페이스를 활용하여 기존 HTTP 클라이언트의 타입 안전성 부재, 타입 중복, 유지보수 비용 증가 등의 문제점을 해결하는 방법을 제시합니다. 특히, 타입 주도 개발(TDD) 관점에서 API 통신 계층을 설계하는 실질적인 방안을 다룹니다.

기술적 세부사항

• 기존 HTTP 클라이언트의 문제점: 타입 안전성 부재로 인한 런타임 오류, 타입 단언 남용, 타입 중복 정의, 유지보수 비용 증가, 테스트 어려움 등을 지적합니다.
• Type-Safe HTTP 클래스 설계 원칙:
  • 제네릭 활용: HTTP 메서드(GET, POST 등)에 제네릭 타입을 적용하여 요청 본문(D)과 응답 데이터(T)의 타입을 명확히 정의합니다.
  • 응답 형식 표준화: HttpResponse<T> 인터페이스를 정의하여 모든 API 응답이 일관된 구조(data, status, headers)를 가지도록 합니다. HttpStatusCode 열거형으로 상태 코드의 타입 안전성을 확보합니다.
• 실제 구현 사례 분석:
  • HTTP 클래스 구현: Http 클래스는 baseURL, defaultHeaders를 가지며, request 메서드를 통해 HTTP 요청을 처리합니다. get, post, put, delete 메서드는 제네릭을 활용하여 재사용성을 높입니다.
  • HTTP 클라이언트 인스턴스 생성: 애플리케이션 전반에 걸쳐 일관된 HTTP 통신을 위해 단일 httpClient 인스턴스를 생성합니다.
  • API 타입 정의: 도메인 모델(User)을 기반으로 Omit, Pick과 같은 타입 유틸리티를 사용하여 요청(CreateUserReq, GetUsersReq) 및 응답(UserRes, GetUsersRes) 타입을 명확하게 정의합니다.
  • API 함수 구현: 각 API 엔드포인트별로 타입 안전한 함수를 정의하고, httpClient를 호출하여 응답 데이터(response.data)만 반환하도록 합니다.
• 테스트 용이성: Mock Service Worker (MSW)를 활용하여 실제 서버 없이 API 호출을 모킹하고, 타입 안전한 테스트 코드를 작성하여 코드의 안정성을 검증합니다.

개발 임팩트

• 런타임 오류 감소: 컴파일 타임에 대부분의 타입 관련 오류를 사전에 방지합니다.
• 유지보수성 향상: API 스키마 변경 시 관련된 타입 정의만 수정하면 되어 유지보수 비용이 절감됩니다.
• 개발 생산성 증대: 타입 추론, 자동 완성, 명확한 타입 정의를 통해 개발자가 코드를 더 빠르고 정확하게 작성할 수 있습니다.
• 팀 협업 강화: API 명세와 실제 구현 간의 일관성을 유지하여 팀원 간의 혼란을 줄이고 협업 효율을 높입니다.
• 테스트 코드 작성 용이성: 타입 안전성이 확보된 코드는 테스트 작성 및 검증을 용이하게 합니다.