Комплексная практика проекта на TypeScript
В этом руководстве на примере полного проекта комплексно применяются различные возможности TypeScript.
От настройки проекта до фактической разработки — оно полностью демонстрирует применение TypeScript в реальных проектах.
SVG-диаграмма: архитектура проекта
Зачем нужна комплексная практика проекта?
После изучения синтаксиса TypeScript вам нужно закрепить знания на реальных проектах.
В этом руководстве демонстрируется полная система управления задачами, охватывающая фронтенд, бэкенд и определения типов.
На этом проекте вы сможете освоить лучшие практики TypeScript в реальной разработке.
Цели проекта:Создать систему управления задачами с возможностями создания, запроса, обновления и удаления задач.
Структура проекта
Организовать структуру проекта в стиле Monorepo.
Структура каталогов
├── src/
│ ├── types/# Определения типов
│ │ ├── task.ts# Типы задач
│ │ ├── api.ts# Типы API
│ │ └── index.ts# Экспорт типов
│ │
│ ├── services/# Слой сервисов
│ │ ├── taskService.ts# Сервис задач
│ │ └── index.ts
│ │
│ ├── components/# Компоненты React
│ │ ├── TaskList.tsx# Список задач
│ │ ├── TaskItem.tsx# Элемент задачи
│ │ ├── TaskForm.tsx# Форма задачи
│ │ └── index.ts
│ │
│ ├── hooks/# Пользовательские хуки
│ │ ├── useTasks.ts# Управление состоянием задач
│ │ └── index.ts
│ │
│ ├── App.tsx# Главное приложение
│ ├── App.css# Стили
│ └── main.tsx# Входной файл
│
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
Разделение каталогов:Каталоги разделены по функциональности: отдельно определения типов, сервисный слой и компоненты.
Определения типов
Сначала определите основные типы проекта.
src/types/task.ts
export type TaskStatus = "pending" | "in-progress" | "completed";
// Перечисление приоритетов задачи
export type TaskPriority = "low" | "medium" | "high";
// Определение интерфейса Task
export interface Task {
id: string; // ID задачи
title: string; // Название задачи
description?: string; // Описание задачи (необязательно)
status: TaskStatus; // Статус задачи
priority: TaskPriority; // Приоритет задачи
createdAt: string; // Время создания
updatedAt: string; // Время обновления
dueDate?: string; // Дата выполнения (необязательно)
tags?: string[]; // Теги (необязательно)
}
// Входной тип для создания задачи
export interface CreateTaskInput {
title: string;
description?: string;
priority: TaskPriority;
dueDate?: string;
tags?: string[];
}
// Входной тип для обновления задачи
export interface UpdateTaskInput {
title?: string;
description?: string;
status?: TaskStatus;
priority?: TaskPriority;
dueDate?: string;
tags?: string[];
}
// Параметры фильтра задач
export interface TaskFilter {
status?: TaskStatus;
priority?: TaskPriority;
search?: string;
}
Разделение типов по слоям:Определяйте входные типы, выходные типы и типы фильтров отдельно для упрощения поддержки.
Определения типов API
Определите типы, связанные с API.
export interface ApiResponse<T> {
success: boolean;
data?: T;
error?: string;
message?: string;
}
// Метаданные пагинации
export interface PaginationMeta {
total: number;
page: number;
pageSize: number;
totalPages: number;
}
// Тип ответа с пагинацией
export interface PaginatedResponse<T> {
items: T[];
meta: PaginationMeta;
}
// Тип ошибки запроса
export interface ApiError {
code: string;
message: string;
details?: Record<string, string>;
}
// Тип HTTP-метода
export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
// Эндпоинты API, связанные с задачами
export interface TaskEndpoints {
getAll: "/api/tasks";
getById: "/api/tasks/:id";
create: "/api/tasks";
update: "/api/tasks/:id";
delete: "/api/tasks/:id";
}
Типы API:Унифицированный формат ответа и типы обработки ошибок упрощают интеграцию фронтенда и бэкенда.
Сервисный слой задач
Реализуйте бизнес-логику для управления задачами.
src/services/taskService.ts
import {
Задача,
CreateTaskInput,
UpdateTaskInput,
TaskFilter,
TaskStatus,
TaskPriority
} from "../types/task";
// Сгенерировать уникальный ID
function generateId(): string {
return Date.now().toString(36) + Math.random().toString(36).substr(2);
}
// Имитация базы данных (хранилище в памяти)
let tasks: Task[] = [
{
id: "1",
title: "Изучить TypeScript",
description: "Освойте основы TypeScript и продвинутые возможности",
status: "завершено",
priority: "высокий",
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
tags: ["Изучение", "TypeScript"]
},
{
id: "2",
title: "Разработать систему управления задачами",
description: "Разработка с использованием React + TypeScript",
status: "в процессе",
priority: "высокий",
createdAt: new Date().toISOString(),
updatedAt: new Date().toISOString(),
tags: ["Project", "Practice"]
}
];
// Класс сервиса задач
class TaskService {
// Получить все задачи
getAll(filter?: TaskFilter): Task[] {
let result = [...tasks];
if (filter) {
if (filter.status) {
result = result.filter(t => t.status === filter.status);
}
if (filter.priority) {
result = result.filter(t => t.priority === filter.priority);
}
if (filter.search) {
const search = filter.search.toLowerCase();
result = result.filter(t =>
t.title.toLowerCase().includes(search) ||
t.description?.toLowerCase().includes(search)
);
}
}
return result;
}
// Получить задачу по ID
getById(id: string): Task | undefined {
return tasks.find(t => t.id === id);
}
// Создать задачу
create(input: CreateTaskInput): Task {
const now = new Date().toISOString();
const task: Task = {
id: generateId(),
title: input.title,
description: input.description,
status: "pending",
priority: input.priority,
createdAt: now,
updatedAt: now,
dueDate: input.dueDate,
tags: input.tags
};
tasks.push(task);
return task;
}
// Обновить задачу
update(id: string, input: UpdateTaskInput): Task | null {
const index = tasks.findIndex(t => t.id === id);
if (index === -1) return null;
const task = tasks[index];
const updated: Task = {
...задача,
...input,
updatedAt: new Date().toISOString()
};
tasks[index] = updated;
return updated;
}
// Удалить задачу
delete(id: string): boolean {
const index = tasks.findIndex(t => t.id === id);
if (index === -1) return false;
tasks.splice(index, 1);
return true;
}
// Обновить статус задачи
updateStatus(id: string, status: TaskStatus): Task | null {
return this.update(id, { status });
}
}
// Экспортировать экземпляр сервиса
export const taskService = new TaskService();
Сервисный слой:Бизнес-логика централизована в сервисном слое для удобства тестирования и поддержки.
Пользовательский хук
Используйте хук для управления состоянием задачи.
import { useState, useEffect, useCallback } from "react";
import {
Задача,
CreateTaskInput,
UpdateTaskInput,
TaskFilter,
TaskStatus,
TaskPriority
} from "../types/task";
import { taskService } from "../services/taskService";
// Тип состояния, возвращаемый хуком
interface UseTasksReturn {
tasks: Task[];
loading: boolean;
error: string | null;
filter: TaskFilter;
// Методы операций
createTask: (input: CreateTaskInput) => Promise<void>;
updateTask: (id: string, input: UpdateTaskInput) => Promise<void>;
deleteTask: (id: string) => Promise<void>;
updateStatus: (id: string, status: TaskStatus) => Promise<void>;
setFilter: (filter: TaskFilter) => void;
refresh: () => void;
}
// Инициализировать фильтр по умолчанию
const defaultFilter: TaskFilter = {};
export function useTasks(): UseTasksReturn {
// Состояние списка задач
const [tasks, setTasks] = useState<Task[]>([]);
// Состояние загрузки
const [loading, setLoading] = useState(true);
// Состояние ошибки
const [error, setError] = useState<string | null>(null);
// Условия фильтрации
const [filter, setFilter] = useState<TaskFilter>(defaultFilter);
// Загрузка списка задач
const loadTasks = useCallback(() => {
setLoading(true);
setError(null);
try {
const data = taskService.getAll(filter);
setTasks(data);
} catch (err) {
setError(err instanceof Error ? err.message : "Не удалось загрузить");
} finally {
setLoading(false);
}
}, [filter]);
// Перезагружать при начальной загрузке и изменении фильтров
useEffect(() => {
loadTasks();
}, [loadTasks]);
// Создать задачу
const createTask = useCallback(async (input: CreateTaskInput) => {
try {
taskService.create(input);
loadTasks();
} catch (err) {
setError(err instanceof Error ? err.message : "Не удалось создать");
}
}, [loadTasks]);
// Обновить задачу
const updateTask = useCallback(async (id: string, input: UpdateTaskInput) => {
try {
taskService.update(id, input);
loadTasks();
} catch (err) {
setError(err instanceof Error ? err.message : "Не удалось обновить");
}
}, [loadTasks]);
// Удалить задачу
const deleteTask = useCallback(async (id: string) => {
try {
taskService.delete(id);
loadTasks();
} catch (err) {
setError(err instanceof Error ? err.message : "Не удалось удалить");
}
}, [loadTasks]);
// Обновить статус задачи
const updateStatus = useCallback(async (id: string, status: TaskStatus) => {
try {
taskService.updateStatus(id, status);
loadTasks();
} catch (err) {
setError(err instanceof Error ? err.message : "Не удалось обновить статус");
}
}, [loadTasks]);
// Обновить список задач
const refresh = useCallback(() => {
loadTasks();
}, [loadTasks]);
return {
tasks,
loading,
error,
filter,
createTask,
updateTask,
deleteTask,
updateStatus,
setFilter,
refresh
};
}
Пользовательский хук:Инкапсулируйте управление состоянием и бизнес-логику в хуке, делая компоненты более лаконичными.
Компоненты React
Используйте хук для создания компонента списка задач.
src/components/TaskList.tsx
import React from "react";
import { useTasks } from "../hooks/useTasks";
import { Task, TaskStatus, TaskPriority } from "../types/task";
// Props компонента элемента задачи
interface TaskItemProps {
task: Task;
onStatusChange: (id: string, status: TaskStatus) => void;
onDelete: (id: string) => void;
}
// Компонент элемента задачи
const TaskItem: React.FC<TaskItemProps> = ({
задача,
onStatusChange,
onDelete
}) => {
// Сопоставление стилей статуса
const statusStyles: Record<TaskStatus, string> = {
"pending": "status-pending",
"in-progress": "status-progress",
"completed": "status-completed"
};
// Сопоставление стилей приоритета
const priorityLabels: Record<TaskPriority, string> = {
"low": "Низкий",
"medium": "Средний",
"high": "Высокий"
};
return (
<div className={`task-item ${statusStyles[task.status]}`}>
<div className="task-content">
<h3 className="task-title">{task.title}</h3>
{task.description && (
<p className="task-description">{task.description}</p>
)}
<div className="task-meta">
<span className={`priority priority-${task.priority}`}>
{priorityLabels[task.priority]}
</span>
<span className="task-date">
{new Date(task.createdAt).toLocaleDateString()}
</span>
</div>
</div>
<div className="task-actions">
<select
value={task.status}
onChange={(e) => onStatusChange(task.id, e.target.value as TaskStatus)}
className="status-select"
>
<option value="pending">Ожидает</option>
<option value="in-progress">В процессе</option>
<option value="completed">Завершено</option>
</select>
<button
onClick={() => onDelete(task.id)}
className="delete-btn"
>
Delete
</button>
</div>
</div>
);
};
// Компонент списка задач
export const TaskList: React.FC = () => {
// Использовать пользовательский хук для получения состояния задач
const {
tasks,
loading,
error,
updateStatus,
deleteTask
} = useTasks();
// Отображение состояния загрузки
if (loading) {
return <div className="loading">Загрузка...</div>;
}
// Отображение состояния ошибки
if (error) {
return <div className="error">Ошибка: {error}</div>;
}
// Отображение пустого состояния
if (tasks.length === 0) {
return (
<div className="empty">
<p>Пока нет задач</p>
<p>Нажмите кнопку выше, чтобы создать новую задачу</p>
</div>
);
}
// Отображение списка задач
return (
<div className="task-list">
{tasks.map(task => (
<TaskItem
key={task.id}
task={task}
onStatusChange={updateStatus}
onDelete={deleteTask}
/>
))}
</div>
);
};
export default TaskList;
Разделение компонентов:Разделите TaskItem на независимый компонент, сделав код понятнее.
Основной компонент приложения
Интегрируйте все компоненты, чтобы сформировать полноценное приложение.
src/App.tsx
import React, { useState } from "react";
import { TaskList } from "./components/TaskList";
import { useTasks } from "./hooks/useTasks";
import { CreateTaskInput, TaskPriority } from "./types/task";
import "./App.css";
// Пропсы компонента формы задачи
interface TaskFormProps {
onSubmit: (input: CreateTaskInput) => void;
}
// Компонент формы задачи
const TaskForm: React.FC<TaskFormProps> = ({ onSubmit }) => {
// Состояние формы
const [title, setTitle] = useState("");
const [description, setDescription] = useState("");
const [priority, setPriority] = useState<TaskPriority>("medium");
// Обработка отправки
const handleSubmit = (e: React.FormEvent) => {
e.preventDefault();
if (!title.trim()) {
alert("Пожалуйста, введите название задачи");
return;
}
onSubmit({
title: title.trim(),
description: description.trim() || undefined,
priority
});
// Сброс формы
setTitle("");
setDescription("");
setPriority("medium");
};
return (
<form onSubmit={handleSubmit} className="task-form">
<input
type="text"
value={title}
onChange={(e) => setTitle(e.target.value)}
placeholder="Введите название задачи"
className="form-input"
/>
<input
type="text"
value={description}
onChange={(e) => setDescription(e.target.value)}
placeholder="Введите описание задачи (необязательно)"
className="form-input"
/>
<select
value={priority}
onChange={(e) => setPriority(e.target.value as TaskPriority)}
className="form-select"
>
<option value="low">Низкий приоритет</option>
<option value="medium">Средний приоритет</option>
<option value="high">Высокий приоритет</option>
</select>
<button type="submit" className="submit-btn">
Добавить задачу
</button>
</форма>
);
};
// Основной компонент приложения
const App: React.FC = () => {
// Использовать пользовательский Hook
const { createTask, error } = useTasks();
// Отобразить сообщение об ошибке
const renderError = () => {
if (!error) return null;
return <div className="app-error">{error}</div>;
};
return (
<div className="app">
<header className="app-header">
<h1>Система управления задачами на TypeScript</h1>
<p>Комплексный практический проект</p>
</header>
{renderError()}
<main className="app-main">
<TaskForm onSubmit={createTask} />
<TaskList />
</main>
<footer className="app-footer">
<p>Работает на TypeScript + React</p>
</footer>
</div>
);
};
export default App;
Композиция компонентов:Создавайте сложный интерфейс, комбинируя простые компоненты.
Конфигурация проекта
Конфигурация TypeScript и сборки проекта.
tsconfig.json
"compilerOptions": {
"target": "ES2020",
"useDefineForClassFields": true,
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"skipLibCheck": true,
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "react-jsx",
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true
},
"include": ["src"],
"references": [{ "path": "./tsconfig.node.json" }]
}
Строгий режим:Включите strict для наиболее полной проверки типов.
Примечания
- Сначала типы:Сначала определите типы, затем пишите код реализации.
- Interface vs type:Используйте интерфейсы для объектных типов, псевдонимы типов — для union-типов.
- Слоистая архитектура:Организуйте типы, сервисы и компоненты по слоям.
- Инкапсуляция хуков:Инкапсулируйте бизнес-логику в хуках.
Лучшие практики:Определения типов — основа проекта на TypeScript; проектируйте их тщательно.
Итог
В ходе этого комплексного проекта мы отработали ключевые концепции TypeScript.
- Определения типов:Интерфейсы, такие как Task, CreateTaskInput, TaskFilter.
- Слой сервисов:TaskService инкапсулирует бизнес-логику.
- Пользовательские хуки:useTasks управляет состоянием.
- Компоненты React:Типобезопасная разработка компонентов.
- Конфигурация проекта:Строгая конфигурация TypeScript.
Другие расширенияСоветы:Участвуйте в большем количестве реальных проектов, чтобы углубить понимание TypeScript на практике.