📊 Capítulo 03: Controllers REST & DTOs Records

Especialização Backend com Java 21 & Spring Boot 3

🗺️ O Fluxo de uma Requisição REST no Spring MVC

flowchart LR
    REQ["HTTP Request (JSON)"]
    --> DISPATCHER["DispatcherServlet"]
    --> HANDLER["HandlerMapping"]
    --> CTRL["@RestController\n(@PostMapping / @GetMapping)"]
    --> DTO["Java 21 Record DTO\n(Desserialização Jackson)"]
    --> SERVICE["Service Layer"]
    --> RESP["ResponseEntity<ResponseDTO>\n(HTTP 200/201/204 / JSON)"]

    style REQ fill:#ede7f6,stroke:#512da8,stroke-width:2px
    style DISPATCHER fill:#fff3e0,stroke:#ff9800,stroke-width:1.5px
    style HANDLER fill:#fff3e0,stroke:#ff9800,stroke-width:1.5px
    style CTRL fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style DTO fill:#e1f5fe,stroke:#03a9f4,stroke-width:1.5px
    style SERVICE fill:#c8e6c9,stroke:#2e7d32,stroke-width:1.5px
    style RESP fill:#e0f2f1,stroke:#00897b,stroke-width:2px

🎯 Slide 1: @RestController & @ResponseBody

• @RestController: Combinação de @Controller + @ResponseBody, indicando que o retorno de cada método é serializado diretamente no corpo da resposta HTTP (JSON/XML).

• Mapeamento Semântico HTTP:
  • @GetMapping: Leitura de recursos (Idempotente e Seguro).
  • @PostMapping: Criação de recursos (Retorna HTTP 201 Created com cabeçalho Location).
  • @PutMapping: Atualização integral idempotente.
  • @PatchMapping: Atualização parcial.
  • @DeleteMapping: Exclusão (Retorna HTTP 204 No Content).

🎯 Slide 2: Java 21 Records como DTOs Canônicos

public record UsuarioRequestDTO(
    @NotBlank(message = "O nome é obrigatório")
    String nome,

    @Email(message = "E-mail inválido")
    String email,

    @Positive(message = "A idade deve ser positiva")
    Integer idade
) {}

• Imutabilidade Nativa: Construtor canônico, getters (nome()), equals(), hashCode() e toString() gerados automaticamente pelo compilador Java!

🎯 Slide 3: Construção Semântica com ResponseEntity

@PostMapping
public ResponseEntity<UsuarioResponseDTO> criar(
        @RequestBody @Valid UsuarioRequestDTO dto,
        UriComponentsBuilder uriBuilder) {
    UsuarioResponseDTO novo = service.salvar(dto);
    URI location = uriBuilder.path("/api/v1/usuarios/{id}").buildAndExpand(novo.id()).toUri();
    return ResponseEntity.created(location).body(novo);
}

• Controle total de Status Code (201 Created), Headers (Location) e Payload de resposta.