DTO vs Entity trong Spring Boot: vì sao đừng trả Entity ra API

Một trong những quyết định thiết kế quan trọng nhất khi làm REST API với Spring là: có nên trả thẳng Entity JPA ra client không? Câu trả lời gần như luôn là không — hãy dùng DTO.

Entity và DTO khác nhau ở mục đích

• Entity: ánh xạ bảng database, phục vụ lớp lưu trữ (persistence)
• DTO (Data Transfer Object): định hình dữ liệu vào/ra API, phục vụ lớp giao tiếp

Vì sao đừng trả Entity

1. Lộ dữ liệu: Entity có thể chứa passwordHash, cờ nội bộ — dễ lỡ tay serialize ra ngoài
2. Vòng lặp JSON: quan hệ hai chiều (Order ↔ Customer) gây đệ quy vô tận khi serialize
3. Lazy loading exception: serialize ngoài transaction đụng quan hệ lazy gây LazyInitializationException
4. Ràng buộc chặt: đổi schema database làm vỡ hợp đồng API của client

Mẫu triển khai

public record UserDto(Long id, String email, String name) {
    static UserDto from(User u) {
        return new UserDto(u.getId(), u.getEmail(), u.getName());
    }
}

Với dự án lớn, dùng thư viện map (MapStruct) để tự sinh code chuyển đổi. DTO cũng là nơi lý tưởng đặt annotation validation (@NotBlank, @Email) cho input.

👉 Dùng thử công cụ liên quan trên dev-hub: JSON Formatter — chạy hoàn toàn trong trình duyệt, không gửi dữ liệu lên server.