DEV Community: Meriéli Manzano

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! 😊