前端 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实现类型继承 - 前端类型使用驼峰命名法(即使后端使用蛇形命名法)
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 字段使用蛇形命名法,如
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>) - 包含
success布尔标志 - 包含可选的
data、message和error字段 - 为分页响应创建单独类型,包含
meta对象
4. 认证类型
export interface AuthResponse {
success: boolean;
token: string;
user: User;
}
export interface Session {
user: User;
token: string;
expiresAt: number;
}
模式:
- 包含
success布尔值 - 包含
token字符串 - 包含
user对象(User 类型) - 包含会话的
expiresAt时间戳
5. 错误类型
export interface AppError {
message: string;
code?: string;
statusCode?: number;
field?: string;
}
export interface FormErrors {
[key: string]: string | undefined;
}
模式:
- 使用
interface定义错误对象 - 使用
?标记可选字段 - 使用索引签名
[key: string]定义动态对象类型(FormErrors)
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"; }
匹配后端模式
字段名映射
后端(蛇形命名法) → 前端(表单数据使用驼峰命名法,API 响应使用蛇形命名法)
// 后端 API 响应(与后端完全匹配)
export interface Task {
id: number;
user_id: string; // 后端的蛇形命名法
title: string;
due_date?: string; // 后端的蛇形命名法
created_at: string; // 后端的蛇形命名法
updated_at: string; // 后端的蛇形命名法
}
// 前端表单数据(驼峰命名法便于使用)
export interface TaskFormData {
title: string;
dueDate?: string; // 前端使用驼峰命名法
tags?: string[];
}
模式:
- API 响应类型与后端完全匹配(蛇形命名法)
- 表单数据类型使用驼峰命名法,便于前端使用
- 在发送/接收 API 数据时进行格式转换
必填字段与可选字段
// 后端 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 严格模式 ✅
参考资料
- 规范:
specs/002-frontend-todo-app/spec.md- 实体定义 - 计划:
specs/002-frontend-todo-app/plan.md- 带类型的 API 合约 - 类型文件:
frontend/types/index.ts- 完整的类型定义
常见模式总结
- ✅ 使用
interface定义对象类型 - ✅ 使用
type定义联合类型(字符串字面量) - ✅ 使用泛型
<T>实现可复用结构 - ✅ 使用
?标记可选字段 - ✅ 匹配后端字段名(API 响应使用蛇形命名法)
- ✅ 表单数据类型使用驼峰命名法
- ✅ 为表单数据和查询参数创建单独类型
- ✅ 使用描述性名称(EntityFormData、EntityQueryParams)
- ✅ 包含后端的全部必填字段
- ✅ 为泛型提供默认类型参数(
<T = unknown>)