Что такое договор API и DTO?
На этой странице
Договор API описывает адрес, метод, входные данные, успешный ответ и возможные ошибки. DTO — объект, специально подготовленный для передачи между клиентом и сервером.
Вопрос
Что такое договор API и DTO? Почему нельзя возвращать клиенту строку таблицы как есть?
Основная идея
DTO расшифровывается как Data Transfer Object, то есть объект передачи данных.
Почему не стоит возвращать строку таблицы
В базе может храниться:
type UserRow = {
id: number;
email: string;
passwordHash: string;
isBlocked: boolean;
createdAt: Date;
};Клиенту нужна только безопасная часть:
type UserResponse = {
id: number;
email: string;
isBlocked: boolean;
createdAt: string;
};
function toUserResponse(user: UserRow): UserResponse {
return {
id: user.id,
email: user.email,
isBlocked: user.isBlocked,
createdAt: user.createdAt.toISOString(),
};
}Пример договора
POST /api/users
Тело:
{
"name": "Анна",
"email": "anna@example.com"
}
Успех: 201
{
"data": {
"id": 42,
"name": "Анна",
"email": "anna@example.com"
}
}
Ошибки:
400 VALIDATION_ERROR
409 EMAIL_ALREADY_EXISTS
500 INTERNAL_ERRORТип TypeScript не является договором во время работы
const body = request.body as CreateUserInput;as только убеждает TypeScript и ничего не проверяет. Для настоящей границы нужен Zod или другое средство проверки.
Версионирование
Для небольшого проекта не нужно начинать с нескольких версий. Если несовместимое изменение всё же требуется, распространённый вариант:
/api/v1/users
/api/v2/usersСначала попробуй добавить необязательное поле или новый маршрут без поломки старого клиента.
Документирование API
Даже короткая таблица в README полезна. В более крупном проекте договор описывают через OpenAPI, из которого можно построить интерактивную документацию и типы клиента.
Что важно помнить
- Договор описывает адрес, метод, вход, успешный ответ и возможные ошибки маршрута.
- DTO отделяет внешний формат от схемы базы: можно менять таблицу, не ломая клиента.
- Приведение
as UserDtoничего не проверяет во время работы — данные проверяет схема. - Договор удобно описывать в OpenAPI и генерировать из него документацию и типы клиента.
- Несовместимое изменение согласуют с клиентами или выпускают новую версию API.
Мини-шпаргалка
- Договор описывает вход, выход и ошибки маршрута.
- DTO отделяет внешний ответ от внутренней модели.
- Никогда не возвращай
passwordHashи другие секретные поля. - Приведение
asне проверяет сетевые данные. - Несовместимое изменение требует согласования или новой версии API.