Clean Architecture e DDD no TypeScript: Guia Prático
⚡ Curso de TypeScript • Web-ZoneWare

Clean Architecture e Domain-Driven Design (DDD) no TypeScript: Arquitetura Enterprise Desacoplada

Lição 48 de 50

Clean Architecture e Domain-Driven Design (DDD) no TypeScript: Arquitetura Enterprise Desacoplada

⚡ Módulo 6 • Aula 48 de 50

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.

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:

🎯

A Regra da Dependência (The Dependency Rule):
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

  1. 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).
  2. 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.
  3. 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).
  4. 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 id do 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: SaldoInsuficienteException em vez de um genérico Error('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:

TypeScript 37 linhas
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:

TypeScript 28 linhas
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:

TypeScript 55 linhas
// 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!'
        };
    }
}
🏆

Independência de Frameworks:
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!

TypeScript 5.0+
clean-architecture-simulacao.ts
TypeScript 96 linhas
// =====================================================================
// 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();
🛠️ Laboratório Prático & Prática Imediata

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.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground 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
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima