프론트엔드 TypeScript 타입 스킬
목적: frontend/types/index.ts의 기존 패턴을 따라 TypeScript 타입 정의를 생성하기 위한 가이드입니다.
개요
모든 TypeScript 타입은 frontend/types/index.ts에 정의됩니다. 타입은 백엔드 API 응답 구조와 일치하며 프론트엔드 애플리케이션 전반에 타입 안전성을 제공합니다.
frontend/types/index.ts의 타입 패턴
1. 사용자 타입
export interface User {
id: string;
email: string;
name: string;
createdAt?: string;
updatedAt?: string;
}
export interface UserCredentials {
email: string;
password: string;
}
export interface UserSignupData extends UserCredentials {
name: string;
}
패턴:
- 객체 타입에는
interface사용 - 선택적 필드는
?로 표시 - 타입 상속에는
extends사용 - 프론트엔드 타입에는 camelCase 사용 (백엔드가 snake_case를 사용하더라도)
2. 작업 타입
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
export interface Task {
id: number;
user_id: string;
title: string;
description?: string;
completed: boolean;
priority: TaskPriority;
due_date?: string;
tags: string[];
created_at: string;
updated_at: string;
}
export interface TaskFormData {
title: string;
description?: string;
priority?: TaskPriority;
due_date?: string;
tags?: string[];
}
export interface TaskQueryParams {
status?: "all" | "pending" | "completed";
sort?: "created" | "title" | "updated" | "priority" | "due_date";
search?: string;
page?: number;
limit?: number;
}
패턴:
- 유니온 타입(문자열 리터럴)에는
type사용 - 객체 타입에는
interface사용 - 백엔드 필드 이름과 일치 (API 필드의 경우 snake_case 사용:
user_id,due_date,created_at) - 폼 데이터를 위한 별도 타입 생성 (필수 필드 외에는 모두 선택적)
- 쿼리 파라미터를 위한 별도 타입 생성 (모두 선택적)
3. API 응답 타입
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
message?: string;
error?: {
code: string;
message: string;
details?: unknown;
};
}
export interface PaginatedResponse<T> {
data: T[];
meta: {
total: number;
page: number;
limit: number;
totalPages: number;
};
}
패턴:
- 재사용 가능한 구조에는 제네릭 타입
<T>사용 - 기본 타입 매개변수 제공 (
<T = unknown>) successboolean 플래그 포함- 선택적
data,message,error필드 포함 meta객체를 포함한 페이지네이션 응답을 위한 별도 타입 생성
4. 인증 타입
export interface AuthResponse {
success: boolean;
token: string;
user: User;
}
export interface Session {
user: User;
token: string;
expiresAt: number;
}
패턴:
successboolean 포함token문자열 포함user객체(User 타입) 포함- 세션에
expiresAt타임스탬프 포함
5. 오류 타입
export interface AppError {
message: string;
code?: string;
statusCode?: number;
field?: string;
}
export interface FormErrors {
[key: string]: string | undefined;
}
패턴:
- 오류 객체에는
interface사용 - 선택적 필드는
?로 표시 - 동적 객체 타입(FormErrors)에는 인덱스 시그니처
[key: string]사용
6. UI 타입
export type LoadingState = "idle" | "loading" | "success" | "error";
export type ToastType = "success" | "error" | "warning" | "info";
export interface ToastMessage {
id: string;
type: ToastType;
message: string;
duration?: number;
}
패턴:
- 유니온 타입(문자열 리터럴)에는
type사용 - 객체 타입에는
interface사용 - 고유 식별을 위해
id포함 - 선택적 필드는
?로 표시
7. 내보내기/가져오기 타입
export type ExportFormat = "csv" | "json";
export interface ImportResult {
imported: number;
errors: number;
errorDetails?: string[];
}
패턴:
- 유니온 타입(문자열 리터럴)에는
type사용 - 결과 객체에는
interface사용 - 성공/오류 추적을 위한 카운트 포함
- 선택적 오류 세부 정보 배열 포함
타입 명명 규칙
인터페이스
- 파스칼케이스:
User,Task,ApiResponse - 설명적인 이름:
TaskFormData,UserSignupData
타입 (유니온 타입)
- 파스칼케이스:
TaskStatus,TaskPriority,LoadingState - 설명적인 이름:
ToastType,ExportFormat
Props 타입
- 컴포넌트이름 + Props:
TaskItemProps,ProtectedRouteProps - 예시:
interface TaskItemProps { task: Task; }
폼 데이터 타입
- 엔티티이름 + FormData:
TaskFormData,UserSignupData - 예시:
interface TaskFormData { title: string; description?: string; }
쿼리 파라미터 타입
- 엔티티이름 + QueryParams:
TaskQueryParams - 예시:
interface TaskQueryParams { status?: "all" | "pending" | "completed"; }
백엔드 스키마 일치
필드 이름 매핑
백엔드 (snake_case) → 프론트엔드 (폼 데이터: camelCase, API 응답: snake_case)
// 백엔드 API 응답 (백엔드와 정확히 일치)
export interface Task {
id: number;
user_id: string; // 백엔드의 snake_case
title: string;
due_date?: string; // 백엔드의 snake_case
created_at: string; // 백엔드의 snake_case
updated_at: string; // 백엔드의 snake_case
}
// 프론트엔드 폼 데이터 (더 쉬운 사용을 위한 camelCase)
export interface TaskFormData {
title: string;
dueDate?: string; // 프론트엔드를 위한 camelCase
tags?: string[];
}
패턴:
- API 응답 타입은 백엔드와 정확히 일치 (snake_case)
- 폼 데이터 타입은 더 쉬운 프론트엔드 사용을 위해 camelCase 사용
- API와 데이터를 주고받을 때 형식 간 변환
필수 필드 vs 선택적 필드
// 백엔드 API 응답 (백엔드의 모든 필드)
export interface Task {
id: number; // 필수 (백엔드)
user_id: string; // 필수 (백엔드)
title: string; // 필수 (백엔드)
description?: string; // 선택적 (백엔드)
completed: boolean; // 필수 (백엔드)
priority: TaskPriority; // 필수 (백엔드)
due_date?: string; // 선택적 (백엔드)
tags: string[]; // 필수 (백엔드, 빈 배열 가능)
created_at: string; // 필수 (백엔드)
updated_at: string; // 필수 (백엔드)
}
// 프론트엔드 폼 데이터 (사용자가 편집할 수 있는 필드만)
export interface TaskFormData {
title: string; // 필수 (사용자가 제공해야 함)
description?: string; // 선택적
priority?: TaskPriority; // 선택적 (기본값 있음)
due_date?: string; // 선택적
tags?: string[]; // 선택적 (빈 배열 가능)
}
패턴:
- API 응답 타입은 백엔드의 모든 필드를 포함
- 폼 데이터 타입은 사용자가 편집할 수 있는 필드만 포함
- 선택적 필드는
?로 표시 - 필수 필드에는
?없음
타입 구조 패턴
1. 객체에는 interface 사용
export interface User {
id: string;
email: string;
}
사용 시기: 속성이 있는 객체 타입
2. 유니온, 교차 또는 별칭에는 type 사용
export type TaskStatus = "pending" | "completed";
export type TaskPriority = "low" | "medium" | "high";
사용 시기: 유니온 타입, 교차 타입 또는 타입 별칭
3. 재사용 가능한 구조에는 제네릭 타입 사용
export interface ApiResponse<T = unknown> {
data?: T;
success: boolean;
}
사용 시기: 다양한 타입과 함께 작동하는 재사용 가능한 구조
4. 선택적 속성은 ?로 표시
export interface Task {
title: string; // 필수
description?: string; // 선택적
}
사용 시기: 존재하지 않을 수 있는 필드
완전한 예제: 새 타입 추가하기
1단계: 엔티티 타입 정의 (백엔드와 일치)
export interface Category {
id: number;
user_id: string;
name: string;
color?: string;
created_at: string;
updated_at: string;
}
2단계: 폼 데이터 타입 정의 (사용자 입력용)
export interface CategoryFormData {
name: string;
color?: string;
}
3단계: 쿼리 파라미터 타입 정의 (API 쿼리용)
export interface CategoryQueryParams {
search?: string;
page?: number;
limit?: number;
}
4단계: API 클라이언트에서 사용
async getCategories(
userId: string,
queryParams?: CategoryQueryParams
): Promise<ApiResponse<PaginatedResponse<Category>>> {
// 구현
}
헌법 요구 사항
- FR-030: 모든 API 호출에 대해 타입이 지정된 TypeScript 인터페이스 ✅
- FR-037: TypeScript strict 모드 ✅
참고 자료
- 명세서:
specs/002-frontend-todo-app/spec.md- 엔티티 정의 - 계획:
specs/002-frontend-todo-app/plan.md- 타입이 포함된 API 계약 - 타입 파일:
frontend/types/index.ts- 완전한 타입 정의
일반 패턴 요약
- ✅ 객체 타입에는
interface사용 - ✅ 유니온 타입(문자열 리터럴)에는
type사용 - ✅ 재사용 가능한 구조에는 제네릭 타입
<T>사용 - ✅ 선택적 필드는
?로 표시 - ✅ 백엔드 필드 이름과 일치 (API 응답은 snake_case)
- ✅ 폼 데이터 타입에는 camelCase 사용
- ✅ 폼 데이터와 쿼리 파라미터를 위한 별도 타입 생성
- ✅ 설명적인 이름 사용 (EntityFormData, EntityQueryParams)
- ✅ 백엔드의 모든 필수 필드 포함
- ✅ 제네릭에 기본 타입 매개변수 제공 (
<T = unknown>)