Builder.shin

TypeScript 4.4 template literal type으로 타입 안전성 높이기

문제 상황

프로젝트에서 RESTful API 엔드포인트를 string으로 관리하다 보니 오타로 인한 404 에러가 종종 발생했다. /api/users/:id 같은 동적 경로는 더 문제였다.

// 기존 방식
const endpoint = `/api/users/${userId}`; // 오타 가능성
fetch(endpoint);

Template Literal Types 활용

TypeScript 4.1부터 지원된 template literal type을 4.4에서 더 강화된 방식으로 활용했다.

type ApiVersion = 'v1' | 'v2';
type Resource = 'users' | 'posts' | 'comments';
type ApiPath = `/api/${ApiVersion}/${Resource}`;

// 자동완성 지원되고 타입 체크됨
const path: ApiPath = '/api/v1/users'; // OK
const invalid: ApiPath = '/api/v3/users'; // Error

동적 ID가 필요한 경우도 처리 가능하다.

type IdPath<T extends string> = `${T}/${number}`;
type UserIdPath = IdPath<'/api/v1/users'>;

// 타입 가드와 함께 사용
function fetchUser(path: UserIdPath) {
  return fetch(path);
}

실용적인 API 클라이언트

실제 프로젝트에 적용한 래퍼 함수다.

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
type Endpoint = `/api/${string}`;

class ApiClient {
  async request<T>(
    method: HttpMethod,
    endpoint: Endpoint,
    data?: unknown
  ): Promise<T> {
    const response = await fetch(endpoint, {
      method,
      headers: { 'Content-Type': 'application/json' },
      body: data ? JSON.stringify(data) : undefined,
    });
    return response.json();
  }
}

const api = new ApiClient();
api.request('GET', '/api/users/123'); // OK
api.request('GET', '/wrong/path'); // Error

결과

  • IDE에서 자동완성으로 엔드포인트 입력 편의성 증가
  • 컴파일 타임에 잘못된 경로 차단
  • 리팩토링 시 타입 에러로 누락 방지

아직 복잡한 쿼리 파라미터까지는 타이핑하지 않았지만, 기본적인 경로 검증만으로도 충분히 효과를 봤다. TypeScript 4.4의 개선된 타입 추론 덕분에 이전보다 안정적으로 동작한다.

TypeScript 4.4 template literal type으로 타입 안전성 높이기