📑 Padrões de Desenvolvimento – Backend

Esta página visa apresentar os padrões a serem utilizados no desenvolvimento de código do repositório do Backend da aplicação.

Sumário

1. Swagger
2. 📌 DTOs
3. Estrutura de Exceções

Swagger

Além de seguir os padrões determinados pela arquitetura e estrutura de pastas do projeto, é necessário atualizar a estrutura do Swagger conforme é realizado o desenvolvimento da aplicação.

As marcações do Swagger devem ser inseridas em:

• Controllers
• Models
• DTOs

📌 DTOs

• Todos os DTOs devem ser criados na pasta dto do seu modulo.
• Para a criação dos DTOs usamos a anotação @Valid para validar o tipo de um atributo .
• Utilizar o Bean Validation do Spring para validação automática de atributos.
• As anotações de validação devem ser aplicadas diretamente nos atributos do DTO.

Exemplo:

public class UsuarioDTO {

    @NotBlank(message = "O nome é obrigatório")
    private String nome;

    @Email(message = "E-mail deve ser válido")
    private String email;

    @NotNull(message = "A idade é obrigatória")
    @Min(value = 18, message = "Idade mínima é 18 anos")
    private Integer idade;
}

Na Controller:

@PostMapping
public ResponseEntity<UsuarioDTO> salvar(@RequestBody @Valid UsuarioDTO usuarioDTO) {
    return ResponseEntity.ok(service.salvar(usuarioDTO));
}

Estrutura de Exceções

• exception/HttpException.java → classe base
• exception/NotFoundException.java → exemplo de exceção específica
• config/GlobalExceptionHandler.java → handler global

Handler Global: GlobalExceptionHandler

• O handler global (GlobalExceptionHandler) captura todas as exceções e retorna respostas padronizadas:
• HttpException → retorna a mensagem e o status HTTP definido na exceção
• Exception → erros genéricos retornam 500 com mensagem padrão
• MethodArgumentNotValidException → validação de DTOs retorna 400 BAD_REQUEST com detalhes de cada campo
• IllegalArgumentException → retorna 400 BAD_REQUEST com mensagem da exceção

1. Criando Exceções

Todas as exceções personalizadas devem estender HttpException.

public class NotFoundException extends HttpException {
    public NotFoundException(String message) {
        super(message, HttpStatus.NOT_FOUND);
    }
}

```java
@GetMapping("/usuarios/{id}")
public Usuario getUsuario(@PathVariable Long id) {
    return usuarioRepository.findById(id)
            .orElseThrow(() -> new NotFoundException("Usuário não encontrado"));
}

Retorno :

{
  "message": "Usuário não encontrado",
  "status": "NOT_FOUND"
}

Boas Práticas de Exceções

• Sempre criar exceções específicas estendendo HttpException.
• Usar mensagens claras e descritivas.
• Não lançar RuntimeException direto; use suas exceções customizadas.
• Validações de DTO são tratadas automaticamente (@Valid).
• Não manipular a resposta JSON de erro manualmente; o handler global cuida disso.