DEV Community: Ledson Oliveira da Silva

Desacoplando lógicas com PublishEvent + EventHandler no Spring Boot

Ledson Oliveira da Silva — Wed, 10 Sep 2025 12:14:49 +0000

Quando estamos desenvolvendo aplicações no Spring Boot, é comum nos depararmos com cenários em que uma única ação precisa disparar várias consequências.

Pense no caso de cadastro de usuário: além de salvar os dados no banco, talvez seja necessário enviar um e-mail de boas-vindas, registrar um log, ou até notificar outro sistema.

A solução mais direta seria implementar tudo dentro do próprio UserService. Mas logo surge o problema: o método que deveria apenas cadastrar o usuário acaba assumindo várias responsabilidades, ficando cada vez mais difícil de manter e evoluir.

👉 E aí surge a pergunta: como podemos desacoplar essas lógicas sem transformar nosso código em um monólito cheio de dependências internas ou partir imediatamente para soluções complexas como Kafka ou microsserviços?

É exatamente aí que entram os eventos no Spring Boot.
Com o uso de publishEvent e @EventListener, conseguimos criar uma comunicação interna desacoplada, onde o serviço principal apenas publica o que aconteceu, e outros componentes ficam responsáveis por reagir a isso de forma independente.

Neste artigo, vou mostrar na prática:

Como usar eventos no Spring Boot.
Vantagens dessa abordagem.
Boas práticas e armadilhas comuns.
Como esse padrão se conecta com arquiteturas maiores, como CQRS e event-driven.

📌 Como usar eventos no Spring Boot

O Spring Boot já oferece suporte nativo a eventos, e o fluxo básico é bem simples:

Definimos um evento (geralmente representando algo que aconteceu no domínio).

Publicamos esse evento em algum ponto do sistema.

Criamos handlers/listeners que irão reagir a ele.

Vamos ver isso passo a passo em um exemplo prático de cadastro de usuário.

1. Criando o evento

Podemos representar um evento como uma classe simples.
No nosso caso, vamos criar um UserCreatedEvent para indicar que um novo usuário foi registrado.

public record UserCreatedEvent(Long userId, String email) {}

💡 Aqui usei um record para deixar o código mais conciso, mas você pode usar uma classe normal se preferir.

2. Publicando o evento

Dentro do UserService, assim que o usuário for cadastrado, vamos publicar o evento.

@Service
@RequiredArgsConstructor
public class UserService {

    private final ApplicationEventPublisher publisher;

    public void registerUser(String email) {
        // Simulação de cadastro
        User user = saveUser(email);

        // Publica o evento
        publisher.publishEvent(new UserCreatedEvent(user.getId(), user.getEmail()));
    }

    private User saveUser(String email) {
        // persistência fake só para exemplo
        return new User(1L, email);
    }
}

3. Reagindo ao evento

Agora podemos criar quantos handlers quisermos para reagir ao evento.
O Spring Boot cuida da mágica para chamar cada um deles automaticamente.

@Component
public class SendWelcomeEmailHandler {

    @EventListener
    public void handle(UserCreatedEvent event) {
        System.out.println("Enviando e-mail para: " + event.email());
    }
}

@Component
public class CreateLogHandler {

    @EventListener
    public void handle(UserCreatedEvent event) {
        System.out.println("Criando log para usuário: " + event.userId());
    }
}

🔎 Note como o UserService não tem conhecimento de como o e-mail é enviado ou onde o log é registrado. Ele apenas publica o evento, e cada handler faz o seu trabalho de forma independente.

Assim, com poucas linhas de código, já conseguimos um fluxo desacoplado e extensível: se amanhã você quiser adicionar mais uma ação (como notificar outro sistema via API), basta criar um novo handler, sem tocar no código de cadastro.

🚀 Vantagens de usar eventos no Spring Boot

Adotar a publicação e tratamento de eventos no Spring Boot traz diversos benefícios para a arquitetura da aplicação, mesmo em projetos que ainda são monólitos.

🔹 1. Desacoplamento

O serviço principal (ex.: UserService) não precisa conhecer os detalhes de como cada ação complementar será executada.
Ele só dispara o evento — e os handlers cuidam do resto.
Isso reduz dependências diretas entre classes e facilita a manutenção.

🔹 2. Extensibilidade

Se amanhã surgir a necessidade de enviar um push notification ou integrar com outro sistema, não é necessário modificar o código do cadastro de usuário.
Basta criar um novo handler para reagir ao mesmo evento.

Ou seja, o sistema cresce de forma aberta para extensão e fechada para modificação (princípio OCP do SOLID).

🔹 3. Organização do código

Cada responsabilidade fica em seu próprio componente, evitando métodos gigantes que fazem “tudo ao mesmo tempo”.
Isso deixa o código mais legível e as classes mais coesas.

🔹 4. Reuso e testabilidade

Handlers podem ser testados isoladamente, sem precisar passar por todo o fluxo do serviço principal.
Além disso, um mesmo evento pode ser usado para disparar múltiplas ações em contextos diferentes.

🔹 5. Preparação para arquiteturas maiores

Mesmo em um monólito, trabalhar com eventos já cria uma mentalidade event-driven, tornando a transição para soluções com mensageria (Kafka, RabbitMQ) ou padrões como CQRS bem mais natural.

⚠️ Armadilhas e boas práticas

Apesar de trazerem muitas vantagens, os eventos no Spring Boot também exigem atenção para evitar problemas de manutenção e comportamento inesperado.

⚠️ 1. Eventos são síncronos por padrão

Quando você usa publishEvent, o fluxo espera todos os handlers terminarem antes de seguir.

Se algum handler for lento (ex.: envio de e-mail externo) ou lançar exceção, pode impactar diretamente o serviço principal.

✅ Boas práticas:

Use @Async nos handlers que podem rodar em paralelo, evitando travar o fluxo principal.

Para isso, basta habilitar @EnableAsync na sua aplicação.

⚠️ 2. Cuidados com transações

Se você publicar o evento dentro de uma transação, ele será disparado imediatamente — mesmo que a transação ainda não tenha sido confirmada.
Isso pode causar inconsistência (ex.: handler tenta acessar dados que ainda não foram persistidos).

✅ Boas práticas:

Use @TransactionalEventListener para garantir que o handler só seja executado após o commit da transação.

Exemplo:

@Component
public class CreateLogHandler {

    @TransactionalEventListener
    public void handle(UserCreatedEvent event) {
        System.out.println("Criando log após commit para usuário: " + event.userId());
    }
}

⚠️ 3. Não transformar tudo em evento

É tentador usar eventos para “qualquer coisa”, mas isso pode deixar o sistema difícil de debugar e seguir o fluxo.

✅ Boas práticas:

Use eventos quando há múltiplos interessados em uma mesma ação.

Para lógicas simples e locais, prefira manter o código direto no serviço.

⚠️ 4. Tratamento de falhas

Por padrão, se um handler lançar exceção, ela pode se propagar e afetar o fluxo.
Isso pode ser crítico se o evento for parte de uma ação de negócio essencial.

✅ Boas práticas:

Isolar a lógica dos handlers com try/catch.

Para eventos assíncronos, configurar retries ou dead-letter (quando migrar para mensageria).

👉 Em resumo: eventos são poderosos, mas não são bala de prata. Usados com consciência, ajudam a manter a aplicação organizada e preparada para crescer.

🔗 Conexão com arquiteturas maiores

Trabalhar com publishEvent e @EventListener no Spring Boot pode parecer algo simples, mas na prática é um primeiro passo para arquiteturas mais robustas.

Esse padrão já introduz uma mentalidade event-driven, que facilita a migração futura para:

CQRS – separando comandos e queries.

Mensageria (Kafka, RabbitMQ) – distribuindo eventos entre microsserviços.

Escalabilidade – permitindo que novas funcionalidades sejam adicionadas sem acoplar ao core.

✅ Conclusão

Usar eventos no Spring Boot é uma forma prática de desacoplar responsabilidades, manter o código mais limpo e extensível, além de preparar o terreno para arquiteturas mais avançadas.

Mesmo em aplicações monolíticas, essa abordagem já traz ganhos reais de organização e manutenção.

👉 E você, já usou eventos no seu projeto com Spring Boot? Prefere manter tudo síncrono ou já partiu para mensageria com Kafka/RabbitMQ? Conta aí nos comentários!

Implantando um aplicativo Angular com DigitalOcean e GitHub de forma gratuita

Ledson Oliveira da Silva — Wed, 15 Jan 2025 18:32:44 +0000

Neste artigo, abordaremos como implantar um aplicativo Angular utilizando o DigitalOcean combinado com o GitHub para configurar um pipeline de entrega contínua (CI/CD) de forma eficiente e gratuita.

Esses dias, estava olhando algumas opções, para criar uma pipeline de um projeto pessoal, com bom custo beneficio, e me deparei com o serviço Platform App da digital ocean, é um PaaS (Plataforma como serviço) que simplifica o processo de implantação, gerenciamento e escalabilidade de aplicativos, sites estáticos e APIs, permitindo que desenvolvedores foquem no código sem se preocupar com a infraestrutura subjacente.

Em outras palavras, é um lugar onde vai hospedar suas aplicações, sem ter que se preocupar com infra, sistema operacional, plataforma para CI/CD, um serviço bem legalzinho, que vai te economizar um bom tempo, e fazer com que foque mais no desenvolvimento do seu produto, sem perder horas configurando VM, pipeline, Firewall, conectividade, etc...

O mais legal, é que ele oferece 3 aplicações web estáticas, 100% free, dai resolvi fazer um teste e implantar um frontend feito com angular que tenho aqui, e funcionou perfeitamente, dito isso, resolvi escrever aqui e compartilhar o passo a passo de como funciona este processo.

Pré-requisitos:

Ter uma conta na digital ocean.
Conhecimento de GIT e Github.
Angular-Cli instalado.

Obs: Neste exemplo, estarei utilizando a versão 18 do angular.

Passo 01 (Criar novo projeto com angular-clie):

ng new <project-name>

Na criação do projeto, será perguntado se deseja habilitar a renderização do lado do servidor (SSR), neste caso deixe marcado com "N", pois para nos encaixarmos no plano FREE, o aplicativo deve ser estatico, e caso queira habilitar SSR, você precisará selecionar um plano que tenha um servidor web, e não será gratuito.

Passo 02 (Ajustar configurações do projeto):

Ajuste o processo de build no arquivo angular.json, por default o angular vem configurado para gerar um build de aplicativo para executar em um servidor, precisamos que gere os arquivos para executar de forma estatica.

Ajuste de o arquivo para conforme o trecho abaixo de:

"architect": {
    "build": {
        "builder": "@angular-devkit/build-angular:application",
        "options": {
            "outputPath": "dist/angular-platform-app",
            "index": "src/index.html",
            "browser": "src/main.ts",
            .....

Para:

"architect": {
    "build": {
        "builder": "@angular-devkit/build-angular:browser",
        "options": {
            "outputPath": "dist",
            "index": "src/index.html",
            "main": "src/main.ts",
            .....

Neste caso a alteração aqui foi feita em "builder" alterado de application para browser, e consequentemente a chave "browser" para "main".

Também foi alterado "outputPath" para que os arquivos fiquem na raiz da pasta "dist".

DIFF:

Passo 03 (NPM Install):

Importante rodar um NPM install no projeto recem criado, pois ele adiciona alguns metadados com relação ao node no package-lock.json que no caso se não for versionado, ocasionará erro no build dentro da plataforma.

Passo 04 (Versionamento no github):

Aqui é somente comitar e subi em seu repositório no github mesmo, não vou entrar no mérito de como faz este processo.

Passo 05 (Criar APP no Platform App da DigitalOcean) conforme steps abaixo:

No menu "CREATE", selecione o produto "Platform APP"

Deixe marcado a opção Github e será necessário conceder permissão para DigitalOcean enxergar seus repositórios:

Após conceder a permissão, ele deve aparecer no combo de repositórios, dai basta selecionar e configurar a branch no qual será disparado a trigger para deployment, o source directory e o checkbox para indicar se o deployment será automático conforme seja comitado nesta determinada branch:

Avance para próxima etapa, e neste momento que precisaremos ajustar o resourceType para efetuar o deploymeny em um "Static WEB", por padrão ele vem marcado como "WebServer". No APP basta clicar em Edit, e na opção "ResourceType" clicar também em Edit e selecionar a opção "Static Site", conforme imagem abaixo:

Após editar, basta voltar em "Back" e avançar para próxima etapa.

Agora basta avanças as etapas, não precisa de mais nenhuma configuração adicional e por fim criar o recurso, aqui você poderá vê que o preço ficou em $0.00:

Finish, aplicativo criado e implantado:

Aplicação no AR:

É isso pessoal, espero que o conteúdo seja util, e estou aberto a sugestões e críticas com relação ao conteúdo.

Um abs!

Links importantes:

Repositório utilizado no exemplo:
https://github.com/ledsonsilva/angular-platform-app-example

Documentação PlaformApp:
https://docs.digitalocean.com/products/app-platform/

Documentação Angular:
https://angular.dev/installation

Tratamento de erros personalizados para APIs rest com Spring Boot.

Ledson Oliveira da Silva — Sun, 20 Dec 2020 01:05:48 +0000

Hello guys! Aqui quem vos escreve é o Ledson Silva, desenvolvedor de software desde meados de 2014 e o objetivo desta publicação é demonstrar como faço para implementar tratamento de erros personalizados para api rest no spring boot.

Atualmente o spring tem uma resposta genérica para caso de erros e que na maioria das vezes queremos devolver para os clients uma resposta mais elaborada, que tenha mais informações e principalmente quando estamos trabalhando com javax validation elaborar uma resposta elegante.

Ah!!! e além de implementar uma resposta personalizada, também vou mostrar como faço para organizar minhas exceptions e as mensagens de erros que minhas apis devolvem de resposta.

Vamos lá!!

OBS: Neste exemplo estou usando Java 11 e nosso projeto spring tem as seguintes dependencias:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.5</version>
</dependency>

Passo 01: No primeiro passo iremos criar dois arquivos, onde será colocado nossas mensagens de erros. Faremos algo com esta estrutura dentro do pacote resources:

No arquivo business.properties concentraremos as mensagems de regras de negócio, e no arquivo validation.properties serão as mensagens de validações de dados.

Passo 02: Criar o arquivo de configuração para o spring recuperar estes arquivos de mensagens, no caso iremos apenas utilizar o esquema de internacionalização do spring.

MessageConfiguration.java

@Configuration
public class MessageConfiguration implements WebMvcConfigurer {
    @Bean
    public MessageSource messageSource() {
        ReloadableResourceBundleMessageSource messageSource = new ReloadableResourceBundleMessageSource();
        messageSource.setBasenames("classpath:/messages/business/business", "classpath:/messages/validation/validation");
        messageSource.setDefaultEncoding("UTF-8");
        return messageSource;
    }

    @Bean
    public LocalValidatorFactoryBean validator(MessageSource messageSource) {
        LocalValidatorFactoryBean bean = new LocalValidatorFactoryBean();
        bean.setValidationMessageSource(messageSource);
        return bean;
    }

    @Bean
    public LocaleResolver localeResolver() {
        SessionLocaleResolver localeResolver = new SessionLocaleResolver();
        localeResolver.setDefaultLocale(Locale.US);
        return localeResolver;
    }

    @Bean
    public LocaleChangeInterceptor localeChangeInterceptor() {
        LocaleChangeInterceptor localeChangeInterceptor = new LocaleChangeInterceptor();
        localeChangeInterceptor.setParamName("lang");
        return localeChangeInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(localeChangeInterceptor());
    }
}

Passo 03: Criar a estrutura dos erros personalizados, no caso os dtos que retornaremos em nossa api:

ErrorDTO.java

public class ErrorDTO {
    private String key;
    private String message;

    public ErrorDTO() {
    }

    public ErrorDTO(String key, String message) {
        this.key = key;
        this.message = message;
    }

    ... getters and setters
}

ApiErrorDTO.java

public class ApiErrorDTO {
    private Date timestamp;
    private Integer status;
    private String code;
    private Set<ErrorDTO> errors;

    public ApiErrorDTO() {
    }

    public ApiErrorDTO(Date timestamp, Integer status, String code, Set<ErrorDTO> errors) {
        this.timestamp = timestamp;
        this.status = status;
        this.code = code;
        this.errors = errors;
    }

    ... getters and setters
}

Passo 04: No quarto passo criaremos nossa exception base, que utilizaremos para estende-las ao criar nossas exceptions de negócio.

MessageException.java

public interface MessageException {
    String getExceptionKey();
    Map<String, Object> getMapDetails();
}

BaseRuntimeException.java

public abstract class BaseRuntimeException extends RuntimeException implements MessageException {
    private final Map<String, Object> mapDetails;

    public BaseRuntimeException() {
        mapDetails = null;
    }
    public BaseRuntimeException(final Map<String, Object> mapDetails) {
        this.mapDetails = mapDetails;
    }

    public abstract String getExceptionKey();

    public Map<String, Object> getMapDetails() {
        return this.mapDetails;
    }
}

Passo 05: Aqui está o pulo do gato!! criaremos a nossa clase que será responsável por interceptar as exceptions e transforma-las em nossa resposta personalizada conforme os dtos que criamos anteriormente.

ExceptionHandlerAdvice.java

@ControllerAdvice
public class ExceptionHandlerAdvice {
    private static final String UNKNOWN_ERROR_KEY = "unknown.error";

    private static final Logger logger = LoggerFactory.getLogger(ExceptionHandlerAdvice.class);
    private final MessageSource messageSource;

    public ExceptionHandlerAdvice(MessageSource messageSource) {
        this.messageSource = messageSource;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiErrorDTO> handlerMethodArgumentNotValid(
            MethodArgumentNotValidException exception
    ) {
        logger.error("Exception {}, Message: {}", exception.getClass().getName(), exception.getMessage());
        Set<ErrorDTO> errors = exception.getBindingResult()
                .getFieldErrors()
                .stream()
                .map(error -> buildError(error.getCode(), error.getDefaultMessage()))
                .collect(Collectors.toSet());

        return ResponseEntity
                .status(HttpStatus.BAD_REQUEST)
                .body(baseErrorBuilder(HttpStatus.BAD_REQUEST, errors));
    }

    @ExceptionHandler(BaseRuntimeException.class)
    public ResponseEntity<ApiErrorDTO> handlerBaseException(Throwable exception) {
        logger.error("Exception {}", exception.getClass().getName());
        MessageException messageException = (MessageException) exception;
        ErrorDTO error = buildError(messageException.getExceptionKey(),
                bindExceptionKeywords(messageException.getMapDetails(),messageException.getExceptionKey()));

        Set<ErrorDTO> errors = Set.of(error);
        ApiErrorDTO apiErrorDto = baseErrorBuilder(getResponseStatus(exception), errors);

        return ResponseEntity
                .status(getResponseStatus(exception))
                .body(apiErrorDto);
    }

    @ExceptionHandler(Throwable.class)
    public ResponseEntity<ApiErrorDTO> handlerMethodThrowable(Throwable exception) {
        logger.error("Exception {}, Message: {}", exception.getClass().getName(), exception.getMessage());
        Set<ErrorDTO> errors = Set.of(buildError(UNKNOWN_ERROR_KEY, exception.getMessage()));
        return ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(baseErrorBuilder(HttpStatus.INTERNAL_SERVER_ERROR, errors));
    }

    private ErrorDTO buildError(String code, String message) {
        return new ErrorDTO(code, message);
    }

    private ApiErrorDTO baseErrorBuilder(HttpStatus httpStatus, Set<ErrorDTO> errorList) {
        return new ApiErrorDTO(
                new Date(),
                httpStatus.value(),
                httpStatus.name(),
                errorList);
    }

    private String bindExceptionKeywords(Map<String, Object> keywords, String exceptionKey) {
        String message = messageSource.getMessage(exceptionKey, null, LocaleContextHolder.getLocale());
        return Objects.nonNull(keywords) ? new StrSubstitutor(keywords).replace(message) : message;
    }

    private HttpStatus getResponseStatus(Throwable exception) {
        ResponseStatus responseStatus = exception.getClass().getAnnotation(ResponseStatus.class);
        if (exception.getClass().getAnnotation(ResponseStatus.class) == null) {
            return HttpStatus.INTERNAL_SERVER_ERROR;
        }
        return responseStatus.value();
    }
}

Isso já é suficiente para transformar nossas exceptions em nossa resposta personalizada. E agora iremos criar uma estrutura com uma Controller e um DTO para requests, onde teremos dois endpoints POST mesmo um para exemplificar erros de validação e outro para erros de negócio!

ExampleDTO.java

public class ExampleDTO {
    @NotNull(message = "{required.validation}")
    private Long id;

    @NotBlank(message = "{required.validation}")
    @Size(min = 4, max = 30, message = "{size.validation}")
    private String name;

    public ExampleDTO() {
    }

    public ExampleDTO(Long id, String name) {
        this.id = id;
        this.name = name;
    }

    ... getters and setters
}

ExampleExceptionController.java

@RestController
@RequestMapping(path = "custom-exception-example")
public class ExampleExceptionController {
    @PostMapping(path = "validation")
    public ResponseEntity<ExampleDTO> exampleModelValidationEndpoint(@Validated @RequestBody ExampleDTO dto) {
        return ResponseEntity.ok(dto);
    }

    @PostMapping(path = "business")
    public ResponseEntity<String> exampleBusinessValidationEndpoint(@Validated @RequestBody ExampleDTO dto) {
        if (dto.getName().equalsIgnoreCase("params")) {
            throw new ExampleNameRuleWithParamsException("params");
        }

        if (!dto.getName().equalsIgnoreCase("business")) {
            throw new ExampleNameRuleException();
        }
        return ResponseEntity.ok("Success!");
    }
}

E por último e não menos importante são as mensagens nos arquivos que criamos no primeiro passo.

business.properties

example.name.rule=No campo name somente é permitido o valor: business
example.name.rule.with.params=Não é permitido digitar o valor: ´${value}´ no campo name

validation.properties

required.validation=Existem campos obrigatórios que não foram preenchidos
size.validation=Tamanho inválido! Digite no mínimo {min} e no máximo {max} caracteres

Só uma explicação!! Em nosso DTO de exemplo quando temos uma anotação de validation, por exemplo @NotBlank é necessário definir a chave na qual irá representar em seu arquivo de mensagem por exemplo:

@NotNull(message = "{required.validation}")

E quando for exceptions de negócio, no qual precisaremos criar uma exception que estende de BaseRuntimeException.java a mesma nos obriga a implementar o método String getExceptionKey(), e será neste método que retornaremos nossa chave correspondente em nosso arquivo business.properties.

Exemplo:

ExampleNameRuleException.java

@ResponseStatus(HttpStatus.BAD_REQUEST)
public class ExampleNameRuleException extends BaseRuntimeException {
    private static final String KEY = "example.name.rule";

    public ExampleNameRuleException() {
        super();
    }

    @Override
    public String getExceptionKey() {
        return KEY;
    }
}

ExampleNameRuleWithParamsException.java

@ResponseStatus(HttpStatus.BAD_REQUEST)
public class ExampleNameRuleWithParamsException extends BaseRuntimeException {
    private static final String KEY = "example.name.rule.with.params";

    public ExampleNameRuleWithParamsException(String value) {
        super(Map.of("value", value));
    }

    @Override
    public String getExceptionKey() {
        return KEY;
    }
}

Entendido??!!! se não deixa um comentário aqui que trocaremos uma idéia.

Beleza galera!!! temos nossa implementação, e no final meu projeto ficou com esta estrutura:

E por fim segue os prints dos testes:

Erros de validação:

Erros de negócio:

Porque eu gosto desta abordagem?? cara desta forma eu consigo ter um padrão de resposta de erros para minha api, tanto para erros de validações, obrigatoriedade etc.. quanto para erros de negócio!! além de também separar as mensagens de erros em arquivos especificos e com chaves que podem ser reutilizadas pelo sistema!!! quando precisar mudar uma mensagem de erro não preciso dar um ctrl + f no projeto e sair alterando em vários arquivos e códigos... fica concentrado apenas nos arquivos das mensagens.

Por enquanto é isso galera!! esta é a forma com que gosto de organizar meus projetos em relação aos erros de API e espero que tenham gostado da implementação.

Todos os arquivos citados no post pode ser encontrado em meu github.