DTO и маппинг: почему нельзя отдавать сущности наружу

Сущность БД и объект API — разные вещи. DTO (Data Transfer Object) — это «лицо» данных для клиента, отделённое от внутренней модели.

Суть: не возвращайте @Entity напрямую в JSON. Заведите DTO — отдельный объект для передачи данных. Это защищает от утечек, ленивых исключений и жёсткой связи API с базой.

Соблазн велик: сущность уже есть, у неё все поля — почему бы не отдать её клиенту как JSON? Но это одна из самых частых ошибок в Spring Boot. Сущность принадлежит слою данных, а API — отдельный контракт. Смешивать их опасно.

Чем плох возврат сущности

• Утечка данных. В сущности User есть passwordHash, внутренние флаги, аудит-поля. Отдав сущность, вы рискуете слить их клиенту.
• LazyInitializationException. Сериализатор обратится к LAZY-связи вне транзакции — и получит исключение или лавину запросов.
• Жёсткая связь. Переименовали колонку в базе — сломали контракт API. DTO разрывает эту связь.

DTO на record

В современной Java DTO удобно делать неизменяемой записью (record):

// Что уходит клиенту — без пароля и внутренних полей
public record UserResponse(Long id, String name, String email) { }

// Что приходит от клиента — только нужное для создания
public record CreateUserRequest(String name, String email, String password) { }

Маппинг entity ↔ DTO

@Service
public class UserService {

    public UserResponse toResponse(User entity) {
        return new UserResponse(
            entity.getId(),
            entity.getName(),
            entity.getEmail()
            // passwordHash НЕ попадает в ответ
        );
    }
}

Как работает под капотом

Маппинг — это явное копирование нужных полей из одного объекта в другой. Сущность остаётся в слое данных, наружу уходит DTO. Контроллер принимает DTO запроса, сервис превращает его в сущность, сохраняет, а на выходе формирует DTO ответа.

  Клиент --JSON--> CreateUserRequest (DTO входа)
        |
        v
  Service: DTO -> Entity (маппинг)
        |
        v
  Repository: сохраняет Entity в БД
        |
        v
  Service: Entity -> UserResponse (DTO выхода)
        |
        v
  Контроллер --JSON--> Клиент (без пароля и внутренних полей)

Смоделируем маппинг с фильтрацией приватных полей:

# Маппинг Entity -> DTO: наружу только разрешённые поля
def to_response_dto(entity):
    # entity содержит секреты, DTO — нет
    return {
        "id": entity["id"],
        "name": entity["name"],
        "email": entity["email"],
        # password_hash и internal_flag НЕ копируем
    }

user_entity = {
    "id": 7,
    "name": "Анна",
    "email": "[email protected]",
    "password_hash": "$2a$10$secrethash",
    "internal_flag": True,
}

dto = to_response_dto(user_entity)
print("Уходит клиенту:", dto)
print("Утёк ли пароль?", "password_hash" in dto)   # False

Нажмите «Попробуй сам ▶»: DTO отдаёт клиенту только публичные поля, секреты остаются в сущности.

Частые ошибки

• Возврат @Entity из контроллера. Главный антипаттерн — ведёт к утечкам и ленивым исключениям.
• Один DTO на вход и выход. Запрос и ответ разные: на входе пароль нужен, на выходе — нет. Делайте отдельные.
• Логика маппинга в контроллере. Преобразование лучше держать в сервисе или отдельном мапере.

Best practices

• Заводите отдельные DTO для запроса и ответа; используйте record для неизменяемости.
• Никогда не отдавайте сущности напрямую в JSON.
• Для крупных проектов автоматизируйте маппинг (например, MapStruct), но понимайте, что он делает.

Итог: DTO — это контракт API, отделённый от модели БД. Он защищает от утечек, ленивых исключений и жёсткой связи. Сущность остаётся внутри, наружу уходит аккуратный объект передачи данных.

Закрепим главное

DTO — это граница между внутренним устройством приложения и внешним контрактом. Сущность принадлежит слою данных и меняется вместе со схемой базы; DTO принадлежит API и меняется вместе с потребностями клиента. Разделив их, вы получаете свободу эволюционировать базу, не ломая клиентов, и наоборот. Это одно из самых важных архитектурных решений в типичном Spring Boot приложении.

Запомните три конкретные причины никогда не отдавать сущность наружу, потому что каждая встречается в реальных проектах. Первая — утечка приватных полей: пароль-хеш, внутренние флаги и аудит-данные не должны попадать клиенту. Вторая — LazyInitializationException: сериализатор обращается к ленивой связи уже вне транзакции и роняет запрос или порождает лавину SQL. Третья — жёсткая связь: переименование колонки в базе ломает контракт API. DTO с явным маппингом снимает все три проблемы разом, поэтому потраченные на него несколько строк кода окупаются многократно.