DTO и маппинг: не пускаем внешний мир в домен
DTO и маппинг: не пускаем внешний мир в домен
В гексагональной архитектуре у слоёв могут быть свои модели данных:
HTTP handler оперирует JSON-структурами, база данных - строками таблиц,
а домен - entity и value objects. Чем сущность отличается от объекта-значения
и почему Email в домене лучше не держать обычной строкой - в уроке
Entity и Value Object. DTO (Data Transfer
Object) - структуры-переносчики, которые преобразуют данные между слоями.
ℹ️ Сколько моделей заводить - решение, а не правило
«Каждый слой работает со своими моделями» звучит как закон, но это компромисс, и у него есть обе стороны.
Разделять стоит там, где границы меняются по разным причинам. Формат ответа API - это контракт с клиентом: его нельзя ломать при рефакторинге домена, а домен нельзя подстраивать под удобство JSON. Именно поэтому отдавать доменные типы наружу опасно: переименовал поле в сущности - сломал мобильное приложение.
Не разделять имеет смысл, пока модели действительно совпадают: в простом CRUD три одинаковых структуры с маппингом между ними дают не изоляцию, а три места правки при добавлении одного поля.
Практический порядок: начинать с минимума и разделять по факту расхождения - когда в ответе API понадобилось поле, которого нет в домене, или наоборот. Первое разделение почти всегда полезное - между доменом и внешним контрактом; отдельная модель для базы нужна реже, и появляется, когда схема хранения перестаёт совпадать с моделью.
Три модели для одной сущности
Рассмотрим пользователя. У него три представления:
// 1. HTTP Request DTO - то, что приходит от клиента
type CreateUserRequest struct {
Email string `json:"email"`
Name string `json:"name"`
Password string `json:"password"`
}
// 2. Domain Model - ядро бизнес-логики
type User struct {
ID int64
Email string
Name string
PasswordHash string
CreatedAt time.Time
IsActive bool
}
// 3. HTTP Response DTO - то, что уходит клиенту
type UserResponse struct {
ID int64 `json:"id"`
Email string `json:"email"`
Name string `json:"name"`
CreatedAt string `json:"created_at"`
}
<?php
// src/UserInterface/Http/Dto/CreateUserRequest.php
// 1. HTTP Request DTO - то, что приходит от клиента
declare(strict_types=1);
namespace App\UserInterface\Http\Dto;
final readonly class CreateUserRequest
{
public function __construct(
public string $email,
public string $name,
public string $password,
) {}
}
<?php
// src/Domain/User/User.php
// 2. Domain Model - ядро бизнес-логики
declare(strict_types=1);
namespace App\Domain\User;
use DateTimeImmutable;
final class User
{
public function __construct(
private readonly int $id,
private readonly string $email,
private readonly string $name,
private readonly string $passwordHash,
private readonly DateTimeImmutable $createdAt,
private bool $isActive,
) {}
public function id(): int { return $this->id; }
public function email(): string { return $this->email; }
public function name(): string { return $this->name; }
public function passwordHash(): string { return $this->passwordHash; }
public function createdAt(): DateTimeImmutable { return $this->createdAt; }
public function isActive(): bool { return $this->isActive; }
}
<?php
// src/UserInterface/Http/Dto/UserResponse.php
// 3. HTTP Response DTO - то, что уходит клиенту
declare(strict_types=1);
namespace App\UserInterface\Http\Dto;
final readonly class UserResponse
{
public function __construct(
public int $id,
public string $email,
public string $name,
public string $createdAt,
) {}
}
# DTO - dataclass: ключи JSON берутся из имён полей через asdict().
# В FastAPI/Django на этом месте pydantic-модель или Serializer.
from dataclasses import dataclass
from datetime import datetime
# 1. HTTP Request DTO - то, что приходит от клиента
@dataclass(frozen=True, slots=True)
class CreateUserRequest:
email: str
name: str
password: str
# 2. Domain Model - ядро бизнес-логики
@dataclass
class User:
id: int
email: str
name: str
password_hash: str
created_at: datetime
is_active: bool
# 3. HTTP Response DTO - то, что уходит клиенту
@dataclass(frozen=True, slots=True)
class UserResponse:
id: int
email: str
name: str
created_at: str
Обрати внимание на различия:
- Request содержит
Password(открытый текст), домен хранитPasswordHash - Домен содержит
IsActive, но в response это поле не отдаётся - Response форматирует
CreatedAtкак строку, домен хранитtime.Time
🚫 Почему нельзя вернуть domain.User напрямую
Если использовать
domain.Userкак JSON-ответ, клиент получит хеш пароля и флаг активности (в Go без json-тегов - под ключамиPasswordHashиIsActive). Это утечка внутренних деталей и потенциальная проблема безопасности. DTO - это фильтр между доменом и внешним миром.
Поток данных: Request → Domain → Response
Полный цикл обработки HTTP-запроса выглядит так:
Функции маппинга
Маппинг - это преобразование одной структуры в другую. В Go это обычные функции, в PHP - статические методы-фабрики на DTO или отдельный mapper-сервис:
// adapters/http/mapper.go
package http
import (
"time"
"myapp/internal/domain"
)
// toDomain преобразует HTTP-запрос в доменную модель
func toDomainUser(req CreateUserRequest, passwordHash string) *domain.User {
return &domain.User{
Email: req.Email,
Name: req.Name,
PasswordHash: passwordHash,
CreatedAt: time.Now().UTC(),
IsActive: true,
}
}
// toResponse преобразует доменную модель в HTTP-ответ
func toUserResponse(u *domain.User) UserResponse {
return UserResponse{
ID: u.ID,
Email: u.Email,
Name: u.Name,
CreatedAt: u.CreatedAt.Format(time.RFC3339),
}
}
// toListResponse - для списков
func toUserListResponse(users []*domain.User) []UserResponse {
result := make([]UserResponse, 0, len(users))
for _, u := range users {
result = append(result, toUserResponse(u))
}
return result
}
<?php
// src/UserInterface/Http/Mapper/UserMapper.php
declare(strict_types=1);
namespace App\UserInterface\Http\Mapper;
use App\Domain\User\User;
use App\UserInterface\Http\Dto\CreateUserRequest;
use App\UserInterface\Http\Dto\UserResponse;
use DateTimeImmutable;
use DateTimeInterface;
final class UserMapper
{
// toDomain преобразует HTTP-запрос в доменную модель
public static function toDomain(CreateUserRequest $req, string $passwordHash): User
{
return new User(
id: 0,
email: $req->email,
name: $req->name,
passwordHash: $passwordHash,
createdAt: new DateTimeImmutable(),
isActive: true,
);
}
// toResponse преобразует доменную модель в HTTP-ответ
public static function toResponse(User $u): UserResponse
{
return new UserResponse(
id: $u->id(),
email: $u->email(),
name: $u->name(),
createdAt: $u->createdAt()->format(DateTimeInterface::RFC3339),
);
}
/**
* toListResponse - для списков
*
* @param User[] $users
* @return UserResponse[]
*/
public static function toListResponse(array $users): array
{
return array_map(fn (User $u): UserResponse => self::toResponse($u), $users);
}
}
В Symfony эту же задачу решает Serializer с #[Groups] - помечаешь поля, какие сериализуются для запроса, какие для ответа, и нормализатор делает маппинг автоматически. Начиная с Symfony 7.3 есть и отдельный компонент ObjectMapper с атрибутом #[Map], который перекладывает данные между DTO и объектами. Mapper-классы остаются полезны, когда у DTO и Domain объекта разные имена полей или нужны вычисляемые поля.
# adapters/http/mapper.py
from datetime import datetime, timezone
from myapp.domain import User
from .dto import CreateUserRequest, UserResponse
# to_domain преобразует HTTP-запрос в доменную модель
def to_domain_user(req: CreateUserRequest, password_hash: str) -> User:
return User(
id=0,
email=req.email,
name=req.name,
password_hash=password_hash,
created_at=datetime.now(timezone.utc),
is_active=True,
)
# to_response преобразует доменную модель в HTTP-ответ
# (isoformat() у aware datetime даёт строку в формате RFC 3339)
def to_user_response(u: User) -> UserResponse:
return UserResponse(
id=u.id,
email=u.email,
name=u.name,
created_at=u.created_at.isoformat(),
)
# to_list_response - для списков
def to_user_list_response(users: list[User]) -> list[UserResponse]:
return [to_user_response(u) for u in users]
Handler использует эти функции для преобразования. Обрати внимание на границу: DTO живёт только внутри адаптера, а дальше в use-case уходит его собственная Input-структура - зачем сценарию отдельный вход, разобрано в уроке Use Case: сценарии вместо «толстых сервисов»:
func (h *RegisterHandler) Handle(w http.ResponseWriter, r *http.Request) {
// 1. Декодируем JSON в Request DTO
var req CreateUserRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
respondError(w, http.StatusBadRequest, "invalid json")
return
}
// 2. Вызываем use-case (передаём Input, не DTO и не *http.Request)
out, err := h.registerUC.Execute(r.Context(), usecase.RegisterInput{
Email: req.Email,
Name: req.Name,
Password: req.Password,
})
if err != nil {
handleError(w, err)
return
}
// 3. Маппим результат в Response DTO
resp := toUserResponse(out.User)
respondJSON(w, http.StatusCreated, resp)
}
<?php
// src/UserInterface/Http/Controller/RegisterController.php
declare(strict_types=1);
namespace App\UserInterface\Http\Controller;
use App\Application\UseCase\RegisterInput;
use App\Application\UseCase\RegisterUseCase;
use App\UserInterface\Http\Dto\CreateUserRequest;
use App\UserInterface\Http\Mapper\UserMapper;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Serializer\SerializerInterface;
final class RegisterController
{
public function __construct(
private readonly RegisterUseCase $registerUC,
private readonly SerializerInterface $serializer,
) {}
public function __invoke(Request $request): JsonResponse
{
// 1. Декодируем JSON в Request DTO
$req = $this->serializer->deserialize(
$request->getContent(),
CreateUserRequest::class,
'json',
);
// 2. Вызываем use-case (передаём Input, не DTO и не Request)
$out = $this->registerUC->execute(new RegisterInput(
email: $req->email,
name: $req->name,
password: $req->password,
));
// 3. Маппим результат в Response DTO
$resp = UserMapper::toResponse($out->user);
return new JsonResponse($resp, Response::HTTP_CREATED);
}
}
# Фреймворк-независимый handler; в FastAPI это endpoint,
# где CreateUserRequest приходит уже разобранным параметром
class RegisterHandler:
def __init__(self, register_uc: RegisterUser) -> None:
self._register_uc = register_uc
def handle(self, request: Request) -> Response:
# 1. Декодируем JSON в Request DTO
try:
req = CreateUserRequest(**json.loads(request.body))
except (json.JSONDecodeError, TypeError): # TypeError - лишние/недостающие поля
return respond_error(400, "invalid json")
# 2. Вызываем use-case (передаём Input, не DTO и не Request)
try:
out = self._register_uc.execute(RegisterInput(
email=req.email,
name=req.name,
password=req.password,
))
except Exception as e:
return handle_error(e)
# 3. Маппим результат в Response DTO
resp = to_user_response(out.user)
return respond_json(201, asdict(resp))
⚠️ Не передавай *http.Request в use-case
Use-case не должен знать о HTTP. Если ты передаёшь
*http.Requestилиhttp.ResponseWriterза пределы handler - ты нарушаешь границу слоёв. Use-case принимает свою Input-структуру с примитивными типами.
Где именно проходит эта граница и что ещё остаётся на стороне адаптера - парсинг, статусы, middleware - разбирается в уроке HTTP адаптер.
Разбор и нормализация на границе
Из формы или query-строки всё приходит строками, часто с лишними пробелами и в разном регистре. Работу на границе удобно разделить на две части:
- адаптер приводит тип и формат: обрезает пробелы, парсит число, приводит email к нижнему регистру. Строка «abc» вместо возраста - ошибка формата, клиенту уходит 400;
- домен проверяет правила: «возраст от 1 до 150», «в email есть
@» - это знание о бизнесе, его держит доменный конструктор, и обойти его из другого адаптера (CLI, очередь) нельзя.
Маппер склеивает обе части: нормализует сырые поля и передаёт их в доменный конструктор.
// domain/user.go - правило живёт в домене
func NewUser(name string, age int) (User, error) {
if name == "" {
return User{}, ErrEmptyName
}
if age < 1 || age > 150 {
return User{}, ErrInvalidAge
}
return User{name: name, age: age}, nil
}
// adapters/http/mapper.go - адаптер приводит тип и формат
func toDomainUser(dto UserForm) (domain.User, error) {
age, err := strconv.Atoi(strings.TrimSpace(dto.Age))
if err != nil {
return domain.User{}, fmt.Errorf("age is not a number: %q", dto.Age)
}
return domain.NewUser(strings.TrimSpace(dto.Name), age)
}
<?php
declare(strict_types=1);
// src/Domain/User/User.php - правило живёт в домене
final class User
{
private function __construct(public readonly string $name, public readonly int $age) {}
public static function create(string $name, int $age): self
{
if ($name === '') {
throw new DomainException('empty name');
}
if ($age < 1 || $age > 150) {
throw new DomainException('invalid age');
}
return new self($name, $age);
}
}
// src/UserInterface/Http/Mapper/UserFormMapper.php - адаптер приводит тип и формат
final class UserFormMapper
{
public static function toDomain(UserForm $dto): User
{
$age = filter_var(trim($dto->age), FILTER_VALIDATE_INT);
if ($age === false) {
throw new InvalidArgumentException('age is not a number');
}
return User::create(trim($dto->name), $age);
}
}
# domain/user.py - правило живёт в домене
@dataclass(frozen=True)
class User:
name: str
age: int
def __post_init__(self) -> None:
if not self.name:
raise EmptyNameError()
if not 1 <= self.age <= 150:
raise InvalidAgeError(self.age)
# adapters/http/mapper.py - адаптер приводит тип и формат
def to_domain_user(dto: UserForm) -> User:
try:
age = int(dto.age.strip())
except ValueError:
raise BadRequestError(f"age is not a number: {dto.age!r}") from None
return User(name=dto.name.strip(), age=age)
Если доменного конструктора пока нет (как в коротком упражнении к уроку), маппер делает обе части сам - главное, чтобы непроверенные данные не прошли дальше границы.
DB-модели: ещё один слой маппинга
Помимо HTTP DTO, существуют модели базы данных. Если ты используешь GORM или sqlx (Go), Doctrine ORM или DBAL (PHP), у тебя наверняка есть struct/класс с тегами db: или #[Column]:
// adapters/postgres/model.go
package postgres
import (
"time"
"myapp/internal/domain"
)
type userRow struct {
ID int64 `db:"id"`
Email string `db:"email"`
Name string `db:"name"`
PasswordHash string `db:"password_hash"`
IsActive bool `db:"is_active"`
CreatedAt time.Time `db:"created_at"`
UpdatedAt time.Time `db:"updated_at"`
}
func toUserRow(u *domain.User) userRow {
return userRow{
ID: u.ID,
Email: u.Email,
Name: u.Name,
PasswordHash: u.PasswordHash,
IsActive: u.IsActive,
CreatedAt: u.CreatedAt,
UpdatedAt: time.Now(),
}
}
func (r userRow) toDomain() *domain.User {
return &domain.User{
ID: r.ID,
Email: r.Email,
Name: r.Name,
PasswordHash: r.PasswordHash,
IsActive: r.IsActive,
CreatedAt: r.CreatedAt,
}
}
<?php
// src/Infrastructure/Persistence/Doctrine/UserRow.php
declare(strict_types=1);
namespace App\Infrastructure\Persistence\Doctrine;
use App\Domain\User\User;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
use DateTimeImmutable;
#[ORM\Entity]
#[ORM\Table(name: 'users')]
final class UserRow
{
#[ORM\Id]
#[ORM\Column(name: 'id', type: Types::BIGINT)]
public int $id = 0;
#[ORM\Column(name: 'email', type: Types::STRING)]
public string $email = '';
#[ORM\Column(name: 'name', type: Types::STRING)]
public string $name = '';
#[ORM\Column(name: 'password_hash', type: Types::STRING)]
public string $passwordHash = '';
#[ORM\Column(name: 'is_active', type: Types::BOOLEAN)]
public bool $isActive = true;
#[ORM\Column(name: 'created_at', type: Types::DATETIME_IMMUTABLE)]
public DateTimeImmutable $createdAt;
#[ORM\Column(name: 'updated_at', type: Types::DATETIME_IMMUTABLE)]
public DateTimeImmutable $updatedAt;
}
// src/Infrastructure/Persistence/Doctrine/UserRowMapper.php
final class UserRowMapper
{
public static function fromDomain(User $u): UserRow
{
$row = new UserRow();
$row->id = $u->id();
$row->email = $u->email();
$row->name = $u->name();
$row->passwordHash = $u->passwordHash();
$row->isActive = $u->isActive();
$row->createdAt = $u->createdAt();
$row->updatedAt = new DateTimeImmutable();
return $row;
}
public static function toDomain(UserRow $row): User
{
return new User(
id: $row->id,
email: $row->email,
name: $row->name,
passwordHash: $row->passwordHash,
createdAt: $row->createdAt,
isActive: $row->isActive,
);
}
}
# adapters/postgres/model.py
# Имена полей совпадают с колонками: psycopg с row_factory=class_row(UserRow)
# соберёт строку сам. В SQLAlchemy это модель с Column(...) на том же месте.
from dataclasses import dataclass
from datetime import datetime, timezone
from myapp.domain import User
@dataclass(slots=True)
class UserRow:
id: int
email: str
name: str
password_hash: str
is_active: bool
created_at: datetime
updated_at: datetime
def to_domain(self) -> User:
return User(
id=self.id,
email=self.email,
name=self.name,
password_hash=self.password_hash,
is_active=self.is_active,
created_at=self.created_at,
)
def to_user_row(u: User) -> UserRow:
return UserRow(
id=u.id,
email=u.email,
name=u.name,
password_hash=u.password_hash,
is_active=u.is_active,
created_at=u.created_at,
updated_at=datetime.now(timezone.utc),
)
Собирает и разбирает эту строку сам адаптер репозитория: наружу он обязан отдать domain.User, а не userRow, иначе тип из базы протечёт в сценарий. Контракт такого порта и правило «никаких *sql.Rows в сигнатуре» - в уроке Репозитории и интерфейсы.
Зачем отдельные DB-модели? Потому что:
- Доменная модель не должна зависеть от ORM-тегов (
gorm:"column:...") - Имена полей в БД (
password_hash) могут отличаться от имён в домене - В БД могут быть поля (
updated_at), которых нет в домене - При смене ORM или переходе на raw SQL меняется только адаптер
ℹ️ Когда DB-модель = доменная модель
В простых CRUD-сервисах (3-5 полей, никакой бизнес-логики) отдельные DB-модели - лишний код. Если доменная модель = строка таблицы один-в-один, можно добавить
db:теги прямо на доменную структуру. Но как только появляются различия - разделяй.
Полная картина: 4 модели
В полноценном hex-приложении данные проходят через 4 структуры. Это выглядит как много кода. Но каждая структура существует по конкретной причине и защищает границу между слоями.
Когда маппинг избыточен
Не каждому проекту нужны 4 слоя моделей:
- Микросервис с 2-3 эндпоинтами - можно обойтись без отдельных DB-моделей
- Внутренний инструмент без публичного API - Request DTO может совпадать с Input
- Прототип - используй доменную модель везде, разделишь когда стабилизируется
Начинай с минимума и добавляй слои, когда появляется реальная необходимость: поля начинают расходиться, тесты становятся хрупкими, или утекают внутренние данные.
Обратный случай тоже бывает: если ответ для экрана собирается из нескольких таблиц и на доменную модель уже совсем не похож, дешевле не плодить мапперы, а завести отдельную модель для чтения, которая ходит в базу своим запросом. Этот приём описан в уроке Repositories в DDD.
Мини-задание
- Выбери один endpoint в своём проекте и создай для него Request DTO и Response DTO
- Напиши функции
toDomain()иtoResponse()для маппинга - Убедись, что handler не передаёт
*http.Requestв use-case - Проверь: не утекают ли чувствительные поля (пароль, внутренние флаги) в JSON-ответ?