Конвертеры данных (DTO -> Model)

Руководство по разделению контрактов API и внутренним моделям данных приложения с помощью маппингов (DTO -> Domain Model).

Архитектура маппинга данных

Преимущества: Конвертеры изолируют UI от изменений на бэкенде, позволяют форматировать данные (даты, перечисления) и гарантируют типобезопасность на уровне слоев.

Структура файлов конвертеров сущности

Соглашения о наименовании

Конвертеры:
Располагаются в папке converters. Файлы называются по шаблону [entity-name].converters.ts. Используют типы из соседней папки для трансформации данных.
Типы и Интерфейсы:
Располагаются в папке types. Обязательно разделение на *.backend.interface.ts (сырые DTO) и *.interface.ts (модели для UI). Все типы экспортируются через index.ts.

01Маппинг в Frontend (Domain Model)

Преобразование сырых данных бэкенда (snake_case, строки вместо дат) в camelCase и типизированные объекты для UI. mapToFrontend — самый важный этап.

converters/booking-order.converters.ts

import { formatDate } from "@/shared/lib/utils";
import { type IEntityBackend, type IEntity } from "../types";

export const mapEntityToFrontend = (
	data: IEntityBackend
): IEntity => ({
	id: data.id,
	fullName: data.full_name,
	dateCreated: formatDate(data.created_at),
	status: data.status_code
});

02Маппинг в Backend (DTO)

Подготовка данных перед отправкой. Используется при создании или обновлении сущностей для возврата к формату DTO, ожидаемому API.

converters/booking-order.converters.ts

import { 
    type IEntityBackend, 
    type IEntity 
} from "../types";

export const mapEntityToBackend = (
	data: Partial<IEntity>
): Partial<IEntityBackend> => ({
	id: data.id,
	full_name: data.fullName,
	created_at: data.dateCreated,
	status_code: data.status
});

03Конвертация фильтров

Особый случай маппинга стейта поисковых фильтров в query-параметры. Позволяет удобно объединять массивы, обрабатывать пустые значения и специфичные форматы API.

converters/booking-order.converters.ts

import { type IEntityFilters } from "../types";

export const mapEntityFiltersToBackend = (
	filters: IEntityFilters
) => ({
	page: filters.page,
	limit: filters.limit,
	search: filters.search || undefined,
	status: filters.status.length > 0 
        ? filters.status.join(",") 
        : undefined
});

04Интеграция с RTK Query

Конвертеры внедряются прямо в описание эндпоинтов: transformResponse для получения данных и query (params/body) для отправки.

api/[entity-name].service.ts

import { authApi } from "@/entities/auth/api/auth.api";
import { 
    mapEntityFiltersToBackend, 
    mapEntityPaginatedToFrontend,
    mapEntityToBackend
} from "../converters";

export const entityApi = authApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<TResponse, TFilters>({
			query: (filters) => ({
				url: "/entity/list",
				params: mapEntityFiltersToBackend(filters)
			}),
			transformResponse: (response: TResponseBackend) => 
                mapEntityPaginatedToFrontend(response)
		}),
        updateEntity: builder.mutation<void, TEntity>({
			query: (body) => ({
				url: "/entity/update",
				method: "POST",
				body: mapEntityToBackend(body)
			})
		})
	})
});

01Маппинг в Frontend (Domain Model)

converters/booking-order.converters.ts

import { formatDate } from "@/shared/lib/utils";
import { type IEntityBackend, type IEntity } from "../types";

export const mapEntityToFrontend = (
	data: IEntityBackend
): IEntity => ({
	id: data.id,
	fullName: data.full_name,
	dateCreated: formatDate(data.created_at),
	status: data.status_code
});

02Маппинг в Backend (DTO)

converters/booking-order.converters.ts

import { 
    type IEntityBackend, 
    type IEntity 
} from "../types";

export const mapEntityToBackend = (
	data: Partial<IEntity>
): Partial<IEntityBackend> => ({
	id: data.id,
	full_name: data.fullName,
	created_at: data.dateCreated,
	status_code: data.status
});

03Конвертация фильтров

converters/booking-order.converters.ts

import { type IEntityFilters } from "../types";

export const mapEntityFiltersToBackend = (
	filters: IEntityFilters
) => ({
	page: filters.page,
	limit: filters.limit,
	search: filters.search || undefined,
	status: filters.status.length > 0 
        ? filters.status.join(",") 
        : undefined
});

04Интеграция с RTK Query

api/[entity-name].service.ts

import { authApi } from "@/entities/auth/api/auth.api";
import { 
    mapEntityFiltersToBackend, 
    mapEntityPaginatedToFrontend,
    mapEntityToBackend
} from "../converters";

export const entityApi = authApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<TResponse, TFilters>({
			query: (filters) => ({
				url: "/entity/list",
				params: mapEntityFiltersToBackend(filters)
			}),
			transformResponse: (response: TResponseBackend) => 
                mapEntityPaginatedToFrontend(response)
		}),
        updateEntity: builder.mutation<void, TEntity>({
			query: (body) => ({
				url: "/entity/update",
				method: "POST",
				body: mapEntityToBackend(body)
			})
		})
	})
});