Domain-Driven Design (DDD): como estruturar softwares complexos a partir do negócio
Um guia prático e rigoroso baseado na obra de Eric Evans para modelar softwares complexos usando Linguagem Ubíqua, Bounded Contexts, Agregados, Entidades e Arquitetura em Camadas.

Sumário deste guia
Por Matheus Lobo — CTO e Software Engineer
A maior ameaça a um software corporativo de longa vida raramente é a escolha do banco de dados ou a sintaxe do framework. A principal causa de degradação é o descompasso entre a complexidade do negócio real e a estrutura do código. Quando o modelo de software não reflete o modelo mental dos especialistas que operam a empresa, cada mudança exige tradução, cada refatoração gera regressão e o sistema se torna um emaranhado de regras espalhadas.
Em 2003, Eric Evans formalizou em sua obra clássica (Domain-Driven Design: Tackling Complexity in the Heart of Software) uma abordagem sistemática para combater essa entropia. O Domain-Driven Design (DDD) não é um padrão de código nem um conjunto de regras para frameworks ORM: é uma disciplina de modelagem e arquitetura orientada ao coração do negócio. Este guia disseca os pilares estratégicos e táticos do DDD clássico, eliminando mitos comuns e oferecendo um caminho prático para aplicação real.
Resumo executivo
- O foco é a complexidade do domínio: O DDD só paga seu custo em softwares onde as regras de negócio são intrinsecamente complexas. Para CRUDs simples, a abordagem traz sobre-engenharia desnecessária.
- Design Estratégico antes do Design Tático: Dividir o sistema em Contextos Delimitados (Bounded Contexts) e unificar o vocabulário através da Linguagem Ubíqua é mais vital do que criar classes de Entidades.
- Linguagem Ubíqua não é glossário: É uma linguagem rigorosa falada por especialistas do negócio e desenvolvedores, expressa diretamente no código, nomes de métodos, testes e eventos.
- Contextos Delimitados fixam significados: A palavra "Cliente" tem atributos e comportamentos completamente diferentes na Vendas, na Logística e no Faturamento. Tentar criar um modelo único universal para a empresa inteira é uma ilusão catastrófica.
- Agregados definem limites transacionais: Um Agregado é um grupo de Entidades e Objetos de Valor modificados como uma única unidade de consistência atômica, protegidos pela Raiz do Agregado (Aggregate Root).
- Repositórios operam apenas sobre Raízes de Agregados: Não se criam repositórios para todas as tabelas do banco. Apenas a Raiz do Agregado possui repositório próprio.
- Isolamento via Arquitetura em Camadas: O Domínio é o centro do software e não possui dependências de frameworks, interfaces gráficas ou bancos de dados. A infraestrutura é um detalhe externo acoplado via inversão de dependência.
O problema central: complexidade essencial vs. complexidade acidental
Fred Brooks, em seu célebre ensaio No Silver Bullet, dividiu a complexidade do software em duas categorias:
- Complexidade Acidental: Dificuldades decorrentes das ferramentas, linguagens, configurações de servidores e detalhes de infraestrutura.
- Complexidade Essencial: A complexidade inerente ao problema de negócio que o software se propõe a resolver.
Muitas equipes gastam meses otimizando complexidade acidental (trocando de biblioteca de UI ou refazendo pipelines de build), enquanto deixam a complexidade essencial desamparada. O resultado é o modelo anêmico ou o monólito de regras confusas, onde regras fiscais, validações de crédito e cálculos de frete se misturam em controladores HTTP.
O DDD direciona o foco da engenharia para a complexidade essencial. Ele prega que o código deve ser uma projeção direta do modelo de domínio criado em colaboração contínua entre engenheiros e especialistas de domínio (Domain Experts).
Design Estratégico: a visão macro do negócio
Antes de criar classes ou tabelas, o DDD exige compreender como a empresa se estrutura e como a informação flui entre áreas.
1. Linguagem Ubíqua (Ubiquitous Language)
A Linguagem Ubíqua é a espinha dorsal do DDD. Não se trata de uma tradução entre "linguagem de negócios" e "linguagem de TI". Trata-se de uma linguagem única, rigorosa e inequívoca compartilhada por toda a equipe.
Se o especialista em logística fala "despachar pedido" e o código contém o método Order.setStatus(4), a linguagem ubíqua foi quebrada. Se a equipe de vendas fala em "proposta aceita" e o banco de dados armazena is_active = true, há ruído de tradução.
Regras da Linguagem Ubíqua:
- Falada em reuniões, escrita em documentações e codificada em nomes de classes, métodos, variáveis e testes.
- Se um termo mudar no negócio, ele deve mudar no código. Se um termo for ambíguo no código, a discussão com o especialista deve esclarecê-lo.
- Não aceita jargões puramente técnicos no coração do domínio (como
OrderDTOManagerouProcessPayload).
2. Contextos Delimitados (Bounded Contexts)
Um dos erros mais devastadores em arquitetura corporativa é a tentativa de criar um "Modelo Único de Dados" para toda a empresa. Na prática, a palavra "Cliente" tem significados irreconciliáveis dependendo do departamento:
- No Contexto de Vendas: Cliente é um Lead com score de crédito, histórico de contatos e perfil de consumo.
- No Contexto de Logística: Cliente é apenas um nome e um Endereço de Entrega com restrições de horário.
- No Contexto Financeiro: Cliente é uma Razão Social com CNPJ, limite de crédito e dados de faturamento.
Forçar todos esses atributos dentro de uma única classe Customer resulta em um objeto monstruoso, cheio de campos nulos e condicionais infinitas.
O Bounded Context (Contexto Delimitado) estabelece a fronteira explícita dentro da qual um modelo de domínio se aplica rigorosamente. Dentro do Bounded Context de Logística, a classe Cliente contém apenas o que a logística necessita.
O mesmo conceito ('Pedido') possui modelos e significados distintos em cada contexto. A camada anticorrupção (ACL) evita que o modelo interno seja poluído por esquemas externos.
3. Mapeamento de Contextos (Context Mapping)
Sistemas reais possuem múltiplos Bounded Contexts que precisam se comunicar. Eric Evans definiu os padrões de relacionamento entre contextos:
- Shared Kernel (Núcleo Compartilhado): Dois contextos compartilham um pequeno subconjunto do modelo e código. Exige alinhamento constante entre equipes.
- Customer-Supplier (Cliente-Fornecedor): O contexto fornecedor precisa adaptar suas entregas às necessidades do contexto cliente.
- Conformist (Conformista): O contexto cliente aceita o modelo do contexto fornecedor como ele é, sem adaptação.
- Anti-Corruption Layer (ACL - Camada Anticorrupção): Uma camada tradutora que isola um contexto moderno de um modelo legado ou externo mal desenhado, garantindo que conceitos poluídos não entrem no domínio limpo.
- Open Host Service / Published Language: O contexto fornecedor provê um protocolo de integração aberto (como uma API REST bem versionada) e uma linguagem de publicação (como JSON/Protobuf) para múltiplos consumidores.
Design Tático: os blocos de construção do modelo
Enquanto o Design Estratégico organiza os limites da aplicação, o Design Tático fornece os padrões de modelagem orientada a objetos para implementar as regras de negócio dentro de cada Bounded Context.
1. Entidades (Entities)
Uma Entidade é um objeto definido por sua identidade contínua e não por seus atributos. Mesmo que todos os atributos de uma Entidade mudem com o tempo, ela continua sendo a mesma Entidade por conta de seu identificador único.
Exemplo: Um Usuario com ID usr_9812 continua sendo a mesma entidade mesmo se alterar seu nome, e-mail e endereço.
# Exemplo conceitual de Entidade em Python
from dataclasses import dataclass
from uuid import UUID
@dataclass
class Usuario:
id: UUID
nome: str
email: "Email" # Objeto de Valor
def alterar_email(self, novo_email: "Email") -> None:
"""Garante a regra de negócio para atualização de e-mail."""
self.email = novo_email
def __eq__(self, outro: object) -> bool:
"""Uma Entidade é identificada unicamente pelo seu ID, não por atributos."""
if not isinstance(outro, Usuario):
return False
return self.id == outro.id
def __hash__(self) -> int:
return hash(self.id)
2. Objetos de Valor (Value Objects)
Um Objeto de Valor (Value Object) é um objeto imutável definido exclusivamente pelo valor de seus atributos. Ele não possui identidade própria. Dois Objetos de Valor com os mesmos atributos são considerados absolutamente idênticos.
Exemplos de Objetos de Valor: CPF, Email, Endereço, Dinheiro (composto por valor e moeda).
Propriedades fundamentais dos Value Objects:
- Imutabilidade: Nunca modifique o estado interno de um Value Object. Para alterá-lo, retorne uma nova instância (
frozen=True). - Validação na Criação: Um Value Object não pode existir em estado inválido. Se o valor for inválido, o construtor dispara uma exceção em
__post_init__. - Enriquecimento do Domínio: Substitui tipos primitivos (
str,float) por tipos expressivos de negócio.
# Exemplo conceitual de Objeto de Valor em Python
from dataclasses import dataclass
from typing import Literal
@dataclass(frozen=True)
class Dinheiro:
quantia: float
moeda: Literal["BRL", "USD"] = "BRL"
def __post_init__(self) -> None:
# Invariante de negócio: validação na criação do Value Object
if self.quantia < 0:
raise ValueError("Quantia monetária não pode ser negativa.")
def somar(self, outro: "Dinheiro") -> "Dinheiro":
if self.moeda != outro.moeda:
raise ValueError(f"Não é possível somar moedas diferentes: {self.moeda} e {outro.moeda}.")
return Dinheiro(quantia=self.quantia + outro.quantia, moeda=self.moeda)
3. Agregados e Raízes de Agregados (Aggregates & Aggregate Roots)
Um Agregado é o conceito mais vital e frequentemente mal compreendido do Design Tático. Trata-se de um conjunto de Entidades e Objetos de Valor associados que são tratados como uma unidade de consistência transacional.
Regras de Ouro dos Agregados:
- A Raiz do Agregado (Aggregate Root): É a única Entidade do Agregado com a qual o mundo externo pode se comunicar diretamente.
- Referência Exclusiva por ID: Nenhum objeto fora do Agregado pode manter uma referência direta para Entidades internas do Agregado; ele deve guardar apenas o ID da Raiz.
- Consistência Atômica: Qualquer alteração no Agregado deve ser salva no banco em uma única transação atômica. Se um
Pedidotem 5Itens, alterar um item exige carregar oPedido, executar o método noPedidoe salvar oPedido. - Proteção de Invariantes: A Raiz é responsável por garantir que nenhuma regra de negócio seja violada durante as mutações.
# Exemplo de Raiz do Agregado protegendo invariantes em Python
from dataclasses import dataclass, field
from typing import List
from uuid import UUID
@dataclass
class ItemPedido:
produto_id: UUID
quantidade: int
preco_unitario: Dinheiro
@dataclass
class Pedido:
id: UUID
cliente_id: UUID
itens: List[ItemPedido] = field(default_factory=list)
status: str = "RASCUNHO"
def adicionar_item(self, produto_id: UUID, quantidade: int, preco: Dinheiro) -> None:
"""Protege as invariantes do Agregado durante mutações."""
if self.status != "RASCUNHO":
raise ValueError("Não é possível alterar um pedido já finalizado.")
if quantidade <= 0:
raise ValueError("A quantidade do item deve ser maior que zero.")
self.itens.append(ItemPedido(produto_id, quantidade, preco))
@property
def valor_total(self) -> Dinheiro:
if not self.itens:
return Dinheiro(quantia=0.0)
moeda = self.itens[0].preco_unitario.moeda
total = sum(item.preco_unitario.quantia * item.quantidade for item in self.itens)
return Dinheiro(quantia=total, moeda=moeda)
Objetos externos referenciam apenas a Raiz do Agregado. Mudanças internas acontecem como uma unidade transacional atômica.
Value Object imutável
4. Repositórios (Repositories)
Na visão do DDD, um Repositório simula uma coleção de Raízes de Agregado armazenada em memória.
Diferença crucial: Não se criam "Repositories" para todas as tabelas ou objetos. Se ItemPedido faz parte do Agregado Pedido, NÃO existe ItemPedidoRepository. Existe apenas PedidoRepository. O acesso a qualquer ItemPedido é feito através da Raiz Pedido.
# Exemplo de Interface de Repositório em Python usando ABC
from abc import ABC, abstractmethod
from typing import Optional
from uuid import UUID
class PedidoRepository(ABC):
@abstractmethod
def buscar_por_id(self, pedido_id: UUID) -> Optional[Pedido]:
"""Recupera a Raiz do Agregado Pedido pelo seu ID único."""
pass
@abstractmethod
def salvar(self, pedido: Pedido) -> None:
"""Persiste atomicamente o estado da Raiz do Agregado Pedido."""
pass
5. Serviços de Domínio (Domain Services)
Nem toda operação de negócio pertence naturalmente a uma Entidade ou Objeto de Valor. Quando um processo envolve múltiplos Agregados ou uma transformação stateless, ele deve ser modelado como um Serviço de Domínio.
Cuidado: Não confunda Serviços de Domínio com Serviços de Aplicação. O Serviço de Domínio contém regras puras de negócio (ex: cálculo de imposto interestadual complexo). O Serviço de Aplicação orquestra o fluxo (carrega o repositório, chama o serviço de domínio, salva e envia notificação).
6. Eventos de Domínio (Domain Events)
Um Evento de Domínio captura algo relevante que ocorreu no passado do negócio. Exemplos: PedidoPagoEvent, ContaBloqueadaEvent.
Eventos de domínio são fundamentais para desacoplar Agregados. Em vez de o Agregado Pedido chamar diretamente a Logística ou o Estoque, ele dispara um evento PedidoFaturadoEvent, permitindo que outros contextos reajam assincronamente.
Arquitetura em Camadas (Layered Architecture)
Para proteger o Modelo de Domínio de contaminações tecnológicas, o DDD promove uma clara separação em quatro camadas conceituais:
- Camada de Apresentação (UI / API Layer): Controladores HTTP, rotas GraphQL, interfaces gráficas. Responsável por interpretar requisições externas e formatar respostas.
- Camada de Aplicação (Application Layer): Casos de uso da aplicação. Não contém regras de negócio. Responsável por orquestrar transações, segurança e repositórios.
- Camada de Domínio (Domain Layer): O coração do software. Contém Entidades, Value Objects, Serviços de Domínio e interfaces de Repositórios. Zero dependência de infraestrutura.
- Camada de Infraestrutura (Infrastructure Layer): Implementações concretas de bancos de dados (Prisma, TypeORM), clientes HTTP, envio de e-mails e filas.
O Domínio é o núcleo do sistema e não depende de banco, frameworks ou interfaces. A Infraestrutura implementa as interfaces definidas pelo Domínio.
Pelo princípio da Inversão de Dependência (DIP), a Camada de Domínio define a interface do Repositório (ex: PedidoRepository), enquanto a Camada de Infraestrutura fornece a implementação concreta (ex: PostgresPedidoRepository). O Domínio nunca importa a Infraestrutura.
Armadilhas e Maus Usos Frequentes do DDD
Aplicar DDD sem critério pode paralisar um projeto. As armadilhas mais comuns incluem:
1. O Modelo de Domínio Anêmico (Anemic Domain Model)
Trata-se do antipadrão onde Entidades são meras estruturas de dados com getters e setters públicos, sem comportamento algum, enquanto toda a lógica fica espalhada em classes chamadas OrderService. Isso destrói o encapsulation do DDD. Entidades devem ter métodos de negócio expressivos (ex: pedido.cancelar(motivo) em vez de pedido.setStatus("CANCELADO")).
2. Agregados Gigantescos
Criar um Agregado Empresa que contém todos os Funcionarios, Projetos e Clientes causará sérios gargalos de concorrência e memória. Agregados devem ser tão pequenos quanto possível, mantendo apenas a fronteira de consistência atômica estritamente necessária.
3. Dogmatismo para CRUDs Simples
Se uma aplicação consiste apenas em ler do banco e exibir na tela sem validações complexas ou transações de negócio, tentar aplicar DDD integralmente resultará em dezenas de interfaces e adaptadores inúteis. Use a ferramenta certa para o problema certo.
Perguntas frequentes
O que é Domain-Driven Design (DDD) em termos simples?
DDD é uma abordagem de desenvolvimento de software onde a estrutura e o código da aplicação são diretamente moldados pelas regras, terminologias e processos do negócio real, em colaboração contínua com especialistas da área.
Qual a diferença entre Entidade e Objeto de Valor (Value Object)?
Uma Entidade possui uma identidade única e contínua que perdura no tempo (como um Usuário ou Pedido), enquanto um Objeto de Valor é imutável e definido apenas pelos seus atributos (como um CPF, E-mail ou Endereço).
O que é um Bounded Context (Contexto Delimitado)?
É uma fronteira explícita dentro da qual um determinado modelo de domínio se aplica. O mesmo termo (como "Cliente") pode ter propriedades e comportamentos totalmente diferentes em Contextos Delimitados distintos (como Vendas vs. Logística).
Devo usar DDD em todos os meus projetos de software?
Não. O DDD agrega valor em projetos com alta complexidade de regras de negócio. Em aplicações simples, como CRUDs ou painéis administrativos básicos, o DDD introduz complexidade desnecessária.
Qual a relação entre DDD, Clean Architecture e Arquitetura Hexagonal?
Todas compartilham o mesmo princípio central: isolar as regras de negócio (Domínio) do mundo externo e de detalhes de infraestrutura (bancos de dados, frameworks, UI), garantindo testabilidade e manutenibilidade.
Sua decisão precisa de evidência, não de promessa.
Quer aplicar os princípios de engenharia ao seu negócio? A Korventi ajuda a transformar processo, restrição e objetivo em uma direção técnica mensurável.
Conversar sobre um projetoFontes primárias
- EVANS, Eric. Domain-Driven Design: Tackling Complexity in the Heart of Software. Addison-Wesley Professional, 2003.
- VERNON, Vaughn. Implementing Domain-Driven Design. Addison-Wesley Professional, 2013.
- FOWLER, Martin. Anemic Domain Model. Refactoring.com, 2003.
- BROOKS, Frederick P. No Silver Bullet — Essence and Accident in Software Engineering. IEEE Computer, 1987.


