TypeScript 실전 패턴 — 타입 안전한 API 설계
안녕하세요, 코드픽(codepick.kr) 독자 여러분!
현대 웹 애플리케이션 개발에서 API는 클라이언트와 서버 간의 핵심적인 통신 수단입니다. 잘 설계된 API는 개발 생산성을 높이고, 시스템의 안정성을 보장하며, 팀원 간의 협업을 원활하게 만듭니다. 특히, 대규모 프로젝트에서는 API 계약의 명확성과 일관성이 무엇보다 중요하죠.
하지만 JavaScript의 동적인 특성 때문에 API 통신 과정에서 예상치 못한 타입 오류가 발생하거나, 클라이언트와 서버 간의 데이터 계약 불일치로 인해 런타임 버그가 빈번하게 발생하곤 합니다. 이런 문제들은 디버깅 시간을 늘리고 개발자의 피로도를 가중시키는 주범이 됩니다.
이러한 문제에 대한 강력한 해결책이 바로 TypeScript입니다. TypeScript는 정적 타입을 통해 컴파일 시점에 잠재적인 오류를 미리 발견하고, 코드의 가독성과 예측 가능성을 크게 향상시킵니다. 이번 포스팅에서는 TypeScript를 활용하여 타입 안전한 API를 설계하고 구현하는 다양한 실전 패턴들을 자세히 살펴보겠습니다. 인터페이스, 제네릭, 식별 가능한 유니온과 같은 핵심 TypeScript 기능을 넘어, 런타임 유효성 검증 라이브러리인 Zod를 활용한 데이터 검증 전략까지, 실제 프로젝트에 바로 적용할 수 있는 유용한 팁들을 코드 예제와 함께 설명해 드릴 예정입니다.
견고하고 유지보수하기 쉬운 API를 구축하고 싶은 개발자라면 이 글이 큰 도움이 될 것입니다. 그럼, 함께 타입 안전한 API 설계의 세계로 떠나볼까요?
1. 왜 타입 안전한 API 설계가 중요한가?
타입 안전한 API 설계는 단순한 코딩 스타일을 넘어, 소프트웨어 개발 생명주기 전반에 걸쳐 막대한 이점을 제공합니다.
버그 감소와 예측 가능성 향상
JavaScript는 유연하지만, 런타임에 타입 오류가 발생하기 쉽습니다. 예를 들어, API 응답 객체에 특정 속성이 없는데도 해당 속성에 접근하려 하거나, 예상치 못한 타입의 데이터가 전달될 때 런타임 에러가 발생합니다. TypeScript는 이러한 문제들을 컴파일 시점에 잡아내어, 개발자가 코드를 실행하기 전에 잠재적인 버그를 수정할 수 있도록 돕습니다.
API의 요청(Request)과 응답(Response) 데이터 구조를 타입으로 명확히 정의하면, 개발자는 어떤 데이터가 오고 갈지 정확히 예측할 수 있습니다. 이는 "이 필드는 왜 없지?", "이 데이터는 왜 이런 타입이지?"와 같은 혼란을 줄여주고, 예측 가능한 시스템을 구축하는 데 기여합니다.
개발 생산성 및 유지보수성 증대
타입 정보는 IDE의 자동 완성(IntelliSense) 기능을 극대화하여 개발 속도를 향상시킵니다. API 응답 타입을 미리 정의해두면, 클라이언트 코드 작성 시 해당 응답 객체의 속성에 쉽게 접근하고 메서드를 호출할 수 있습니다. 이는 오타로 인한 오류를 줄이고, 개발자가 API 명세를 일일이 찾아볼 필요 없이 코드를 통해 정보를 얻을 수 있게 합니다.
또한, API 변경 사항이 발생했을 때 TypeScript는 관련 코드를 즉시 식별하여 개발자에게 알려줍니다. 예를 들어, API 응답에서 특정 필드가 제거되면, 해당 필드를 사용하는 모든 클라이언트 코드에서 컴파일 에러가 발생하여 누락된 업데이트를 쉽게 파악하고 수정할 수 있습니다. 이는 대규모 리팩토링이나 API 버전 업그레이드 시 발생하는 위험을 크게 줄여줍니다.
견고한 클라이언트-서버 계약
API는 클라이언트와 서버 간의 "계약"과 같습니다. 이 계약이 명확하고 일관적일수록 양측 개발팀은 독립적으로 작업을 진행하면서도 높은 수준의 정합성을 유지할 수 있습니다. TypeScript는 이 계약을 코드 레벨에서 강제하여, 서버 개발자가 API 응답 타입을 변경하면 클라이언트 개발자도 즉시 그 변경 사항을 인지하고 대응할 수 있도록 합니다.
이는 클라이언트와 서버 간의 불필요한 커뮤니케이션 비용을 줄이고, 데이터 무결성을 보장하며, 궁극적으로 더 안정적인 애플리케이션을 구축하는 기반이 됩니다.
2. 핵심 타입 정의 패턴
이제 TypeScript를 활용하여 API의 요청 및 응답 데이터를 효과적으로 정의하는 핵심 패턴들을 살펴보겠습니다.
API 요청/응답을 위한 인터페이스 및 타입 별칭
가장 기본적인 패턴은 API 요청 본문(Request Body)과 응답 데이터(Response Data)의 구조를 interface 또는 type 별칭으로 명확하게 정의하는 것입니다. 이는 API의 데이터 계약을 코드 레벨에서 문서화하는 역할을 합니다.
// 사용자 정보를 나타내는 기본 인터페이스
interface User {
id: string;
name: string;
email: string;
createdAt: string; // ISO 8601 형식의 날짜 문자열
status: active | inactive | pending; // 리터럴 타입 유니온
}
// 사용자 생성 요청 (Request Body)
interface CreateUserRequest {
name: string;
email: string;
password?: string; // 선택적 필드
}
// 사용자 생성 응답 (Response Data)
interface CreateUserResponse {
message: string;
user: User;
}
// 사용자 목록 조회 응답 (Response Data)
// 페이지네이션 정보를 포함할 수 있습니다.
interface GetUsersResponse {
users: User[];
totalCount: number;
page: number;
limit: number;
}
// 특정 사용자 조회 응답 (Response Data)
type GetUserResponse = User; // 응답 데이터가 User 인터페이스와 동일할 경우 타입 별칭 사용
// 예시: API 호출 함수
async function createUser(userData: CreateUserRequest): Promise<CreateUserResponse> {
const response = await fetch(/api/v1/users, {
method: POST,
headers: { Content-Type: application/json },
body: JSON.stringify(userData),
});
if (!response.ok) {
throw new Error(Failed to create user);
}
return response.json();
}
// 사용 예시
async function main() {
const newUser: CreateUserRequest = {
name: 홍길동,
email: hong.gildong@example.com,
};
try {
const result = await createUser(newUser);
console.log(User created:, result.user.name, result.user.email);
// result.user.id, result.user.createdAt 등 자동 완성 지원
} catch (error) {
console.error(error);
}
}
main();위 예시에서 interface는 객체의 구조를 정의하는 데 사용되며, type 별칭은 기존 타입에 새로운 이름을 부여하거나 유니온, 인터섹션 등 복합 타입을 정의할 때 유용합니다. API의 각 엔드포인트에 대한 요청과 응답 타입을 명확히 정의함으로써, 클라이언트 개발자는 어떤 데이터를 보내고 받을지 정확히 알 수 있습니다.
제네릭을 활용한 재사용 가능한 API 클라이언트
많은 API 요청은 공통적인 구조를 가집니다 (예: GET, POST 요청에 대한 성공/실패 응답). 이러한 공통 패턴을 추상화하고 재사용성을 높이기 위해 **제네릭(Generics)**을 활용할 수 있습니다. 제네릭은 다양한 타입에서 동작하는 컴포넌트나 함수를 만들 때 유용합니다.
API 클라이언트 함수에 제네릭을 적용하면, 하나의 함수로 여러 종류의 데이터를 처리하면서도 타입 안전성을 유지할 수 있습니다.
// 일반적인 API 응답 구조 (선택 사항)
// 모든 API 응답이 data 필드와 message 필드를 가질 경우 유용합니다.
interface ApiResponse<T> {
statusCode: number;
message: string;
data: T; // 제네릭 타입 T가 실제 데이터의 타입을 결정합니다.
}
// 에러 응답 구조
interface ApiErrorResponse {
statusCode: number;
message: string;
error?: string;
}
// 제네릭을 활용한 범용 API 호출 함수
async function callApi<T>(
url: string,
method: GET | POST | PUT | DELETE,
body?: object,
headers?: HeadersInit
): Promise<ApiResponse<T>> {
const response = await fetch(url, {
method,
headers: {
Content-Type: application/json,
...headers,
},
body: body ? JSON.stringify(body) : undefined,
});
if (!response.ok) {
const errorData: ApiErrorResponse = await response.json();
throw new Error(`API Error ${errorData.statusCode}: ${errorData.message}`);
}
return response.json();
}
// User 관련 API 타입 정의 (위에서 정의한 User, CreateUserRequest 등 재사용)
// interface User { ... }
// interface CreateUserRequest { ... }
// interface CreateUserResponse { message: string; user: User; } // ApiResponse<User>와 호환되도록 조정 가능
// 사용 예시
async function fetchDataExample() {
try {
// 사용자 생성
const newUserRequest: CreateUserRequest = { name: 이순신, email: lee.soonshin@example.com };
const createResult = await callApi<User>(/api/v1/users, POST, newUserRequest);
console.log(Created user:, createResult.data.name);
// createResult.data는 User 타입으로 추론됩니다.
// 사용자 목록 조회
const usersResult = await callApi<User[]>(/api/v1/users, GET);
console.log(Users:, usersResult.data.map(user => user.name));
// usersResult.data는 User[] 타입으로 추론됩니다.
// 특정 사용자 조회
const userId = createResult.data.id;
const userResult = await callApi<User>(`/api/v1/users/${userId}`, GET);
console.log(Fetched user:, userResult.data.email);
} catch (error: any) {
console.error(API call failed:, error.message);
}
}
fetchDataExample();callApi 함수는 T라는 제네릭 타입을 받아, API 응답의 data 필드에 대한 타입을 동적으로 결정합니다. 이를 통해 각 API 호출마다 응답 타입을 명시적으로 지정하여 컴파일 타임에 정확한 타입 검사를 받을 수 있습니다. 이는 코드의 반복을 줄이고 유지보수성을 크게 향상시킵니다.
열거형(Enum)으로 API 상수 관리
API에서 특정 필드의 값이 미리 정의된 몇 가지 값 중 하나여야 하는 경우가 많습니다. 예를 들어, 사용자 상태(active, inactive, pending), 주문 상태(pending, processing, shipped, delivered), 역할(admin, user, guest) 등이 그렇습니다. 이러한 상수 값들을 TypeScript의 **열거형(Enum)**으로 관리하면 코드의 가독성과 타입 안전성을 높일 수 있습니다.
// 사용자 상태 열거형
enum UserStatus {
Active = ACTIVE,
Inactive = INACTIVE,
Pending = PENDING,
Suspended = SUSPENDED,
}
// API 엔드포인트 열거형 (문자열 리터럴 타입 유니온으로도 대체 가능)
enum ApiEndpoint {
Users = /api/v1/users,
Products = /api/v1/products,
Orders = /api/v1/orders,
}
interface User {
id: string;
name: string;
email: string;
status: UserStatus; // UserStatus 열거형 사용
}
interface UpdateUserStatusRequest {
status: UserStatus; // 요청 본문에도 열거형 사용
}
// 예시: 사용자 상태 업데이트 함수
async function updateUserStatus(userId: string, newStatus: UserStatus): Promise<User> {
const response = await fetch(`${ApiEndpoint.Users}/${userId}/status`, {
method: PUT,
headers: { Content-Type: application/json },
body: JSON.stringify({ status: newStatus }),
});
if (!response.ok) {
throw new Error(Failed to update user status);
}
const result: User = await response.json();
return result;
}
// 사용 예시
async function updateUserStatusExample() {
const targetUserId = some-user-id-123;
try {
const updatedUser = await updateUserStatus(targetUserId, UserStatus.Inactive);
console.log(`User ${updatedUser.name}s status updated to: ${updatedUser.status}`);
// 잘못된 상태 값 사용 시 컴파일 에러 발생
// await updateUserStatus(targetUserId, invalid-status); // Error: Argument of type "invalid-status" is not assignable to parameter of type UserStatus.
} catch (error) {
console.error(error);
}
}
updateUserStatusExample();UserStatus 열거형을 사용하면 status 필드에 할당할 수 있는 값을 명확히 제한할 수 있습니다. 이는 개발자가 오타를 입력하거나 유효하지 않은 값을 사용하는 것을 방지하여 런타임 오류를 줄여줍니다. 또한, 코드의 의도를 명확히 하여 가독성을 높입니다.
식별 가능한 유니온(Discriminated Unions)으로 복합 응답 처리
API 응답이 특정 필드의 값에 따라 다른 구조를 가질 때, **식별 가능한 유니온(Discriminated Unions)**은 매우 강력한 패턴입니다. 예를 들어, API 호출 결과가 성공일 때는 데이터 객체를 포함하고, 실패일 때는 에러 메시지를 포함하는 경우가 있습니다.
이 패턴은 공통의 "식별자(discriminant)" 필드를 사용하여 TypeScript가 런타임에 어떤 유니온 멤버가 사용되었는지 추론할 수 있도록 합니다.
// 공통적인 API 응답 인터페이스 (식별자 status 포함)
interface ApiResponseBase {
status: success | error;
timestamp: string;
}
// 성공 응답 타입
interface SuccessResponse<T> extends ApiResponseBase {
status: success; // 식별자
data: T;
}
// 에러 응답 타입
interface ErrorResponse extends ApiResponseBase {
status: error; // 식별자
code: string;
message: string;
details?: Record<string, any>;
}
// API 호출 결과 유니온 타입
type FetchResult<T> = SuccessResponse<T> | ErrorResponse;
// 예시: 특정 리소스 조회 함수
async function fetchResource<T>(url: string): Promise<FetchResult<T>> {
const response = await fetch(url);
const jsonResponse: ApiResponseBase & (SuccessResponse<T> | ErrorResponse) = await response.json();
// 서버 응답이 status 필드를 포함한다고 가정
if (jsonResponse.status === success) {
// TypeScript는 이제 jsonResponse가 SuccessResponse<T> 타입임을 압니다.
return jsonResponse as SuccessResponse<T>;
} else {
// TypeScript는 이제 jsonResponse가 ErrorResponse 타입임을 압니다.
return jsonResponse as ErrorResponse;
}
}
// 사용자 정의 인터페이스 (위에서 정의한 User 재사용)
// interface User { id: string; name: string; email: string; status: UserStatus; }
// 사용 예시
async function fetchUserExample() {
try {
const userId = user-123;
const result = await fetchResource<User>(`/api/v1/users/${userId}`);
if (result.status === success) {
// result는 SuccessResponse<User> 타입으로 추론됨
console.log(`User found: ${result.data.name}, Email: ${result.data.email}`);
// result.data는 User 타입이므로 .name, .email에 접근 가능
} else {
// result는 ErrorResponse 타입으로 추론됨
console.log(`Error fetching user: ${result.message} (Code: ${result.code})`);
// result.data에 접근하려 하면 컴파일 에러 발생
}
const nonExistentUserId = non-existent-user;
const errorResult = await fetchResource<User>(`/api/v1/users/${nonExistentUserId}`);
if (errorResult.status === success) {
console.log(`User found: ${errorResult.data.name}`);
} else {
console.log(`Error fetching user: ${errorResult.message} (Code: ${errorResult.code})`);
// 예상: Error fetching user: User not found (Code: NOT_FOUND)
}
} catch (error) {
console.error(Network or unexpected error:, error);
}
}
fetchUserExample();FetchResult<T>는 SuccessResponse<T>와 ErrorResponse의 유니온 타입입니다. status 필드를 식별자로 사용하여 if (result.status === success)와 같은 조건문 안에서 TypeScript는 result 객체의 타입을 자동으로 좁힙니다(Type Narrowing). 이를 통해 개발자는 각 경우에 해당하는 필드에만 안전하게 접근할 수 있으며, 잘못된 필드 접근으로 인한 런타임 오류를 방지할 수 있습니다.
3. 런타임 타입 검증과 데이터 유효성
TypeScript는 컴파일 타임에 타입 안전성을 보장하지만, 네트워크를 통해 들어오는 데이터(예: API 응답, 사용자 입력)는 TypeScript의 타입 시스템의 통제 밖에 있습니다. 즉, 서버가 약속된 타입과 다른 데이터를 보내더라도 TypeScript는 이를 컴파일 시점에 알 수 없습니다. 이러한 외부 데이터의 유효성을 검사하고 타입 안정성을 확보하기 위해 런타임 타입 검증이 필요합니다.
컴파일 타임 vs. 런타임 유효성 검사
- 컴파일 타임 유효성 검사 (TypeScript): 개발자가 코드를 작성하는 시점과 컴파일 시점에 타입 일치 여부를 확인합니다. 코드 내에서 변수 할당, 함수 호출 시 타입 규칙을 따르는지 검사하여 개발 오류를 줄입니다. 하지만 외부에서 유입되는 데이터의 실제 구조를 보장하지는 못합니다.
- 런타임 유효성 검사 (Zod, Yup, Joi 등): 애플리케이션이 실행되는 시점에 실제 데이터의 구조와 값을 검사합니다. 예를 들어, API 응답이 기대하는 스키마를 따르는지, 사용자 입력이 특정 조건을 만족하는지 등을 확인하여 데이터 무결성을 보장하고 런타임 오류를 방지합니다.
타입 안전한 API 설계를 위해서는 이 두 가지 검증 방식이 상호 보완적으로 사용되어야 합니다. TypeScript로 컴파일 타임 안전성을 확보하고, 런타임 유효성 검사 라이브러리로 외부 데이터의 무결성을 보장하는 것이 이상적입니다.
Zod를 이용한 스키마 정의 및 유효성 검사
Zod는 TypeScript 우선(TypeScript-first) 런타임 유효성 검사 라이브러리입니다. Zod의 가장 큰 장점은 스키마 정의를 통해 TypeScript 타입도 자동으로 추론할 수 있다는 점입니다. 이는 타입 정의의 중복을 피하고, 런타임 유효성 검사 로직과 컴파일 타임 타입 정의 간의 일관성을 유지하는 데 매우 효과적입니다.
import { z } from zod;
// 1. Zod 스키마 정의
const userStatusSchema = z.enum([ACTIVE, INACTIVE, PENDING, SUSPENDED]);
const userSchema = z.object({
id: z.string().uuid("유효한 UUID 형식이 아닙니다."), // UUID 형식 검증
name: z.string().min(1, "이름은 필수입니다."),
email: z.string().email("유효한 이메일 형식이 아닙니다."),
createdAt: z.string().datetime("유효한 날짜 시간 형식이 아닙니다."), // ISO 8601 날짜 시간 검증
status: userStatusSchema,
});
const createUserRequestSchema = z.object({
name: z.string().min(1, "이름은 필수입니다."),
email: z.string().email("유효한 이메일 형식이 아닙니다."),
password: z.string().min(6, "비밀번호는 최소 6자 이상이어야 합니다.").optional(), // 선택적 필드
});
// 2. Zod 스키마로부터 TypeScript 타입 추론
type User = z.infer<typeof userSchema>;
type CreateUserRequest = z.infer<typeof createUserRequestSchema>;
// 3. API 응답에 Zod 스키마 적용
// 예시: API 응답을 검증하는 함수
async function fetchAnd