The Service Layer & DTOs

The problem with fat controllers

So far our controllers did everything: read the request, run the logic, and call the database. That is fine for tiny demos, but in a real app it becomes a tangled mess — logic is hard to find, hard to reuse, and hard to test.

Professional Spring apps use a layered architecture: each layer has one job, and they call each other in a straight line.

The flow is always one direction: Controller → Service → Repository. The controller never touches the database directly; it asks the service, and the service asks the repository.

What is a DTO, and why bother?

A DTO (Data Transfer Object) is a small, plain class that carries only the fields you want to send or receive over the web — separate from your database entity. Why have two classes for what feels like the same data? Three solid reasons:

• Safety: your entity might have fields you must never expose — a password hash, internal flags. A DTO sends only the safe fields.
• Stability: you can change the database table without breaking the JSON your clients depend on, because the DTO is a separate contract.
• Shape: the JSON a client wants is often not shaped like your table (e.g. an author’s name flattened into a book’s response). A DTO lets you choose that shape.

Putting it together

Here is a complete slice: an entity (the database row), a DTO (what we send to clients), a service (the logic) and a thin controller. Read each class and notice how thin the controller becomes:

// 1) The ENTITY — maps to the database, may hold sensitive fields
@Entity
public class User {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;
    private String passwordHash;   // must NEVER be sent to clients
    // getters / setters ...
}

// 2) The DTO — only the safe fields we want the client to see
public class UserDto {
    private Long id;
    private String name;
    private String email;          // note: no passwordHash here
    public UserDto(Long id, String name, String email) {
        this.id = id; this.name = name; this.email = email;
    }
    // getters ...
}

// 3) The SERVICE — holds the logic, returns DTOs not entities
@Service
public class UserService {
    private final UserRepository repo;
    public UserService(UserRepository repo) { this.repo = repo; }

    public UserDto getUser(Long id) {
        User u = repo.findById(id)
            .orElseThrow(() -> new NotFoundException("No user " + id));
        // map entity -> DTO (drop the password)
        return new UserDto(u.getId(), u.getName(), u.getEmail());
    }
}

// 4) The CONTROLLER — thin: just delegates to the service
@RestController
@RequestMapping("/users")
public class UserController {
    private final UserService service;
    public UserController(UserService service) { this.service = service; }

    @GetMapping("/{id}")
    public UserDto one(@PathVariable Long id) {
        return service.getUser(id);
    }
}

The mapping step (and a shortcut)

Turning an entity into a DTO (and back) is called mapping. Above we did it by hand — clear and simple. For many fields this gets repetitive, so teams often use a mapper library like ModelMapper or MapStruct that copies matching fields for you. Hand-mapping is perfect to start; reach for a mapper when there are lots of fields.