Clean Architecture e Domain-Driven Design (DDD) no TypeScript: Arquitetura Enterprise Desacoplada
Compreenda a sinergia entre Clean Architecture e Domain-Driven Design (DDD) no desenvolvimento de software de alta complexidade com TypeScript: aprenda a isolar regras puras de negócio através das 4 camadas concêntricas de Uncle Bob, modelar Entidades e Value Objects imutáveis com tipagem estática e desacoplar Use Cases de controladores HTTP e bancos de dados.
📑 Índice do Conteúdo
1. O Desafio da Complexidade e a Arquitetura Limpa no TypeScript
Conforme aplicações corporativas crescem, um dos erros mais frequentes é misturar regras de negócio diretamente com bibliotecas de terceiros: rotas do Express/Fastify contendo queries SQL, componentes React executando chamadas de persistência ou regras fiscais acopladas aos decorators de um ORM específico (como Prisma ou TypeORM). Quando a equipe precisa trocar de banco de dados, atualizar o framework HTTP ou escrever testes unitários, a base de código revela-se excessivamente frágil.
A Clean Architecture (Arquitetura Limpa), proposta por Robert C. Martin, resolve esse impasse através de círculos concêntricos de abstração governados por uma diretriz irrevogável:
O fluxo de dependências do código-fonte deve sempre apontar de fora para dentro. As camadas mais internas (regras puras de negócio) nunca devem saber da existência das camadas mais externas (banco de dados, frameworks, UI ou bibliotecas de terceiros).
2. As Quatro Camadas Essenciais da Clean Architecture
- Enterprise Business Rules (Domínio / Entities): O coração do sistema. Contém as regras de negócio mais universais da empresa (Entidades e Value Objects). Deve ser escrito em TypeScript 100% puro, sem qualquer import de bibliotecas externas (nem mesmo decorators de ORMs).
- Application Business Rules (Casos de Uso / Use Cases): Implementa os fluxos operacionais específicos da aplicação (ex: “Cadastrar Novo Usuário”, “Finalizar Pagamento de Pedido”). Orquestra as entidades de domínio e comunica-se com a infraestrutura através de interfaces de repositórios e serviços.
- Interface Adapters (Controllers, Presenters & Gateways): Converte os dados entre o formato mais conveniente para os Casos de Uso e o formato externo (converte requisições HTTP REST/GraphQL para DTOs e vice-versa).
- Frameworks & Drivers (Infraestrutura): A camada mais volátil. Onde vivem as ferramentas concretas: PostgreSQL, Redis, Express, Fastify, Docker, clientes HTTP e drivers de envio de e-mail.
3. Conceitos Fundamentais do Domain-Driven Design (DDD)
Para estruturar o núcleo da camada de Domínio, adotamos os padrões estratégicos e táticos do DDD (Domain-Driven Design) criado por Eric Evans:
- Entidades (Entities): Objetos que possuem uma identidade única contínua (ex: um
iddo tipo UUID). Dois usuários com o mesmo nome e idade continuam sendo pessoas diferentes se seus IDs forem distintos. - Objetos de Valor (Value Objects): Objetos que não possuem identidade própria e são definidos unicamente pelos seus atributos. São imutáveis por natureza e contêm suas próprias regras de validação intrínseca (ex:
Email,Cpf,PrecoMonetario). - Erros de Domínio: Classes de exceção que expressam com exatidão a linguagem ubíqua do negócio (ex:
SaldoInsuficienteExceptionem vez de um genéricoError('Falha 400')).
4. Modelagem de um Value Object Imutável: Email
Veja como criar um Value Object com garantia estática de integridade. Nenhuma parte do sistema conseguirá criar uma instância de Email que contenha uma string vazia ou inválida:
export class EmailInvalidoError extends Error {
public constructor(emailFornecido: string) {
super(`O e-mail "${emailFornecido}" não atende aos padrões de formatação válidos.`);
this.name = 'EmailInvalidoError';
}
}
export class Email {
// 1. Membro privado e imutável
private readonly valor: string;
// 2. Construtor privado: instanciação controlada exclusivamente pelo factory method
private constructor(valorLimpo: string) {
this.valor = valorLimpo;
}
// 3. Factory method estático com validação de invariantes
public static criar(emailBruto: string): Email {
const sanitizado = emailBruto.trim().toLowerCase();
const regexEmail = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$/;
if (!regexEmail.test(sanitizado)) {
throw new EmailInvalidoError(emailBruto);
}
return new Email(sanitizado);
}
public getValor(): string {
return this.valor;
}
// 4. Igualdade estrutural (dois Value Objects com o mesmo valor são idênticos)
public igual(outro: Email): boolean {
return this.valor === outro.getValor();
}
}
5. Modelagem da Entidade de Domínio: ContaCliente
A entidade agrega comportamentos ricos do negócio. Em vez de permitir alterações aleatórias de propriedades públicas (o antipadrão de modelo de domínio anêmico), toda mutação é protegida por métodos de negócio explícitos:
export interface PropsContaCliente {
id: string;
nomeCompleto: string;
email: Email;
saldo: number;
ativo: boolean;
criadoEm: Date;
}
export class ContaCliente {
private props: PropsContaCliente;
public constructor(props: PropsContaCliente) {
if (props.saldo < 0) {
throw new Error('Uma conta não pode ser inicializada com saldo negativo.');
}
this.props = { ...props };
}
public get id(): string { return this.props.id; }
public get nome(): string { return this.props.nomeCompleto; }
public get email(): string { return this.props.email.getValor(); }
public get saldo(): number { return this.props.saldo; }
public get estaAtivo(): boolean { return this.props.ativo; }
// Regras de negócio encapsuladas
public depositar(valor: number): void {
if (valor
6. Caso de Uso (Use Case / Interactor) com DTOs Tipados
O Caso de Uso orquestra as operações da aplicação. Ele recebe um DTO tipado, valida regras em conjunto com o repositório e devolve outro DTO tipado de saída:
// DTOs de Entrada e Saída (Data Transfer Objects)
export interface AbrirContaInputDTO {
nome: string;
email: string;
depositoInicial: number;
}
export interface AbrirContaOutputDTO {
contaId: string;
saldoFinal: number;
mensagem: string;
}
// Contrato de Repositório desacoplado da tecnologia de persistência
export interface IContaClienteRepository {
buscarPorEmail(email: string): Promise;
salvar(conta: ContaCliente): Promise;
}
// O Caso de Uso
export class AbrirContaUseCase {
public constructor(
private readonly contaRepo: IContaClienteRepository
) {}
public async executar(input: AbrirContaInputDTO): Promise {
// 1. Criação do Value Object (validação intrínseca imediata)
const emailVO = Email.criar(input.email);
// 2. Regra de negócio: não permitir contas duplicadas para o mesmo e-mail
const existente = await this.contaRepo.buscarPorEmail(emailVO.getValor());
if (existente) {
throw new Error(`Já existe uma conta cadastrada para o e-mail: ${emailVO.getValor()}`);
}
// 3. Criação da entidade de domínio
const novaConta = new ContaCliente({
id: `acc_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`,
nomeCompleto: input.nome,
email: emailVO,
saldo: input.depositoInicial,
ativo: true,
criadoEm: new Date()
});
// 4. Persistência transparente
await this.contaRepo.salvar(novaConta);
return {
contaId: novaConta.id,
saldoFinal: novaConta.saldo,
mensagem: 'Conta aberta com sucesso no ecossistema enterprise!'
};
}
}
Observe que o código de
AbrirContaUseCase e ContaCliente não importa nenhuma biblioteca externa. Você pode rodar esse mesmo código no Node.js, Deno, Bun, Cloudflare Workers, em uma CLI de terminal ou em um app React Native sem alterar uma vírgula!
clean-architecture-simulacao.ts
// =====================================================================
// LAB: CLEAN ARCHITECTURE & DDD EM TYPESCRIPT PURO
// =====================================================================
// [Camada 1: Domínio - Value Object]
class Cpf {
private readonly valor: string;
private constructor(cpfLimpo: string) { this.valor = cpfLimpo; }
public static criar(raw: string): Cpf {
const limpo = raw.replace(/D/g, '');
if (limpo.length !== 11) {
throw new Error(`CPF inválido: esperado 11 dígitos, recebido ${limpo.length}`);
}
return new Cpf(limpo);
}
public formatado(): string {
return this.valor.replace(/(d{3})(d{3})(d{3})(d{2})/, '$1.$2.$3-$4');
}
}
// [Camada 1: Domínio - Entidade]
class MembroClube {
public constructor(
public readonly id: string,
public readonly nome: string,
public readonly cpf: Cpf,
public pontosFidelidade: number = 0
) {}
public creditarPontos(valorCompra: number): void {
const novosPontos = Math.floor(valorCompra / 10);
this.pontosFidelidade += novosPontos;
console.log(`[Domínio] +${novosPontos} pontos creditados. Total: ${this.pontosFidelidade}`);
}
}
// [Camada 2: Aplicação - Contrato de Repositório]
interface IMembroRepository {
salvar(membro: MembroClube): Promise;
buscarPorId(id: string): Promise;
}
// [Camada 4: Infraestrutura - Repositório em Memória]
class MembroRepositoryEmMemoria implements IMembroRepository {
private readonly banco = new Map();
public async salvar(membro: MembroClube): Promise {
this.banco.set(membro.id, membro);
}
public async buscarPorId(id: string): Promise {
return this.banco.get(id) || null;
}
}
// [Camada 2: Aplicação - Caso de Uso]
class AcumularPontosUseCase {
public constructor(private readonly repo: IMembroRepository) {}
public async executar(membroId: string, valorGasto: number): Promise {
const membro = await this.repo.buscarPorId(membroId);
if (!membro) {
throw new Error(`Membro com ID ${membroId} não foi localizado.`);
}
membro.creditarPontos(valorGasto);
await this.repo.salvar(membro);
return { saldoPontos: membro.pontosFidelidade };
}
}
// Simulação de Execução
async function executarDemonstracao() {
console.log('=== DEMONSTRAÇÃO CLEAN ARCHITECTURE & DDD ===');
const repo = new MembroRepositoryEmMemoria();
// 1. Criando Entidade com Value Object validado
const novoCpf = Cpf.criar('123.456.789-00');
const membro = new MembroClube('MBR-101', 'Renata Vasconcelos', novoCpf, 50);
await repo.salvar(membro);
console.log(`Membro cadastrado: ${membro.nome} (CPF: ${membro.cpf.formatado()})`);
console.log(`Pontuação inicial: ${membro.pontosFidelidade}`);
// 2. Executando Caso de Uso Desacoplado
const useCase = new AcumularPontosUseCase(repo);
const resultado = await useCase.executar('MBR-101', 450.00);
console.log(`nResultado da transação de fidelidade:`);
console.log(`Saldo atualizado de pontos: ${resultado.saldoPontos}`);
}
executarDemonstracao();
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE