Комплексная практика проекта на TypeScript

В этом руководстве на примере полного проекта комплексно применяются различные возможности TypeScript.

От настройки проекта до фактической разработки — оно полностью демонстрирует применение TypeScript в реальных проектах.


SVG-диаграмма: архитектура проекта Background Title Project Practice: Task Management System Frontend Frontend (React + TS) Vite + React 18 Components + Hooks Type-safe UI Arrow Backend Backend (Node.js) Express + TS RESTful API Type Definitions Arrow Data Data Storage In-Memory (Demo) Lower Section: Features Project Features Feature 1 Task CRUD Operations Feature 2 Type-safe API Feature 3 State Management Arrow Marker

Зачем нужна комплексная практика проекта?

После изучения синтаксиса TypeScript вам нужно закрепить знания на реальных проектах.

В этом руководстве демонстрируется полная система управления задачами, охватывающая фронтенд, бэкенд и определения типов.

На этом проекте вы сможете освоить лучшие практики TypeScript в реальной разработке.

Цели проекта:Создать систему управления задачами с возможностями создания, запроса, обновления и удаления задач.


Структура проекта

Организовать структуру проекта в стиле Monorepo.

Структура каталогов

task-manager/
├── 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.

< h2 class="example">src/types/api.ts
// Обобщённый тип ответа 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();

Сервисный слой:Бизнес-логика централизована в сервисном слое для удобства тестирования и поддержки.


Пользовательский хук

Используйте хук для управления состоянием задачи.

< h2 class="example">src/hooks/useTasks.ts
// Импорт хуков React и типов
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

// Импорт React и пользовательского хука
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

// Импорт React и типов
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 на практике.

Другие расширения