Best practice: DTOs vs. Entities

“Think of Entities as your database blueprints and DTOs as the polished brochures you hand out—each has its place, and mixing them up is like showing raw construction plans to customers!” 🏗️📇

🔍 What Are Entities?

• Purpose: Represent your domain model and map directly to database tables via JPA.
• Characteristics:
  • Annotated with @Entity
  • Contain persistence-specific details (e.g., @Id, @Column)
  • Often mutable (JPA requires a no-arg constructor and setters)

javaCopyEditpackage com.example.demo.model;

import jakarta.persistence.*;

@Entity
public class UserEntity {
    @Id @GeneratedValue
    private Long id;

    @Column(nullable = false, unique = true)
    private String email;

    private String password;        // stored hashed

    // JPA needs a no-arg constructor
    protected UserEntity() {}

    public UserEntity(String email, String password) {
        this.email = email;
        this.password = password;
    }

    // getters & setters...
}

🎯 What Are DTOs?

• Purpose: Carry data across process boundaries—from backend to client (or vice versa).
• Characteristics:
  • No persistence annotations
  • Often immutable—use records or final fields
  • Tailored to the API contract (omit internal fields like passwordHash)

javaCopyEditpackage com.example.demo.dto;

public record UserDto(
    Long id,
    String email
) {}

Why record? Java 16+ records are ideal for DTOs: less boilerplate, built-in immutability, and auto-generated equals/hashCode/toString.

⚖️ Why Separate Them?

🛠️ Mapping Strategies

1. Manual Mapping javaCopyEditpublic static UserDto fromEntity(UserEntity e) { return new UserDto(e.getId(), e.getEmail()); }
2. MapStruct (Compile-time codegen) javaCopyEdit@Mapper(componentModel = "spring") public interface UserMapper { UserDto toDto(UserEntity entity); UserEntity toEntity(UserDto dto); }
3. ModelMapper (Runtime) javaCopyEditModelMapper mapper = new ModelMapper(); UserDto dto = mapper.map(userEntity, UserDto.class);

Tip: Prefer MapStruct for type-safe, fast, compile-time mapping with minimal overhead.

💡 Best Practices

• Keep Entities Clean: No JSON annotations or API logic—just persistence.
• DTO Immutability: Use record or final fields + no setters.
• Validation at the Edge: Annotate your incoming DTOs with @NotNull, @Email, etc., in controller methods.
• Service Layer Converts: Do all mapping in the service layer or dedicated mapper classes—controllers stay skinny.
• Version Your DTOs: As your API evolves, maintain backward-compatible DTOs (v1.UserDto, v2.UserDto).

🐵 Monkey-Proof Challenge

1. Define a ProductEntity with fields id, name, price, and inventoryCount.
2. Create two DTOs:
   • ProductRequestDto for creating/updating (omit id).
   • ProductResponseDto for returning to clients (include id, name, price).
3. Implement a MapStruct mapper to convert between entity and both DTOs.
4. Wire it in a ProductService and expose /products POST and GET endpoints.