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
인터페이스로 응답 구조 통일, 제네릭을 통한 타입 명시로 컴파일 타임 오류 사전 방지