DEV Community: Meriéli Manzano

RabbitMQ na Prática: Manual de Decisão, Padrões e Resiliência

Meriéli Manzano — Tue, 07 Jul 2026 15:16:27 +0000

Em arquiteturas modernas baseadas em microsserviços e eventos, a comunicação assíncrona é o que mantém os sistemas coesos e resilientes — mas a escolha do message broker errado pode transformar uma solução elegante em um pesadelo operacional de latência, perda de dados e retrabalho. É justamente para navegar por esse campo minado de decisões que este manual foi pensado.

Escrevo aqui com o objetivo de descrever, dissecar e posicionar a tecnologia RabbitMQ no cenário atual, oferecendo:

A compreensão do seu modelo mental e arquitetura interna.
Os atributos de qualidade que ela entrega (e os que ela sacrifica).
Os padrões de uso onde ela se destaca e as armadilhas comuns.
Um guia prático de resiliência e operação

Ao final da leitura, você terá subsídios para avaliar se esta tecnologia resolve as dores específicas do seu domínio de negócio.

O que é RabbitMQ?

É um message broker open-source, que possibilita intermediar mensagens para comunicar sistemas de forma assíncrona. Tem suporte e plugins para várias linguagens de programação.

Surgiu em 1 de julho de 2007 e implementa o protocolo AMQP “Advanced Message Queuing Protocol - AMQP” na versão 0-9-1, que é a versão mais usada desse protocolo, além de suportar múltiplos protocolos adicionais, sendo amplamente utilizado para desacoplar serviços, construir arquiteturas orientadas a eventos e processar cargas de trabalho assíncronas.

Principais Protocolos:

AMQP: É um protocolo avançado de enfileiramento de mensagens baseado no TCP (Transmission Control Protocol), por isso é rápido e confiável. Uma das características desse protocolo é justamente o fato de que um publisher nunca publica mensagens diretamente na fila. A mensagem sempre é encaminhada à Exchange que, de acordo com seu tipo, irá encaminhar para uma determinada fila ou a descartar. Escolha para sistemas corporativos que precisam de roteamento complexo e confiabilidade.

MQTT: O Message Queue Telemetry Transport é um protocolo para troca de mensagens em ambientes onde se tem alguma restrição de hardware, como pouca memória disponível, por exemplo, ou uma limitação de banda. Teve um crescimento notável pela adoção em dispositivos móveis. O objetivo desse protocolo é ser mais simples que o AMQP, utilizado em cenários de mensagens simples e diretas. Escolha para projetos de IoT ou dispositivos com recursos limitados.

STOMP: O Simple (or Streaming) Text Oriented Message Protocol é um protocolo baseado em texto, construído para trabalhar com middlewares orientados à mensagem. Possui uma estrutura similar ao AMQP, com cabeçalho, propriedades e corpo da mensagem, porém não lida com tópicos ou filas. Ele usa uma semântica de string de destino. Escolha para integração com sistemas legados ou aplicações web simples.

Origem e Mantenedores

Criado por: Rabbit Technologies (posteriormente adquirida pela VMware, hoje parte da Broadcom).
Data de lançamento: 2007.
Governança: Projeto open-source com governança comunitária; versão comercial (Tanzu RabbitMQ) sob tutela da Broadcom.
Licenciamento: Mozilla Public License 2.0 (MPL-2.0) – permissiva para uso comercial.

Características Técnicas e Atributos de Qualidade

Tipo de sistema: Message Broker tradicional, um agente intermediador entre um produtor e um consumidor.
Modelo de mensagens: Filas com processamento FIFO “First in First out“, roteamento flexível (fanout, topic, direct, etc.).
Padrão principal: Work queue/ request-reply “é composto de filas, do qual temos uma requisição que é passada para fila e depois o processamento da mensagem”.
Retenção de mensagens: Normalmente até serem consumidas (ou TTL configurado), depois de processada sai do RabbitMQ.
Entrega das mensagens: focado em “entregar e sumir” (at-least-once / at-most).
Ordenação: ordenação por fila, pode se perder com múltiplos consumers porque embora as mensagens permaneçam na ordem correta dentro da fila, os consumidores podem recebê-las fora de ordem devido a competição pelas mensagens e a variação de processamento de cada consumidor, fazendo com que uma mensagem entregue depois seja confirmada antes de uma entregue antes. Um possível contorno é adotar mecanismos como SAC ou particionamento por chave de roteamento.
Throughput: Muito bom, mas limitado comparado ao Kafka, benchmarks afirmam que uma Quorum Queue pode atingir em testes controlados cerca de 30.000 mensagens/segundo com mensagens de 1KB.
Latência: Muito baixa, ótimo para processamentos assíncronos. Em testes práticos, a primeira mensagem de uma fila pode ser entregue em apenas 9 ms.
Escalabilidade: Escala bem, mas com mais esforço de configuração, pois cada nó adicionado ao cluster exige decisões arquiteturais sobre topologia, tipo de fila, replicação, particionamento de rede e limites de recursos.
Tolerância a falhas: Bom suporte a HA / clusters (High Availability), oferecendo na versão 4.x um modelo de alta disponibilidade robusto, consistente e baseado em padrões comprovados da indústria, como o Raft.
Complexidade operacional: Mais simples de começar e administrar, em poucos minutos é possível ter um broker em execução na máquina local.

Componentes Principais e Fluxo de Dados

Entendidas as métricas e os atributos de qualidade surge a pergunta natural: como o RabbitMQ entrega tudo isso? O RabbitMQ introduz uma camada de sofisticação sobre filas simples. Seus blocos fundamentais são:

Producers: Aplicações que enviam mensagens as colocando na fila. Um produtor nunca envia diretamente para uma fila — envia para uma exchange.
Exchanges: É como uma central de triagem dos Correios, ele recebe mensagens dos producers e decide para quais filas elas vão, com base em regras chamadas bindings. Baseado em quatro tipos principais:

-   **Direct:** Roteia por correspondência exata da _routing key_.
-   **Fanout:** Transmite para todas as filas vinculadas.
-   **Topic:** Roteia por correspondência de padrão na _routing key_.
-   **Headers:** Roteia com base em atributos do cabeçalho da mensagem.

Queues: Buffers que armazenam mensagens até que sejam consumidas.
Consumers: Aplicações que recebem e processam mensagens das filas.

O RabbitMQ foi escrito em Erlang, linguagem projetada para sistemas que precisam operar continuamente sem falhas. Nele a mensagem da fila é persistente, ou seja ela fica na fila até ser processada e depois ela é descartada, mas não fica persistida eternamente.

Roteamento Estratégico: Quando Usar Direct, Fanout ou Topic

1. Direct Exchange

A Exchange direta envia a mensagem para uma fila específica, em que temos uma routing key (chave de roteamento) configurada e todas as filas que possuírem essa chave receberão essa mensagem.

Ele possui um algoritmo padrão chamado round-robin e os consumidores recebem as mensagens de forma balanceada. Isto é, se tivermos cinco consumidores para aquele tipo de exchange, a cada envio um deles irá receber.

Caso de uso: para rotear comandos específicos (ex: comando.recalcular.calculo) para filas de workers especializados.

2. Fanout Exchange

Esse tipo simplesmente ignora qualquer 'endereço' (routing key) que você coloque na mensagem e a transmite para TODAS as filas que estiverem vinculadas a ela. O vínculo (binding) é direto e sem chave — a fila apenas se 'inscreve' para receber tudo o que a exchange transmitir. Não importa se você colocar uma routing key, ela será totalmente ignorada.

Cenários que fazem sentido esse tipo de fila é por exemplo quando temos processos paralelos baseado em uma única mensagem ou evento importante, assim várias filas vão receber para processar a mensagem de uma forma específica em cada uma das filas.

Caso de uso: para notificações de sistema (ex: 'Pedido Criado') que disparam múltiplos processos independentes (envio de e-mail, atualização de estoque, faturamento).

3. Topic Exchange

Permite que você crie regras personalizadas para entregar mensagens usando curingas (wildcards) que funcionam como um ‘filtro de palavras’. As palavras são separadas por pontos (.), e você usa dois símbolos mágicos:

* (asterisco): Substitui exatamente uma palavra.
# (hash): Substitui zero ou mais palavras (ou seja, ‘todo o resto’).

Exemplo: Se uma fila estiver vinculada com a regra *.error, ela receberá mensagens com db.error ou api.error (uma palavra antes do error), mas NÃO receberá db.mysql.error (duas palavras antes). Se a regra for payment.#, ela receberá payment (zero palavras depois), payment.created (uma palavra) ou payment.created.success (várias palavras) — pois o # engole todo o resto que vier depois.

Caso de uso: para logs ou eventos de domínio onde você precisa de filtros granulares (ex: *.erro.banco).

O que ocorre em caso de falhas?

Até agora, exploramos o fluxo ideal: produtor publica, exchange roteia, consumidor processa e fim. Mas você sabe que o mundo real é implacável — exceções acontecem, serviços caem e mensagens corrompem. É aqui que o modelo conceitual que acabamos de ver se conecta diretamente com a estratégia de resiliência. Quando uma exceção ocorre durante o processamento, a aplicação pode entrar em um loop infinito, travando todo o fluxo da fila. A primeira linha de defesa contra isso é configurar retry com limites claros.

Defina o número máximo de tentativas com max-attempts e habilite o retry. Caso contrário, após esgotar as tentativas (ex: 4 falhas consecutivas), a mensagem simplesmente será descartada — a menos que você a direcione para uma fila de contingência.

A estratégia da Dead Letter Queue (DLQ)

Para evitar a perda definitiva de mensagens problemáticas, o RabbitMQ permite redirecioná-las para uma fila especial chamada Dead Letter Queue (DLQ) — onde as mensagens aguardam uma decisão manual ou automatizada.

Uma mensagem vai para a DLQ quando:

A fila excede o comprimento máximo;
A mensagem expira (TTL - Time to Live);
A mensagem ultrapassa o tamanho permitido;
Ocorrem erros diversos ou falhas de processamento.

No RabbitMQ, as mensagens não vão diretamente para filas, mas sim via exchanges. Para implementar a DLQ, você precisa criar uma Dead Letter Exchange (DLX). Por exemplo: a exchange pagamento.dlx encaminha as mensagens com falha para a fila pagamentos.detalhes-avaliacao-dlq.

Ao receber uma mensagem na DLQ, você tem algumas opções de tratamento:

Persistir os dados em um banco de dados para análise futura;
Direcioná-la para outra fila (reprocessamento em lote);
Registrá-la em um sistema de logs para auditoria e depuração.

Uma DLQ crescendo de forma atípica não é um sinal de “tudo bem”; é um indicador claro de que há um problema estrutural no consumidor que exige intervenção humana imediata ou a implementação de um circuit breaker para evitar que o sistema continue processando dados incorretamente e poluindo ainda mais a fila morta.

Resiliência Operacional

O RabbitMQ frequentemente ocupa uma posição crítica na arquitetura — ele é o “correio” que mantém seus sistemas conversando. Se ele cair, toda a comunicação assíncrona para. Por isso, alta disponibilidade (HA) é um requisito fundamental para o ambiente de produção.

A prática mais comum para garantir HA é montar um Cluster com múltiplas instâncias do RabbitMQ rodando em paralelo.

Documentação oficial: Clustering Guide - RabbitMQ

Como funciona os clusters na prática:

Você cria várias instâncias do RabbitMQ (nós).
Em seguida, executa o comando de join para conectá-las em um único cluster lógico.

Mas ter um cluster não é suficiente por si só. Você precisa configurar como as mensagens serão tratadas caso um dos nós falhe. Para isso, entram em cena as Políticas (Policies) — regras que definem o comportamento do cluster diante de falhas.

O que uma política define?

Espelhamento (Mirroring): você decide se as mensagens serão replicadas para todos os nós do cluster ou apenas para um subconjunto deles.
Escopo de aplicação: a política pode ser aplicada apenas a Exchanges, apenas a Queues, ou a ambos.

Exemplo prático:

Imagine um cluster com 3 nós. Você pode criar uma política chamada ha-all que replica todas as filas para os 3 nós. Assim, se um nó cair, as mensagens ainda estarão disponíveis nos outros dois.

Critérios de Decisão para o RabbitMQ

✅ Quando Usar

Desacoplamento de serviços: conectar sistemas diferentes sem depender de chamadas diretas entre eles, ou com comunicação assíncrona, absorvendo picos de carga.
Controlar desempenho: Regular o fluxo de dados para não sobrecarregar (ou subutilizar) o sistema.
Aumentar tolerância a falhas: Evitar perda de mensagens e permitir recuperação após erros.
Facilitar a escalabilidade: Permitir vários consumidores para o mesmo produtor, com componentes independentes.
Lidar com alto volume de entrada: Processar requisições de forma assíncrona e em “fire-and-forget” (“disparar e esquecer” é um padrão de comunicação assíncrona amplamente utilizado em sistemas de mensageria e microsserviços).
Amortecer a saída do sistema: Enfileirar dados antes de enviá-los, como em streaming de vídeo e notificações.
Roteamento complexo: Quando diferentes tipos de mensagens precisam ser roteados para diferentes filas com base em regras (ex: logs por severidade, notificações por canal).

❌ Quando Evitar

Streaming de alta vazão (>100k msg/seg por partição): Kafka é mais adequado quando você precisa guardar um histórico ordenado completo de tudo o que aconteceu no sistema (para poder ‘voltar no tempo’ e reconstruir estados) e também quando você precisa mover e processar um volume gigantesco de dados em tempo real, na casa dos milhões de eventos por segundo.
Reprocessamento de eventos históricos: RabbitMQ não mantém mensagens consumidas por padrão (exceto Streams - uma alternativa avançada para cenários que exigem replay de eventos); Kafka é superior para replay de eventos.
Exactly-once semantics nativas: RabbitMQ entrega a mensagem ‘pelo menos uma vez’ para garantir que ela nunca se perca, isso significa que, em situações de falha, a mesma mensagem pode ser entregue duas vezes ao seu sistema. Para garantir que cada mensagem seja processada uma exatamente uma única vez, você precisa programar o consumidor para ser ‘idempotente’ — ou seja, capaz de processar a mesma mensagem várias vezes sem causar efeitos colaterais duplicados.”.
Filas extremamente longas (milhões de mensagens): O desempenho degrada significativamente; considere Streams ou outra solução.
Ambientes com restrição extrema de memória: RabbitMQ é memory-bound “dependente de RAM“ e pode sofrer com paging “paginação forçada varrendo para o disco rígido para liberar espaço, o que consome CPU fazendo tudo ficar lento“ em cenários de baixa memória.

O Lugar do RabbitMQ na Arquitetura Moderna

O RabbitMQ não é uma tecnologia nova — nasceu em 2007 — mas mantém-se extraordinariamente relevante porque resolve um problema fundamental: comunicação assíncrona confiável e com roteamento inteligente. Em um mundo de microsserviços, eventos e domínios complexos, ele continua sendo uma escolha sólida e madura.

Mas, como vimos, ele não é uma bala de prata. Respeitar seus limites é tão importante quanto potencializar seus pontos fortes. A decisão de adotá-lo — ou não — deve ser baseada em critérios objetivos, não em modismos ou preferências pessoais.

Recomendações para o próximo passo

Experimente na prática: suba um RabbitMQ localmente em minutos e reproduza os cenários de Direct, Fanout e Topic que vimos aqui. Nada substitui a experiência tátil.
Leia a documentação oficial: rabbitmq.com/docs é seu melhor amigo para aprofundamentos.
Explore plugins avançados: Shovel, Federation e Management Interface abrem possibilidades que vão além do básico.
Teste cenários de falha propositalmente: derrube nós, sobrecarregue filas, simule erros — só assim você conhece os limites reais do sistema.

A melhor tecnologia não é a mais avançada, mas aquela que resolve o problema certo com a complexidade certa.

Com o conhecimento adquirido neste manual, você está pronto para avaliar, projetar e operar sistemas com RabbitMQ de forma confiante e estratégica. A decisão é sua — e agora você tem subsídios para tomá-la com clareza.

Até a próxima galerinha.

Dos fundamentos à prática: como construir Entidades ricas de verdade

Meriéli Manzano — Thu, 11 Jun 2026 16:33:23 +0000

Você já deve ter ouvido a palavra entidade em diferentes contextos no desenvolvimento de software. No banco de dados, uma entidade é quase uma linha numa tabela. No ORM (ferramenta que converte tabelas do banco em objetos), é uma classe cheia de getters e setters.

Mas quando falamos de Domain-Driven Design (DDD) — uma abordagem para modelar software complexo focando no negócio — o significado é bem mais específico. E é sobre ele que vamos conversar hoje, sem complicação.

Imagine que você está construindo um sistema de matrículas para uma escola. No começo, você faz o simples, cria uma classe Aluno com nome, email e cpf e guarda numa tabela. Para alterar o e-mail, você faz:

$student->email = "new@email.com";
$db->save($student);

Tudo funciona mas com o tempo, os pedidos mudam:

Ao trocar de e-mail, é preciso registrar essa alteração para auditoria.
Um aluno não pode se matricular se já tiver outro com o mesmo CPF ativo.
Quando o aluno muda de nome, precisa enviar uma notificação para a secretaria.

Você tenta colocar essas regras nos controllers (camada que recebe requisições HTTP) ou nos services (camada de orquestração). O resultado? O código começa a se repetir com validação de CPF que aparece em três lugares diferentes; a lógica de notificação que se perde entre uma requisição e outra; o Aluno que vira um simples saco de dados, e qualquer parte do sistema pode deixá-lo em um estado inválido (por exemplo, um aluno ativo com CPF vazio).

Essa dor tem nome: Modelo Anêmico. É quando a classe tem apenas propriedades (atributos) e nenhum comportamento (métodos com regras de negócio). O sistema fica frágil, espalhado e difícil de mudar. É justamente isso que a Entidade do DDD resolve. Ela coloca a identidade e as regras dentro do próprio objeto, protegendo a consistência do negócio.

No DDD, uma Entidade é um objeto com identidade própria (um ID único). Ela muda ao longo do tempo, mas continua sendo a mesma por causa dessa identidade. Ela contém atributos (dados) e comportamentos (regras de negócio) que garantem sua validade e evolução.

Pense em uma pessoa. Ela nasce, troca de nome ao casar, muda de endereço várias vezes, talvez até de cor do cabelo. Apesar de todas essas mudanças, essa pessoa continua sendo ela mesma — sua identidade (documento, biometria, história) é o que a define. Uma empresa também: pode mudar de sede, de sócios, de produto principal, mas o CNPJ e a razão social permanecem. No software, a Entidade é exatamente isso: algo que reconhecemos pela identidade, e não pelos seus dados momentâneos.

Abaixo um exemplo em PHP. Repare que não há set público solto — as mudanças acontecem por métodos nomeados com a intenção do negócio.

// Generic base class for all Domain Entities
abstract class Entity
{
    public function __construct(public readonly string $id)
    {
    }

    public function equals(Entity $other): bool
    {
        return $this->id === $other->id;
    }
}

// Concrete Student entity
class Student extends Entity
{
    private string $email;
    private string $name;
    private bool $active = true;

    public function __construct(
        string $id,
        private readonly string $cpf,
        string $name,
        string $email
    ) {
        parent::__construct($id);
        $this->name = $name;
        $this->email = $email;
    }

    public function changeEmail(string $newEmail): void
    {
        if (!str_contains($newEmail, '@')) {
            throw new \InvalidArgumentException("Invalid email");
        }
        // Could register an "EmailChanged" event for audit here
        $this->email = $newEmail;
    }

    public function deactivate(): void
    {
        if (!$this->active) {
            return;
        }
        $this->active = false;
        // Notify the registrar, etc.
    }

    public function getEmail(): string { return $this->email; }
    public function getName(): string { return $this->name; }
    public function getCpf(): string { return $this->cpf; }
    public function isActive(): bool { return $this->active; }
}

Como usar:

$student = new Student("123", "111.222.333-44", "João", "joao@mail.com");
$student->changeEmail("joao.novo@mail.com"); // valid
$student->deactivate();
// $student->email = "any" → error (private property, no public setter)

Perceba: a identidade é o id (passado no construtor). O objeto muda (email e active), mas o id nunca muda. As regras de negócio ficam dentro da própria classe, não espalhadas.

Exemplos de entidades são: Curso, Aula, Usuário, Progresso, Discussão, Anexo, Tutor, Post, Certificado, Produto, etc.

Não devemos focar o domínio no banco de dados! Há uma propensão de desenvolvedores focarem dados em vez de domínio. Isso pode ocorrer devido a abordagens que colocam a importância no banco de dados. Em vez de projetar conceitos de domínio com comportamentos ricos, pensam principalmente em atributos “colunas” e associações/relacionamentos “chaves estrangeiras”.

Você está projetando pensando em colunas ou em comportamentos de negócio? Pare e reflita: sua classe principal tem regras ou só getters?

Com o tempo, o sistema se torna uma "Big Ball of Mud". Essa expressão descreve um software com estrutura indefinida, cheio de dependências emaranhadas. É impossível prever o efeito de uma alteração. As regras de negócio ficam espalhadas por controllers, serviços e até helpers, tornando o sistema frágil e difícil de evoluir. Para converter um modelo anêmico em uma entidade rica (com comportamento), siga estes passos:

Remova todos os setters públicos da classe. Nenhuma propriedade poderá ser alterada diretamente de fora.
Identifique os motivos de mudança no negócio (ex: “cancelar pedido”, “aprovar pagamento”, “alterar e-mail do aluno”).
Crie métodos públicos nomeados com esses verbos (ex: cancelar(), aprovarPagamento(), alterarEmail($novoEmail)). Cada método deve conter as validações e regras necessárias, além de alterar o estado interno.
Mova para dentro desses métodos toda a lógica que antes estava em serviços ou controllers.
Proteja a criação – use um construtor que exija os dados mínimos para a entidade existir em um estado válido (incluindo o ID de identidade).

Ao seguir esses passos, você perceberá que a entidade deixa de ser um mero recipiente de dados. Ela passa a expressar, por si mesma, as regras do negócio. É aqui que alcançamos o verdadeiro propósito do DDD - ter uma entidade validada na aplicação. Isso significa que, se a entidade já existe (ou seja, foi construída respeitando suas invariantes), automaticamente ela já é válida. Você não precisa espalhar validações pelo sistema para garantir sua consistência. E mais, comportamentos ricos dentro da entidade expandem sua capacidade de evoluir sem quebrar o mundo lá fora.

Esse é o coração do que chamamos de Modelo Rico: um modelo que tem os atributos e os comportamentos, ou seja, os métodos que implementam as regras de negócio. Uma Entidade no DDD não é teoria distante — é uma ferramenta prática para acabar com a bagunça do modelo anêmico e da Big Ball of Mud. A diferença entre um sistema que só armazena dados e um que expressa o negócio está exatamente aí: nas classes que protegem sua própria identidade e evolução.

Agora, pare por um momento e olhe para a classe mais crítica do seu projeto atual. Ela tem comportamento ou é só um saco de getters e setters? Se for a segunda opção, você já tem um candidato perfeito para aplicar os cinco passos que vimos.

Não precisa refatorar tudo de uma vez. Comece pequeno: remova um setter, crie um método com nome de verbo do negócio, mova uma validação para dentro da entidade. O efeito é imediato: testes ficam mais claros, bugs diminuem e seu time volta a conversar sobre regras de negócio, não sobre colunas de banco.

Dê identidade e comportamento à sua próxima Entidade. Você vai sentir a diferença na primeira regra de negócio que deixar de se repetir. Abra o código e comece agora!

Até a próxima galerinha.

Dê significado aos seus dados: Objetos de Valor na prática

Meriéli Manzano — Thu, 28 May 2026 20:29:58 +0000

Pare de usar string para tudo e comece a expressar suas regras de negócio com clareza e segurança

Você já se pegou repetindo as mesmas validações de CPF, e-mail ou telefone em várias partes do sistema? Sentiu que seus modelos de domínio estão anêmicos, cheios de getters e setters, mas sem comportamento real? Se sim, é hora de conhecer o verdadeiro poder dos Objetos de Valor (Value Objects).

Neste artigo, vamos mergulhar fundo nesse conceito transformador. Você vai entender por que Objetos de Valor garantem consistência, eliminam duplicação e tornam seu código mais expressivo e seguro. Prepare-se para elevar o nível da sua modelagem de domínio!

Imagine um CPF: 123.456.789-00. O que importa é o número em si, não uma identidade única que o acompanhe. Se dois CPFs têm o mesmo número, eles são iguais – não importa se foram instanciados em momentos diferentes ou em lugares distintos. Essa é a alma do Objeto de Valor.

Definição: Um Objeto de Valor é um tipo de classe que representa um conceito abstrato, sem identidade própria (não possui ID). Ele é definido apenas por suas propriedades, encapsulando dentro de si um ou mais valores e suas respectivas regras de negócio.

Características fundamentais:

Imutável: uma vez criado, nunca muda. Para alterar, cria-se uma nova instância.
Comparado por atributos: dois Value Objects são iguais se todos os seus atributos forem iguais.
Auto-validado: ao ser instanciado, já garante que o valor é consistente com as regras do domínio.

Exemplos clássicos:

CPF, CNPJ, CEP, telefone
Endereço (composto por logradouro, número, cidade, CEP)
Email, senha hash, duração de tempo, preço, nome próprio, cor, moeda

Por que priorizar Objetos de Valor?

Muitos desenvolvedores, quando pensam em DDD, correm imediatamente para as Entidades. Mas o próprio Eric Evans traz uma orientação poderosa:

Devemos nos esforçar para modelar utilizando Objetos de Valor, em vez de Entidades, sempre que possível. Mesmo quando um conceito de domínio precisa ser modelado como uma Entidade, o projeto da Entidade deve favorecer o uso de um contêiner de valores, em vez de um contêiner de Entidades filho.

Isso significa que o primeiro local para armazenar nossas regras de negócio é no Objeto de Valor, e por isso uma Entidade precisa compor Objetos de Valor, evitando ter Entidades dentro de Entidades.

Os benefícios do Objeto de Valor são enormes:

Reuso imediato: Um Email ou CPF pode ser usado em qualquer lugar (Usuário, Cliente, Fornecedor) sem repetir regras.
Código mais expressivo: Em vez de string $email, temos Email $email. O tipo já revela a intenção e as restrições.
Testabilidade facilitada: Testar as regras de um Value Object isolado é trivial.
Imutabilidade e segurança: Sem side-effects; objetos podem ser compartilhados sem risco.

Mesmo que seu projeto não adote formalmente o DDD (Domain-Driven Design, uma abordagem que coloca o negócio e seu vocabulário no centro do código), usar objetos de valor vale a pena porque eles eliminam a duplicação de validações e garantem consistência em qualquer arquitetura.

Se até aqui você já aprendeu algo, compartilhe este artigo com quem precisa de mais consistência e menos duplicação.

Sinal de alerta para extrair um Value Object

Quando você perceber várias classes com os mesmos atributos (ex.: string $cpf, string $email, string $telefone), cada uma validando do seu próprio jeito, é um forte indicativo de que esses atributos merecem se tornar Objetos de Valor.

Objetos de Valor vs Entidades: quando usar cada um?

Entidades

Identidade: Possui um ID único que a rastreia ao longo do tempo e o que a distingue de outras entidades.
Mutabilidade: Mutável (seus atributos podem mudar, mas a identidade permanece).
Igualdade: Comparação por identidade (ID)
Exemplos de uso: Pessoa, Pedido, Conta Bancária, Produto

Objetos de Valor

Identidade: Não tem identificador único; é definido por seus atributos ou por seu valor.
Mutabilidade: Imutável.
Igualdade: Comparação estrutural (todos os atributos/valores).
Exemplos de uso: CPF, Email, Endereço, Cor, Dinheiro

Construindo um Value Object na Prática

Vamos implementar um Email, usando uma classe abstrata genérica para reaproveitar o método equals e definir por padrão o $value como readonly.

// Shared/ValueObject.php
namespace Shared;

/**
 * @template TInput
 */
abstract class ValueObject
{
    /**
     * @param  TInput  $value
     */
    public function __construct(public readonly mixed $value) {}

    /**
     * @param  self<TInput>  $other
     */
    public function equals(self $other): bool
    {
        return static::class === $other::class && $this->value === $other->value;
    }

    /**
     * @param  self<TInput>  $other
     */
    public function notEquals(self $other): bool
    {
        return !$this->equals($other);
    }
}

Agora, o Value Object concreto Email:

namespace Domain\Account\User\Domain\ValueObjects;

use Domain\Account\User\Domain\Exceptions\InvalidEmailException;
use Shared\ValueObject;

/**
 * Email value object handles domain validation for emails.
 *
 * @extends ValueObject<string>
 */
final class Email extends ValueObject
{
    public function __construct(string $value)
    {
        $trimmed = mb_strtolower(mb_trim($value));

        if (!filter_var($trimmed, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException("The email '{$value}' is invalid.");
        }

        parent::__construct($trimmed);
    }

    public string $local {
        get => explode('@', $this->value)[0];
    }

    public string $domain {
        get => explode('@', $this->value)[1];
    }
}

Observações importantes:

O construtor já valida e normaliza (minúsculas, trim).
As propriedades $local e $domain são derivadas do valor.
O objeto é readonly – imutável por design.
A comparação equals verifica tanto o tipo quanto o valor.

Cuidado: a lógica de negócio dentro do Value Object deve ser autossuficiente e baseada apenas no valor recebido, e não deve depender de contexto externo (como banco de dados, por exemplo).

Objetos de Valor em uso

Uma Entidade no DDD deve ser um contêiner de valores, não uma colcha de retalhos de tipos primitivos. Veja como fica uma UserEntity:

class UserEntity extends Entity  // Entity pai fornece $id e clone()
{
    private function __construct(
        public readonly Name $name,
        public readonly Email $email,
        public readonly ?HashedPassword $password,
        string $id,
    ) {
        parent::__construct($id);
    }
    // Restante do código: factory methods, comportamentos...
}

Note que $name, $email e $password são Objetos de Valor e cada um carrega suas próprias regras. E a Entidade User não precisa se preocupar com essas validações – elas já foram resolvidas no momento da criação.

Dicas para usar Objetos de Valor

Comece pelos primitivos obcecados: qualquer lugar onde você vê string $cpf, string $cep, string $telefone é candidato a Value Object.
Seja imutável: depois de construído, nada pode mudar. Para alterar, crie um novo objeto.
Valide no construtor: lance exceções específicas do domínio se os dados forem inválidos. Assim, um objeto de valor sempre representa um estado consistente.
Implemente equals corretamente: compare o valor na classe e todos os atributos relevantes.

Ao adotar Value Objects, você:

Elimina duplicação de validações.
Torna o código autodocumentado.
Previne estados inválidos.
Facilita a evolução do domínio.

Desafio: Liste 3 atributos do seu sistema atual que são primitivos mas deveriam ser Value Objects e deixe aqui nos comentários. Exemplo: placaVeiculo, numCartaoCredito, intervaloData.

Objetos de Valor não são exclusivos para quem adota o DDD – são uma ferramenta prática para acabar com a bagunça dos tipos primitivos e validações repetidas. Eles transformam regras de negócio escondidas em código limpo, seguro e reutilizável.

Então lembre-se: todo CPF, e-mail ou telefone no seu sistema é um valor que merece respeito. Trate-os como objetos – e eles tratarão bem o seu domínio.

Agora vá, identifique um atributo extraia seu primeiro Value Object, e sinta a diferença na consistência. Seu eu do futuro vai agradecer.

Gostou? Então não perca os próximos. Me siga e receba mais artigos sobre código de qualidade e arquitetura de software de verdade.

🔔 Compartilhe com quem ainda valida CPF com if solto no código.

Vamos juntos construir softwares mais expressivos e robustos! Até a próxima, galerinha.

Facades no Laravel entregam velocidade, mas cobram o preço em acoplamento

Meriéli Manzano — Thu, 14 May 2026 15:15:00 +0000

As Facades do Laravel são algo que o framework disponibiliza e que vejo muitos projetos usando em controllers, services, entities e até mesmo em repositories. Eu pessoalmente já usei e ainda uso Facade, a produtividade inicial é maravilhosa, o código fica enxuto e você entrega valor rápido porque não precisa instanciar, é só usar a Facade direto, é lindo.

Só que tenho refletido sobre uma coisa que não aparece no curto prazo, especialmente quando a aplicação cresce e a manutenção se estende por anos.

Pense num cenário real:

Você tem uma classe de serviço que usa várias outras Facades internas. Funciona perfeitamente bem, até o dia que você precisar reaproveitar aquela lógica num script isolado fora do Laravel. Ou testar aquela classe sem o framework inteiro carregado.

Aí você percebe: a classe não diz o que ela precisa. Você só descobre abrindo o código linha por linha. E cada facade é um fio invisível conectado ao Laravel.

Não é que Facade seja errada. É que elas resolvem um problema (velocidade) e criam outro silencioso (acoplamento implícito). Cada time escolhe seu trade-off. Esse acoplamento forte com o framework vai justamente contra as regras de dependência da Clean Architecture.

Para entender por que, precisamos saber que Facades do Laravel funcionam como “proxies estáticos” que fornecem acesso a objetos registrados no service container. São uma “ponte” entre uma chamada de método estático e a instância real de um objeto, resolvido em tempo de execução pelo container de injeção de dependência do Laravel.

Abaixo separei algumas vantagens e desvantagens que vai te ajudar a decidir quando realmente devemos usá-las.

Vantagens:

Código mais rápido de escrever e mais fácil de ler, acelerando drasticamente o desenvolvimento e a prototipagem.
Facilidade para testar usando shouldReceive() e Fakes para garantir que a lógica real não seja acionada, diferente de métodos estáticos tradicionais. “Obs: Mas já que a IA está criando testes com maestria, será que isso faz realmente a diferença?”
Tem comportamento Singleton, sendo resolvida uma única vez por requisição.
Pode ser usada em qualquer lugar, sem a necessidade de passar dependência manualmente pelo construtor.

Desvantagens:

Acoplamento que não quebra a testabilidade, mas suja as dependências “ou seja, não é declarada a dependência, ela fica implícita e só é descoberta olhando o corpo dos métodos”. O que dificulta manutenção e reuso.
Viola a Inversão de Dependência, a classe depende diretamente de uma implementação concreta ou de uma interface resolvida pela Facade, não de uma abstração definida pelo domínio, injetada de fora.
Lógica acoplada ao Framework, porque Facades só funcionam com o Facade Root inicializado. Se um dia pretender reutilizar aquela classe em um script isolado, pacote PHP puro ou outro framework, precisará reescrever tudo.
Por serem muito convenientes, facilitam a violação silenciosa do SRP: desenvolvedores adicionam novas responsabilidades indiretas sem que o construtor da classe sinalize o inchaço.

Deixo mais dois pontos de atenção que não são necessariamente desvantagens, mas devem ser conhecidos:

Embora sejam testáveis, os mocks são aplicados globalmente – afetam todas as chamadas à facade durante o teste, não apenas uma instância específica. Sem uma limpeza explícita (como clearResolvedInstances() no tearDown), pode haver vazamento de comportamento entre testes. É um ponto de atenção, mas contornável.
A facade não é mais rápida que a injeção direta. Cada chamada paga o custo do __callStatic() e da resolução da chave no container – é tecnicamente mais lenta, mas na prática você nunca vai medir essa diferença.

Facades são ótimas em Controllers, Commands, Jobs (camadas mais próximas da infra). E podem até ser usadas em protótipos e MVPs, são uma excelente escolha para garantir velocidade de entrega.

Já nas camadas de domínio, serviços de aplicação, objetos de valor, entidades... faz mais sentido injetar uma interface no construtor para desacoplar sua lógica de negócio.

Tá tudo bem usar Facades. Esse post não é uma regra. É só uma lente que eu peguei dos meus estudos e que, de vez em quando, me faz perguntar: “será que aqui vale a pena declarar a dependência?”

Fico curiosa pra saber como vocês lidam com isso. Já sentiu alguma dificuldade prática com Facades para testar, evoluir ou reaproveitar lógica? Ou acham que eliminar Facades do Laravel da camada de negócio é uma sofisticação desnecessária?

Produtividade com Testes e Vue usando VSCode

Meriéli Manzano — Mon, 26 Sep 2022 14:18:02 +0000

Criar testes bem organizados, separados e com uma boa descrição no Jest ou inserir toda estrutura inicial padrão de um componente Vue, pode ser verboso. Mas configurando o VS Code é possível inserir automaticamente toda pré-estrutura com a escrita de apenas uma palavra.

Desenvolvendo com o Visual Studio Code você pode turbinar sua produtividade de uma forma muito simples com Snippets!

Como funciona?

Os snippets salvos no seu VS Code geram códigos pré-definidos ao digitar uma determinada palavra escolhida na sua configuração.

Como criar um snippet

Com o VS Code aberto vá em File -> Preferences -> Configure User Snippets

Na paleta de comandos aberta digite a linguagem para qual deseja exibir o snippet, no caso de testes Jest digite typescript se for sua linguagem utilizada.

Será aberto um arquivo typescript.json com instruções para criar seu snippet.

Cada snippet tem a seguinte estrutura:

"Nome do Snippet": {
        "prefix": // Palavra que chama o snippet,
        "body": [
            // Corpo com o código a ser gerado         
        ],
        "description": // Descrição com detalhes do código
},

Ao escrever o body, em linhas que houver indentação use \t para aplicar a tabulação necessária. Cada \t representa um Tab.

Para indicar as pausas do Tab para digitação de texto pelo código use $1, substituindo o número pela ordem de inserção desejada em cada trecho.

Também é possível indicar o tipo de conteúdo a ser inserido em cada pausa com ${1:conteudo} dando uma ideia do que escrever. E para definir um texto igual a ser usado em várias partes do código use o mesmo número de ID em todas partes que o texto for repetir.

Abaixo montei um snippet completo para Jest usando BDD que você pode aproveitar nos seus códigos ou adaptar como preferir:

O snippet de Vue é para uso com composition Api usando Typescript e Sass scoped, mas você pode adaptar como preferir:

O artigo é para produtividade com Testes e Vue, mas também é possível criar snippets para outras linguagens.

Espero ter ajudado! 😊