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

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

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

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

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

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

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

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

Преобразование сырых данных бэкенда (snake_case, строки вместо дат) в camelCase и типизированные объекты для UI. Имена операций: mapEntityToFrontend / mapEntitiesToFrontend — литерал mapToFrontend запрещён.

converters/booking-order.converters.ts

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

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

/** Backend list envelope → unified { data, total } */
export const mapEntitiesToFrontend = (
	response: TEntitiesBackend
): IPaginationResponse<IEntity> => ({
	data: response.items.map(mapEntityToFrontend),
	total: response.total_count
});

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

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

converters/booking-order.converters.ts

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

export const mapEntityToBackend = (
	data: Partial<IEntity>
): Partial<TEntityBackend> => ({
	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 { IPaginationRequest } from "@/shared/types";
import type { TEntitiesQueryBackend } from "../types";

/** IPaginationRequest → API-specific query fields (names stay here) */
export const mapEntitiesQueryToBackend = (
	filters: IPaginationRequest
): TEntitiesQueryBackend => ({
	page: filters.page,
	elements_on_page: filters.limit,
	search: filters.search || undefined,
	status_code: filters.status
});

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

Конвертеры внедряются прямо в описание эндпоинтов: transformResponse для получения данных и query (params/body) для отправки. Импорт converters в pages/widgets/features запрещён — UI уже получает frontend-модели.

api/[entity-name].service.ts

import { baseApi } from "@/shared/api/backend";
import type { IPaginationRequest, IPaginationResponse } from "@/shared/types";
import {
	mapEntitiesQueryToBackend,
	mapEntitiesToFrontend,
	mapEntityToBackend
} from "../converters";
import type { TEntitiesBackend, IEntity } from "../types";

/** Only place converters are imported — never in pages/widgets/features/ui */
export const entityApi = baseApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<
			IPaginationResponse<IEntity>,
			IPaginationRequest
		>({
			query: (filters) => ({
				url: "/entity/list",
				params: mapEntitiesQueryToBackend(filters)
			}),
			transformResponse: (response: TEntitiesBackend) =>
				mapEntitiesToFrontend(response)
		}),
		updateEntity: builder.mutation<void, IEntity>({
			query: (body) => ({
				url: "/entity/update",
				method: "POST",
				body: mapEntityToBackend(body)
			})
		})
	})
});

05ESLint: converters не выходят за entity

Фиксируем через no-restricted-imports (блок @/entities/*/converters) и eslint-plugin-boundaries (импорт converters только из api/ той же сущности). Относительный ../converters из api/ разрешён.

eslint.config.js (converters isolation)

import boundaries from "eslint-plugin-boundaries";

export default [
  {
    plugins: { boundaries },
    settings: {
      "boundaries/elements": [
        {
          type: "entity-converters",
          pattern: "src/entities/*/converters/**",
          capture: ["entity"]
        },
        {
          type: "entity-api",
          pattern: "src/entities/*/api/**",
          capture: ["entity"]
        },
        { type: "pages", pattern: "src/pages/**" },
        { type: "widgets", pattern: "src/widgets/**" },
        { type: "features", pattern: "src/features/**" },
        { type: "entities", pattern: "src/entities/**" },
        { type: "shared", pattern: "src/shared/**" }
      ],
      "boundaries/ignore": ["**/*.{test,spec}.{ts,tsx}"]
    },
    rules: {
      // 1) Block public/alias imports of converters (api uses relative ../converters)
      "no-restricted-imports": [
        "error",
        {
          patterns: [
            {
              group: [
                "**/entities/*/converters",
                "**/entities/*/converters/**",
                "@/entities/*/converters",
                "@/entities/*/converters/**"
              ],
              message:
                "Converters are private to the entity. Import only from entities/<name>/api via relative '../converters'. UI must use frontend models from RTK hooks."
            }
          ]
        }
      ],
      // 2) Only same-entity api may depend on converters segment
      "boundaries/element-types": [
        "error",
        {
          default: "disallow",
          rules: [
            {
              from: { type: "entity-api", capture: ["entity"] },
              allow: [
                { type: "entity-converters", capture: ["entity"] },
                "entities",
                "shared"
              ]
            },
            {
              from: "entity-converters",
              allow: ["entities", "shared"]
            },
            {
              from: "pages",
              allow: ["widgets", "features", "entities", "shared"]
            },
            {
              from: "widgets",
              allow: ["features", "entities", "shared"]
            },
            {
              from: "features",
              allow: ["entities", "shared", "features"]
            },
            {
              from: "entities",
              allow: ["entities", "shared"]
            },
            {
              from: "shared",
              allow: ["shared", "entities"]
            }
          ]
        }
      ],
      "boundaries/no-private": "error"
    }
  }
];

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

converters/booking-order.converters.ts

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

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

/** Backend list envelope → unified { data, total } */
export const mapEntitiesToFrontend = (
	response: TEntitiesBackend
): IPaginationResponse<IEntity> => ({
	data: response.items.map(mapEntityToFrontend),
	total: response.total_count
});

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

converters/booking-order.converters.ts

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

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

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

converters/booking-order.converters.ts

import type { IPaginationRequest } from "@/shared/types";
import type { TEntitiesQueryBackend } from "../types";

/** IPaginationRequest → API-specific query fields (names stay here) */
export const mapEntitiesQueryToBackend = (
	filters: IPaginationRequest
): TEntitiesQueryBackend => ({
	page: filters.page,
	elements_on_page: filters.limit,
	search: filters.search || undefined,
	status_code: filters.status
});

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

api/[entity-name].service.ts

import { baseApi } from "@/shared/api/backend";
import type { IPaginationRequest, IPaginationResponse } from "@/shared/types";
import {
	mapEntitiesQueryToBackend,
	mapEntitiesToFrontend,
	mapEntityToBackend
} from "../converters";
import type { TEntitiesBackend, IEntity } from "../types";

/** Only place converters are imported — never in pages/widgets/features/ui */
export const entityApi = baseApi.injectEndpoints({
	endpoints: (builder) => ({
		getEntities: builder.query<
			IPaginationResponse<IEntity>,
			IPaginationRequest
		>({
			query: (filters) => ({
				url: "/entity/list",
				params: mapEntitiesQueryToBackend(filters)
			}),
			transformResponse: (response: TEntitiesBackend) =>
				mapEntitiesToFrontend(response)
		}),
		updateEntity: builder.mutation<void, IEntity>({
			query: (body) => ({
				url: "/entity/update",
				method: "POST",
				body: mapEntityToBackend(body)
			})
		})
	})
});

05ESLint: converters не выходят за entity

eslint.config.js (converters isolation)

import boundaries from "eslint-plugin-boundaries";

export default [
  {
    plugins: { boundaries },
    settings: {
      "boundaries/elements": [
        {
          type: "entity-converters",
          pattern: "src/entities/*/converters/**",
          capture: ["entity"]
        },
        {
          type: "entity-api",
          pattern: "src/entities/*/api/**",
          capture: ["entity"]
        },
        { type: "pages", pattern: "src/pages/**" },
        { type: "widgets", pattern: "src/widgets/**" },
        { type: "features", pattern: "src/features/**" },
        { type: "entities", pattern: "src/entities/**" },
        { type: "shared", pattern: "src/shared/**" }
      ],
      "boundaries/ignore": ["**/*.{test,spec}.{ts,tsx}"]
    },
    rules: {
      // 1) Block public/alias imports of converters (api uses relative ../converters)
      "no-restricted-imports": [
        "error",
        {
          patterns: [
            {
              group: [
                "**/entities/*/converters",
                "**/entities/*/converters/**",
                "@/entities/*/converters",
                "@/entities/*/converters/**"
              ],
              message:
                "Converters are private to the entity. Import only from entities/<name>/api via relative '../converters'. UI must use frontend models from RTK hooks."
            }
          ]
        }
      ],
      // 2) Only same-entity api may depend on converters segment
      "boundaries/element-types": [
        "error",
        {
          default: "disallow",
          rules: [
            {
              from: { type: "entity-api", capture: ["entity"] },
              allow: [
                { type: "entity-converters", capture: ["entity"] },
                "entities",
                "shared"
              ]
            },
            {
              from: "entity-converters",
              allow: ["entities", "shared"]
            },
            {
              from: "pages",
              allow: ["widgets", "features", "entities", "shared"]
            },
            {
              from: "widgets",
              allow: ["features", "entities", "shared"]
            },
            {
              from: "features",
              allow: ["entities", "shared", "features"]
            },
            {
              from: "entities",
              allow: ["entities", "shared"]
            },
            {
              from: "shared",
              allow: ["shared", "entities"]
            }
          ]
        }
      ],
      "boundaries/no-private": "error"
    }
  }
];