TypeScript로 견고한 서버 API 설계: DI 적용 및 타입 안전성 확보

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

카테고리

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

서브카테고리

웹 개발

대상자

프론트엔드 개발자, API 통합 담당자

핵심 요약

  • 타입 안전성 확보 : HttpResponse 인터페이스와 제네릭을 활용해 요청/응답 타입을 명확히 정의
  • 도메인 모델 재사용 : Pick, Omit 유틸리티 타입으로 User 등 공유 모델을 기반으로 타입 정의
  • 의존성 주입(DI) 적용 : UserServerImpl에서 Http 클라이언트 주입으로 테스트 용이성과 환경 분리 구현

섹션별 세부 요약

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

  • 타입 안전성 부재 : any 타입 사용으로 런타임 오류 발생 가능성
  • 타입 중복/불일치 : 동일 API에 대해 서로 다른 UserUserData 인터페이스 정의
  • 유지보수 비용 증가 : API 변경 시 모든 호출 지점 수정 필요

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

  • 제네릭 적용 : post(url: string, data?: D) 메서드로 요청/응답 타입 명시
  • 응답 표준화 : HttpResponse 인터페이스로 data, status, headers 일관성 확보
  • 에러 처리 강제 : response.ok 검증 실패 시 Error 던짐

3. API 타입 정의 및 도메인 모델 재사용

  • 타입 분리 : UserReq = Pick, UserRes = User로 요청/응답 타입 명확화
  • 네이밍 컨벤션 : UserReq, UserRes 등 명확한 접미사 사용

4. 도메인별 API 클라이언트 구현

  • 인터페이스 기반 설계 : UserServer 인터페이스로 createUser 등 메서드 명시
  • DI 적용 : UserServerImpl에서 Http 클라이언트 주입으로 테스트 용이성 확보
  • 응답 데이터 추출 : response.data만 반환해 HTTP 응답 구조 인식 필요 없음

5. 테스트 용이성 및 DI의 장점

  • MSW 모킹 활용 : HttpResponse.json(...)으로 타입 안전한 모의 응답 생성
  • 환경별 설정 분리 : envHttpClient 주입으로 개발/프로덕션 API 자동 분리
  • 테스트 격리 : mockHttp 주입으로 다른 테스트 영향 없이 독립적 테스트 가능

결론

  • 타입 안전성과 유지보수성 향상을 위해 HttpResponse 인터페이스와 제네릭을 활용한 HTTP 클래스 설계, Pick, Omit 유틸리티 타입으로 도메인 모델 재사용, DI 적용을 통해 테스트 용이성 및 환경 분리를 실현해야 한다.