Custom Exceptions

Biblioteca desenvolvida para padronizar o tratamento de exceções em microsserviços Spring Boot.
Inclui exceções personalizadas, record para payload de erro e um @RestControllerAdvice global para capturar e formatar respostas HTTP de forma consistente.

Repositório GitHub: github.com/JuhMaran/custom-exceptions

---

Estrutura e funcionalidades

Recursos principais

• record ApiErrorResponse – Estrutura de resposta padrão de erro.
• Exceções personalizadas:
  • BusinessException → Erros de regra de negócio (400)
  • NotFoundException → Recurso não encontrado (404)
  • UnauthorizedException → Falha de autenticação (401)
  • ForbiddenException → Acesso negado (403)
  • ConflictException → Conflitos de estado (409)
• GlobalExceptionHandler – Tratamento global automático via @RestControllerAdvice.

---

Instalação / Importação

1. Instalar localmente

Execute na raiz do projeto:

mvn clean install

Depois, adicione a dependência no pom.xml do seu microsserviço:

<dependency>
    <groupId>com.julianemaran.libraries</groupId>
    <artifactId>custom-exceptions</artifactId>
    <version>1.0.0</version>
</dependency>

2. Publicar no GitHub Packages (opcional)

Se desejar compartilhar entre projetos via GitHub Packages:

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/JuhMaran/custom-exceptions</url>
    </repository>
</repositories>

---

Uso em um microsserviço

Exemplo de uso

import com.julianemaran.libraries.exceptions.types.BusinessException;
import com.julianemaran.libraries.exceptions.types.NotFoundException;
import org.springframework.stereotype.Service;

@Service
public class UserService {

  public User findUserById(Long id) {
    return userRepository.findById(id)
      .orElseThrow(() -> new NotFoundException("Usuário não encontrado com ID: " + id));
  }

  public void validateUser(User user) {
    if (!user.isActive()) {
      throw new BusinessException("Usuário inativo não pode realizar esta operação");
    }
  }
}

Resposta de erro gerada automaticamente

{
  "status": 404,
  "error": "Not Found",
  "message": "Usuário não encontrado com ID: 15",
  "path": "/api/users/15",
  "timestamp": "2025-10-16T14:30:12"
}

---

Boas Práticas

• Lance exceções específicas em vez de RuntimeException.
• Deixe o GlobalExceptionHandler tratar os erros globalmente.
• Forneça mensagens claras e úteis nas exceções.
• Não exponha informações sensíveis nos detalhes da exceção.

---

Estrutura da biblioteca

custom-exceptions/
 ├── pom.xml
 └── src/main/java/com/julianemaran/libraries/exceptions/
      ├── handler/
      │   └── GlobalExceptionHandler.java
      ├── model/
      │   └── ApiErrorResponse.java
      └── types/
          ├── BusinessException.java
          ├── NotFoundException.java
          ├── UnauthorizedException.java
          ├── ForbiddenException.java
          └── ConflictException.java

---

Licença

Distribuído sob a licença MIT.
Sinta-se à vontade para usar e adaptar em seus microsserviços.

---

Autora: Juliane Maran
Stack: Java 25 • Spring Boot 3.5.6 • Maven
Pacote: com.julianemaran.libraries.exceptions

---