DEV Community: Humberto Barbosa

Promises em Nodejs Paralelo, Sequencial e Corrida – Qual usar?

Humberto Barbosa — Sat, 19 Jul 2025 00:41:07 +0000

Promises em Node.js: Paralelo, Sequencial e Corrida – Como Escolher?

Em JavaScript (e especialmente no Node.js), Promises são uma das ferramentas mais poderosas para trabalhar com código assíncrono — aquele que não bloqueia o fluxo principal enquanto espera por uma resposta, como uma chamada de API ou leitura de arquivo.

Mas… quando você tem várias Promises ao mesmo tempo, como decidir a melhor forma de executá-las?

Neste artigo, vamos explorar os três padrões mais importantes para isso:

Execução Paralela
Execução Sequencial
Corrida (Race Condition)

E sim, vou te mostrar com exemplos práticos e simples como isso funciona.

🧠 Antes de tudo: o que é uma Promise?

Uma Promise é um objeto que representa a eventual conclusão (ou falha) de uma operação assíncrona. Em outras palavras, ela promete que vai te dar um resultado.

Você pode "esperar" por esse resultado com await, ou então usar .then() e .catch().

🔧 Função base para nosso exercício

Vamos criar uma função que simula uma tarefa assíncrona com um setTimeout. Ela simplesmente "resolve" com um valor depois de um tempo:

function promiseWithDelay(value, delay) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(`Valor: ${value}, Delay: ${delay}ms`);
    }, delay);
  });
}

Exemplo de uso:

promiseWithDelay("A", 3000).then(console.log); 
// → Valor: A, Delay: 3000ms (após 3 segundos)

🟩 Execução Paralela (Parallel)

Quando queremos executar várias Promises ao mesmo tempo e esperar todas terminarem juntas, usamos Promise.all().

Exemplo:

async function executarParalelo() {
  const resultados = await Promise.all([
    promiseWithDelay("A", 1000),
    promiseWithDelay("B", 5000),
    promiseWithDelay("C", 3000),
  ]);

  console.log("Execução Paralela Finalizada:", resultados);
}

O que acontece aqui?

As três Promises são iniciadas ao mesmo tempo
A função espera todas terminarem
O tempo total é do item mais lento

Resultado:

(espera 5 segundos)
Execução Paralela Finalizada: [
  'Valor: A, Delay: 1000ms',
  'Valor: B, Delay: 5000ms',
  'Valor: C, Delay: 3000ms'
]

Execução Sequencial (Sequential)

Às vezes, você quer rodar Promises em ordem, uma de cada vez. Isso é útil quando o segundo depende do resultado do primeiro.

Exemplo:

async function executarSequencial() {
  const resultado1 = await promiseWithDelay("A", 1000);
  const resultado2 = await promiseWithDelay("B", 5000);
  const resultado3 = await promiseWithDelay("C", 3000);

  console.log("Execução Sequencial Finalizada:", [
    resultado1,
    resultado2,
    resultado3,
  ]);
}

O que acontece?

Espera o primeiro terminar (A)
Só então executa o segundo (B)
Depois, o terceiro (C)
O tempo total = soma dos delays (9 segundos neste caso)

Corrida (Race)

E se você quiser só o primeiro resultado que chegar e ignorar o resto? Use Promise.race().

Exemplo:

async function executarCorrida() {
  const resultado = await Promise.race([
    promiseWithDelay("A", 1000),
    promiseWithDelay("B", 5000),
    promiseWithDelay("C", 3000),
  ]);

  console.log("Corrida Finalizada. Vencedor:", resultado);
}

Resultado:

(espera 1 segundo)
Corrida Finalizada. Vencedor: Valor: A, Delay: 1000ms

Quem chegar primeiro, ganha. Simples assim!

🧪 Testando os três modos

Vamos chamar os três juntos e ver o comportamento:

async function testarTodos() {
  executarCorrida();
  executarParalelo();
  executarSequencial();
}

testarTodos();

Mesmo sendo chamados na mesma ordem, a corrida terminará primeiro, seguida da execução paralela, e por último a sequencial.

Quando usar cada um?

Caso real	Qual usar?
Carregar 3 dados de API ao mesmo tempo	Paralelo
Passo 1: Login → Passo 2: Pegar token → Passo 3: Dados	Sequencial
Testar 3 URLs e usar a primeira que responder	Corrida (Race)

Conclusão

Quando falamos de Promises em Node.js, a forma como você organiza suas execuções faz toda a diferença no desempenho e no comportamento do seu código.

Lembre-se:

Promise.all() → tudo junto (paralelo)
await em sequência → um por vez (sequencial)
Promise.race() → quem chegar primeiro vence (corrida)

Use o tipo certo de execução para otimizar seus fluxos assíncronos. E se quiser explorar mais, experimente mudar os tempos de delay e veja como isso impacta a execução.

Integração Correios para Rastreamento de Entregas: Arquitetura Escalável com NestJS e Kafka

Humberto Barbosa — Thu, 15 May 2025 12:12:50 +0000

Introdução

Nos sistemas de e-commerce e da logística, rastrear o status de entregas é essencial para garantir transparência e agilidade no atendimento ao cliente. Automatizar esse processo com integração direta aos Correios é um desafio que envolve lidar com APIs externas, mapeamento de status inconsistentes e atualização em tempo real.

Neste artigo, vamos apresentar uma abordagem completa para orquestração de rastreamento de pedidos usando NestJS, aplicando os princípios de Clean Architecture, testes unitários robustos e integração com mensageria (Kafka).

Desenho da Solução

A solução gira em torno do caso de uso TrackingOrderStatusService, responsável por:

Consultar configurações de contas com rastreamento ativo;
Buscar os pedidos com status finalizados que devem ser atualizados;
Integrar com a API dos Correios via ProviderTrackingApiGateway;
Filtrar eventos novos não registrados;
Mapear os eventos para um modelo interno de status;
Persistir os novos eventos no repositório;
Emitir mensagens Kafka sobre mudanças de status;
Registrar novos status desconhecidos para posterior mapeamento.

Pontos de Complexidade

1. Identificação de Status

A API dos Correios utiliza uma combinação de codigo e tipo para representar eventos. Essa combinação foi padronizada com o helper:

export function buildPartnerStatusId(codigo: string, tipo: string): string {
  return `${codigo}${tipo}`;
}

Isso garante que qualquer ponto do sistema que precise identificar unicamente um status tenha uma forma unificada, reduzindo erros e facilitando o mapeamento.

2. Detecção de Eventos Novos

Para evitar a reprocessamento de eventos já persistidos, usamos o método getNewHistories. Ele compara os eventos vindos dos Correios com os eventos já salvos no histórico:

private getNewHistories(tracking: TrackingData[], eventos: CorreiosEventoDTO[]): CorreiosEventoDTO[] {
  return eventos.filter(evento => !this.historyExists(evento, tracking));
}

E o historyExists compara tanto o código concatenado quanto a data:

private historyExists(evento: CorreiosEventoDTO, tracking: TrackingData[]): boolean {
  return tracking.some(hist => {
    return (
      hist.partner.statusCode === buildPartnerStatusId(evento.codigo, evento.tipo) &&
      compareDates(hist.eventDate, evento.dtHrCriado)
    );
  });
}

3. Fallback para Status Não Mapeados

Se um evento dos Correios não tem status mapeado, salvamos esse status para posterior análise e notificamos por Kafka:

if (!statusMapped) {
  const newStatusPartner = new StatusCodePartner({ statusId, status });
  await this.statusCodePartnerRepository.save(newStatusPartner);

  await this.messageProvider.sendMessage({
    topic: KAFKA_TOPIC_FREIGHT_STATUS_CODE_PARTNER_NOT_FOUND,
    messages: [{
      key: JSON.stringify({ id: newStatusPartner.id }),
      value: { data: { ... } },
    }],
    headers: { 'X-Tenant-Id': accountId, 'X-Correlation-Id': randomUUID() },
  });
}

4. Resiliência e Logging

Todas as etapas do processo possuem logging contextualizado:

this.logger.log({
  id: 'TrackingOrderStatusService.trackingOrders',
  message: `[${tracking.accountId}|${tracking.order.internalOrderId}] Evento processado com sucesso.`,
});

Além disso, exceções são capturadas e logadas para facilitar troubleshooting:

catch (error) {
  this.logger.error({
    id: 'TrackingOrderStatusService.execute',
    message: error.message,
    stack: error.stack,
  });
}

Abstração via API Gateway

Outro destaque importante da implementação é o uso do ProviderTrackingApiGateway, uma interface que abstrai o consumo da API dos Correios. Ao invés de depender diretamente de chamadas HTTP acopladas no serviço, a integração é feita via uma porta definida por contrato:

export interface ProviderTrackingApiGateway {
  getTracking(etiqueta: string, cep: string): Promise<CorreiosApiResponseTrackingStatus>;
}

Essa abordagem segue o princípio da Inversão de Dependência (DIP), permitindo:

Substituir facilmente a implementação por mocks em testes unitários:

correiosApiGateway = mock<ProviderTrackingApiGateway>();
correiosApiGateway.getTracking.mockResolvedValue(mockCorreiosTrackingResponse);

Trocar facilmente a origem do rastreamento (ex: transportadoras privadas) sem alterar o caso de uso
Reduzir acoplamento e facilitar manutenção, pois a lógica de orquestração não precisa conhecer detalhes de implementação HTTP, headers ou autenticação

Essa separação clara entre camada de aplicação e infraestrutura melhora a testabilidade e prepara o código para cenários mais complexos.

Boas Práticas Adotadas

Inversão de dependência via tokens de injeção;
Separacão de responsabilidades (cada provider tem uma única função);
Logging com identificadores contextuais ([accountId|orderId]);
Utilização de Promise.all para operações paralelas (status + configuração);
Mensagens Kafka emitidas apenas para eventos novos.

Testes Unitários

🧪 Exemplo de Teste com Gateway Mockado

Abaixo está um exemplo real de como o ProviderTrackingApiGateway pode ser simulado em testes unitários usando jest-mock-extended:

import { mock, MockProxy } from 'jest-mock-extended';
import { ProviderTrackingApiGateway } from '../../correios/interfaces/provider-tracking-api-gateway';
import { CorreiosApiResponseTrackingStatus } from '../../correios/interfaces/provider-tracking-api-gateway';

describe('TrackingOrderStatusService – Integração com Correios API', () => {
  let correiosApiGateway: MockProxy<ProviderTrackingApiGateway>;

  beforeEach(() => {
    correiosApiGateway = mock<ProviderTrackingApiGateway>();
  });

  it('deve retornar eventos simulados dos Correios via gateway mockado', async () => {
    const mockCorreiosResponse: CorreiosApiResponseTrackingStatus = {
      objetos: [
        {
          codObjeto: 'XYZ123456BR',
          dtPrevista: new Date('2025-04-25T18:00:00Z'),
          modalidade: 'F',
          peso: 1.2,
          formato: 'Pacote',
          eventos: [
            {
              codigo: 'BDE',
              tipo: '01',
              dtHrCriado: new Date('2025-04-21T14:00:00Z'),
              descricao: 'Objeto entregue ao destinatário',
            },
          ],
        },
      ],
    };

    correiosApiGateway.getTracking.mockResolvedValue(mockCorreiosResponse);

    const result = await correiosApiGateway.getTracking('XYZ123456BR', '12345');

    expect(result.objetos[0].codObjeto).toBe('XYZ123456BR');
    expect(result.objetos[0].eventos[0].codigo).toBe('BDE');
  });
});

Esse mock garante que o ApiGateway esteja isolado e testável sem fazer chamadas reais, permitindo simular qualquer tipo de retorno da API externa.

Para garantir a qualidade e a confiabilidade da lógica, foram adicionados testes com jest-mock-extended para:

getAllStatusMapped: mapeamento correto e fallback para status desconhecidos;
getNewHistories: detecção de eventos novos;
historyExists: comparação exata por status e data;
trackingOrders e execute: cenários completos de sucesso e falha.

Lições Aprendidas

Pequenos helpers como buildPartnerStatusId e compareDates reduzem bugs e aumentam reutilização;
Separar persistência de envio em sendMessageStatusNotFound tornou o código mais testável e legível;
Centralizar a orquestração no caso de uso facilita extensão para outras transportadoras;
Cobertura de testes auxilia na manutenção sem medo de regressão.

Conclusão

A solução apresentada mostra como é possível construir uma integração robusta com os Correios utilizando boas práticas de arquitetura, testes e logging. Além de resolver o problema imediato de rastreamento, essa abordagem serve como base para integração com outros parceiros logísticos.

Essa implementação está pronta para produção, observável e fácil de evoluir.

Evitando Erros de Índice Único (E11000) ao Usar findOneAndUpdate com upsert no Mongoose

Humberto Barbosa — Sat, 26 Apr 2025 23:29:00 +0000

Como garantir unicidade de remessas em sistemas multi-tenant no MongoDB? Entenda por que erros E11000 acontecem, como alinhar filtros de upsert com índices únicos e evite armadilhas clássicas em modelagem de dados para operações críticas.

✅ Cenário

Imagine um sistema de gestão de entregas com múltiplos clientes (empresas) utilizando a mesma plataforma. Cada cliente (representado por um tenantId) possui seus próprios pedidos internos (clientOrderId), que podem coincidir entre diferentes clientes, mas não dentro do mesmo cliente.

Cada pedido tem uma única remessa associada, representada por um shipment com informações como nota fiscal, status e dados logísticos.

Você precisa garantir que haja apenas uma remessa por pedido e por cliente — e que atualizações venham a sobrescrever remessas existentes se o pedido já existir.

💾 Estrutura simplificada dos dados

@Schema({
  collection: 'shipments',
  timestamps: true
}) export class ShipmentEntity extends Document {@Prop({
    type: String,
    required: true
  }) tenantId: string;@Prop({
    type: String,
    required: true
  }) clientOrderId: string;@Prop({
    type: String,
    required: true
  }) invoiceNumber: string;@Prop({
    type: String,
    required: true
  }) status: string;@Prop({
    type: Date,
  default:
    Date.now
  }) updatedAt:
  Date;
}

🔐 Definindo o índice único

Para garantir unicidade por cliente + pedido:

ShipmentSchema.index(   { tenantId: 1, clientOrderId: 1 },   { unique: true }, );

Esse índice impede que existam dois documentos com a mesma combinação tenantId e clientOrderId.

📈 O Risco pro negocio

Quando pensamos em unicidade de remessas, não é só uma questão de evitar erros técnicos como o E11000.
É sobre proteger a integridade operacional do sistema.

Se um pedido tiver duas remessas associadas por erro, as consequências podem incluir:

Faturamento duplicado: o cliente pode ser cobrado duas vezes pelo mesmo pedido.
Erro logístico: o centro de distribuição pode despachar duas cargas separadas para o mesmo destino.
Problemas fiscais: inconsistência nas notas fiscais emitidas pode gerar multas ou retrabalho junto à Receita.
Perda de confiança: clientes empresariais esperam precisão; falhas assim corroem a relação de confiança.

Ou seja:
Definir corretamente a unicidade dos dados não é só uma questão técnica — é uma salvaguarda para a operação e para o relacionamento com o cliente.

❌ O erro clássico: E11000

Se você tentar fazer um findOneAndUpdate assim:

this.shipmentModel.findOneAndUpdate({clientOrderId: shipment.clientOrderId, invoiceNumber: shipment.invoiceNumber}, { $set: shipment }, { new: true, upsert: true });

Pode falhar com o erro:

E11000 duplicate key error collection: logistics.shipments index: tenantId_1_clientOrderId_1 dup key: { tenantId: "tenantA", clientOrderId: "12345" }

Isso ocorre porque o filtro ignora tenantId, violando a restrição única definida pelo índice.

✅ Solução: usar o filtro certo

await this.shipmentModel.findOneAndUpdate({tenantId: shipment.tenantId,clientOrderId: shipment.clientOrderId}, { $set: shipment }, { new: true, upsert: true } );

Agora o upsert respeita a chave única, atualizando corretamente se já houver uma remessa com o mesmo pedido para o mesmo cliente, ou criando um novo registro caso contrário.

🧠 Conclusão

Quando trabalhamos com upsert no MongoDB, é fundamental que o filtro usado esteja alinhado com o índice único que definimos. No caso que discutimos, isso significa sempre usar tenantId e clientOrderId juntos. Se você esquecer um deles ou misturar outros campos, como invoiceNumber, pode acabar quebrando a unicidade e gerando erros difíceis de diagnosticar.

É importante lembrar que buscar por qualquer campo no MongoDB é possível — mas isso não significa que qualquer campo serve para garantir unicidade em operações críticas. Se sua operação depende da certeza de que "não existe outro igual", então o campo (ou a combinação de campos) precisa estar refletido no índice único.

Quando acontece um erro como o E11000, não é só um problema de código quebrado. É um sinal de que a modelagem dos dados, a estratégia de identificação e a operação do sistema podem estar desalinhadas. Esses erros são uma ótima oportunidade para revisar e fortalecer o desenho do seu banco.

Por fim, sempre vale a pena pensar além da parte técnica: proteger a unicidade dos dados é proteger também a integridade do seu processo logístico, financeiro e de relacionamento com os clientes. No final das contas, um sistema que respeita essas premissas é mais robusto, confiável — e mais fácil de evoluir.

Como os pilares da Programação Orientada a Objetos (POO) se conectam ao SOLID

Humberto Barbosa — Mon, 07 Apr 2025 14:26:15 +0000

1. Abstração

Foca no comportamento essencial isolando as características essenciais de um objeto, ignorando os detalhes de implementação.

A abstração é um dos pilares da Programação Orientada a Objetos (POO) que ajuda a reduzir a complexidade no desenvolvimento de software. Ela permite que os programadores representem entidades do mundo real de maneira simplificada, focando apenas nos aspectos essenciais para o sistema.

Isso permite que seu código de negócio não conheça como o pagamento será salvo: pode ser banco, arquivo, API.

2. Encapsulamento

Protege o estado interno do objeto ermite ocultando os detalhes internos de implementação e definindo uma interface de uso externo segura.

O encapsulamento é um princípio fundamental da Programação Orientada a Objetos que consiste em ocultar os detalhes internos de um objeto, expondo apenas o que é necessário para sua interação.

3. Herança

Permite reuso de comportamento e especialização por meio de classes derivadas.

A herança é um dos pilares fundamentais da Programação Orientada a Objetos que permite estender funcionalidades de uma classe já existente. Com ela, é possível criar novas classes (chamadas de subclasses ou classes filhas) que herdam características (atributos e métodos) de uma classe base (superclasse ou classe pai).

4. Polimorfismo

Permite que objetos de diferentes classes possam responder de maneira diferente a uma mesma chamada de método, mantendo uma interface comum.

O polimorfismo é um conceito essencial da POO que permite que um mesmo método se comporte de maneiras diferentes, dependendo do objeto que o executa. Ele dá flexibilidade ao código, permitindo que classes distintas respondam à mesma ação de formas específicas.

Os 5 Princípios SOLID

1. Single Responsibility Principle (SRP) – Princípio da Responsabilidade Única

Reúna as coisas que mudam pelos mesmos motivos. Separe as coisas que mudam por motivos diferentes.

Evite misturar regras de negócio com a camada de interface gráfica. Também separamos comandos SQL de protocolos de comunicação. Fazemos isso porque queremos manter isolado o código que muda por motivos diferentes, evitando que alterações em uma parte afetem outras de forma indesejada. Assim, garantimos que módulos que evoluem por razões distintas não fiquem entrelaçados por dependências desnecessárias.

Se uma classe faz muitas coisas diferentes, ela fica difícil de entender e modificar. Separando as responsabilidades, deixamos o código mais organizado e modular.

2. Open/Closed Principle (OCP) – Princípio Aberto/Fechado

O código deve estar aberto para extensão, mas fechado para modificação. Isso significa que devemos ser capazes de adicionar novas funcionalidades sem alterar o código existente.

Isso quer dizer que devemos usar interfaces ou classes abstratas para definir o comportamento, e usando polimorfismo esse comportamento pode variar em tempo de execução.

3. Liskov Substitution Principle (LSP) – Princípio da Substituição de Liskov

Subtipos devem ser substituíveis por seus tipos base sem quebrar a aplicação.

Se uma subclasse altera o comportamento esperado da classe pai, podemos ter problemas imprevisíveis no código.
Existem 3 regras que devem ser seguidas pelas subclasses:

Pré-condições não devem ser fortalecidas na subclasse: Pré-condições representam os requisitos necessários para que um método possa ser executado corretamente, os parâmetros esperados. Por exemplo, se um método aceita um número (positivo ou negativo), uma subclasse não deve restringir esse comportamento para aceitar apenas números positivos. Fazer isso fortalece a pré-condição, e pode quebrar a lógica do programa, especialmente em casos onde se espera que o método aceite números negativos.
Pós-condições não devem ser enfraquecidas na subclasse: As pós-condições definem o que o método retorna após sua execução. Uma subclasse não deve retornar menos do que o esperado. Por exemplo, se o contrato do método exige um valor booleano, a subclasse deve retornar um true ou false. Embora seja possível "fortalecer" o contrato (por exemplo, retornando sempre true), retornar outros tipos como string, number, null, ou lançar exceções inesperadas, quebra a expectativa da aplicação — especialmente em linguagens dinamicamente tipadas.
A invariância deve ser preservada na subclasse: Invariância se refere ao estado interno do objeto, que deve ser protegido e controlado por meio de encapsulamento. Subclasses não devem violar esse contrato, modificando diretamente atributos da superclasse ou alterando sua lógica de maneira inconsistente. É essencial respeitar os modificadores de visibilidade (como private e protected) e manter o comportamento coerente em toda a hierarquia de classes.

4. Interface Segregation Principle (ISP) – Princípio da Segregação de Interface

Nenhuma classe deve ser forçada a depender de métodos que não usa.

É melhor ter múltiplas interfaces específicas do que uma interface gigante cheia de métodos inúteis.

Por que isso importa? (segundo Uncle bob)

Mesmo hoje, trabalhando com linguagens compiladas, ainda somos afetados por problemas relacionados à recompilação e reimplantação desnecessária. Imagine o seguinte cenário:

O Módulo A depende de uma interface do Módulo B apenas para um subconjunto de seus métodos.
Se outro método dessa interface for alterado, mesmo que o Módulo A não o utilize, ele precisará ser recompilado e reimplantado.

Esse acoplamento em tempo de compilação, mesmo sem dependência em tempo de execução, é um problema real — especialmente em linguagens estaticamente tipadas como Java, C#, C++, Go, Swift etc.

5. Dependency Inversion Principle (DIP) – Princípio da Inversão de Dependência

Dependa de abstrações, não de implementações concretas, ou seja abstrações não devem depender de detalhes. Detalhes devem depender de abstrações.

Isso significa que implementando esse princípio voce vai quebrar a dependência direta entre regras de negócio (nível alto) e detalhes de implementação (nível baixo). Ele propõe que as dependências devem sempre apontar para abstrações, nunca diretamente para implementações concretas.
A injeção de dependências resolve o vínculo entre os dois em tempo de execução.

RELAÇÃO: PILARES da POO → PRINCÍPIOS SOLID

Pilar da POO	Conexões com Princípios SOLID	Como se Conectam
Abstração	OCP, DIP, ISP, SRP	Permite ocultar complexidade, definindo interfaces que isolam o “o quê” do “como”. Facilita o desacoplamento entre módulos. Base para Dependency Inversion e Interface Segregation.
Encapsulamento	SRP, LSP, OCP	Protege o estado interno dos objetos, separando responsabilidades. Ajuda a manter coesão e evitar que alterações em um detalhe impactem em outros.
Herança	OCP, LSP	Permite a extensão de comportamento sem modificação (essência do Open/Closed). Deve ser usada com cautela para não violar substituição (Liskov).
Polimorfismo	OCP, DIP, LSP, ISP	Permite que objetos de diferentes tipos sejam tratados de forma uniforme via interfaces. Viabiliza inversão de dependência, extensão sem modificação e substituição segura de implementações.

Código tem que ser simples

Simplicidade não é ausência de estrutura ou codar com falta de boas praticas e principios

Dizer apenas "Código tem que ser simples" sem oferecer princípios claros é como ser um surdo em bingo.

Com o entendimento básico dos fundamentos de POO fica mais facil entender os principios SOLID

https://en.wikipedia.org/wiki/Open%E2%80%93closed_principle
https://blog.cleancoder.com/uncle-bob/2020/10/18/Solid-Relevance.html
https://www.branas.io/blog/solid-lsp-liskov-substitution-principle.htmlpo
https://hub.asimov.academy/blog/programacao-orientada-a-objetos-conceito-e-pilares/

Publicando eventos a partir do domínio - com NestJS

Humberto Barbosa — Fri, 28 Mar 2025 20:56:41 +0000

📌 Eventos de Domínio: O que são e por que usar?

Eventos de domínio registram fatos importantes dentro do sistema. Algo aconteceu – um usuário se cadastrou, uma compra foi feita, um status mudou. Ao capturar isso como um evento, mantemos um histórico claro, facilitando auditorias e análises. Além disso, deixamos o sistema preparado para reagir a mudanças sem bagunçar tudo.

🚀 Implementação na prática

Eventos precisam ser imutáveis. Criou? Não mexe mais. Isso garante integridade e rastreabilidade. Outra coisa: desacoplar ao máximo. Se um evento precisa notificar outra parte do sistema, nada de dependência direta. Deixa ele solto e deixa quem precisar ouvir.

Benefícios?

Regras de negócio explícitas – Dá pra entender fácil o que está acontecendo.
Código modular e organizado – Menos acoplamento, mais flexibilidade.
Consistência entre agregados – Se algo muda, tudo que precisa ser atualizado é notificado automaticamente.

🎯 Quando usar eventos de domínio?

Sempre que precisar notificar outros contextos sem acoplamento. Exemplo clássico:

Usuário se cadastra → Dispara evento → Outro serviço manda e-mail de boas-vindas.
Pedido pago → Dispara evento → Estoque e faturamento são atualizados automaticamente.

Bora pro código.

Para fazer isso, vamos evitar expor o dominio a qualquer tipo de infraestrutura de mensagens, com isso evitamos acoplar nossa entidade explicitamente a um recurso externo.

📌 Cenário:

Temos um Usuário que se cadastra no sistema. Quando isso acontece, queremos:
✅ Enviar um e-mail de boas-vindas

Criando o Evento de Domínio

Usamos eventos de domínio para desacoplar esses processos.
Bora pro código! 🎯

export class UsuarioCadastradoEvent {
  constructor(public readonly usuarioId: string, public readonly email: string) {}
}

Um evento simples com id e email do novo usuario

Criando o Agregado Raiz

export class Usuario {
  private domainEvents: any[] = [];

  constructor(public readonly id: string, public readonly nome: string, public readonly email: string) {
    this.adicionarEvento(new UsuarioCadastradoEvent(id, email));
  }

  private adicionarEvento(evento: any) {
    this.domainEvents.push(evento);
  }

  pullEvents(): any[] {
    const events = [...this.domainEvents];
    this.domainEvents = [];
    return events;
  }
}

O que rolou aqui?

Criamos um Usuário.
Assim que ele nasce, ele já dispara UsuarioCadastradoEvent.
pullEvents() pega os eventos pendentes e os limpa. ### Criando um Manipulador de Eventos (Event Handler)

import { EventsHandler, IEventHandler } from '@nestjs/cqrs';
import { UsuarioCadastradoEvent } from '../events/usuario-cadastrado.event';

@EventsHandler(UsuarioCadastradoEvent)
export class EnviarEmailBoasVindasHandler implements IEventHandler<UsuarioCadastradoEvent> {
  handle(event: UsuarioCadastradoEvent) {
    console.log(`📧 Enviando e-mail de boas-vindas para ${event.email}...`);
  }
}

Quando UsuarioCadastradoEvent acontece, o handler entra em ação. Aqui ele só printa no console, mas poderia enviar e-mail, publicar no Kafka, chamar outro serviço, etc.

Criando o Serviço de Usuário

O NestJS já fornece um Event Bus pronto via @nestjs/cqrs, então só precisamos usá-lo.

import { Injectable } from '@nestjs/common';
import { EventBus } from '@nestjs/cqrs';
import { Usuario } from '../models/usuario.model';

@Injectable()
export class UsuarioService {
  constructor(private readonly eventBus: EventBus) {}

  criarUsuario(nome: string, email: string): Usuario {
    const usuario = new Usuario(crypto.randomUUID(), nome, email);
    usuario.pullEvents().forEach((event) => this.eventBus.publish(event));
    return usuario;
  }
}

Criamos o usuário.
Pegamos os eventos gerados.
Publicamos no Event Bus do NestJS.

Agora qualquer serviço que ouvir esse evento pode agir sem precisar mudar código aqui.

Lembre-se de registrar no modulo, algo assim:

@Module({
  providers: [UsuarioService, EnviarEmailBoasVindasHandler],
})

e claro registrar o cqrs no modulo principal conforme a documentação.
Agora, sempre que um usuário se cadastrar, os eventos certos serão disparados. 🚀

✅ Recapitulando

Eventos de Domínio organizam melhor as regras de negócio.
Código desacoplado → Adiciona novos handlers sem mexer no código principal.
NestJS + CQRS → Event Bus já pronto, sem precisar reinventar a roda.

As três leis do TDD em 'The Clean Coder'

Humberto Barbosa — Wed, 19 Mar 2025 10:47:05 +0000

Robert C. Martin, o Uncle Bob, não brinca quando fala de Test Driven Development (TDD). Ele trata como disciplina essencial para quem quer ser um desenvolvedor de verdade. O cara define três leis que tornam o TDD um processo inegociável:

"Não escreva código de produção sem antes escrever um teste que falhe."

Sem exceções. Antes de codar qualquer funcionalidade, escreva um teste que prove que aquilo precisa existir. Como a funcionalidade ainda não foi implementada, o teste falha. Essa falha inicial mostra que o teste realmente verifica o comportamento esperado.

"Não escreva mais de um teste do que o suficiente para falhar - e não compilar já conta como falha."

Sem enrolação. Escreva apenas o necessário para ver o erro acontecer. Nada de sair codando funcionalidade antes da hora.

"Não escreva mais código de produção do que o necessário para passar no teste que falhou."

Código mínimo para o teste passar, nada de firulas. Isso força um ciclo enxuto de implementação e garante que cada linha de código tenha um propósito.

O Ciclo Virtuoso do TDD

Essas três leis criam um loop de desenvolvimento que dura, em média, 30 segundos. Escreve teste → vê falhar → escreve código → vê passar → refatora. Esse ciclo curto reduz o risco de surpresas desagradáveis no código.

Benefícios do TDD

Uncle Bob defende que seguir essas regras traz uma série de vantagens:

Certeza: Testes constantes garantem que as funcionalidades funcionam como esperado.
Coragem: Ter uma suíte de testes permite refatorar sem medo de quebrar tudo.
Menos bugs: Erros são encontrados antes de chegarem ao usuário.
Documentação viva: Os testes servem como um manual de como o código deveria se comportar.
Design melhor: TDD força modularidade e baixo acoplamento.

O Maior Benefício: Certeza

Segundo Uncle Bob, o grande diferencial do TDD é a confiança que ele proporciona. Escrevendo e rodando centenas de testes por semana, um desenvolvedor sabe exatamente o que está funcionando. No projeto FitNesse, com 64 mil linhas de código e mais de 2.200 testes unitários, Uncle Bob garante 90% de cobertura. Tudo roda em 90 segundos, e se passar, ele sabe que pode lançar uma nova versão sem pânico.

Isso se traduz em:

Refatoração sem medo: Melhorar o código sem receio de quebrar algo.
Menos defeitos no código final: Bugs são eliminados antes de virarem problema para o usuário.

Resumindo? Se você quer escrever código que realmente funcione, sem gambiarra e sem susto, TDD não é opcional. É disciplina. Seguir esse processo transforma código ruim em código sólido.

State Pattern na prática - pare de sofrer com lógicas de estado bagunçadas

Humberto Barbosa — Tue, 18 Mar 2025 21:33:58 +0000

Descobrir o State Pattern foi um ponto de virada. Esse padrão não é o mais falado, mas resolve um problema real: código inchado por condicionais monstruosas.

Sabe aquelas máquinas de estado cheias de if e switch? O código cresce, novos estados surgem e, de repente, qualquer alteração vira uma dor de cabeça. Já viu algo assim?

class User {
    constructor(name) {
        this.name = name;
        this.status = "pending"; // Estado inicial
    }

    changeStatus(newStatus) {
        switch (newStatus) {
            case "active":
                if (this.status === "active") {
                    console.log("Já está ativo...");
                } else {
                    this.status = "active";
                    console.log("Usuário ativado com sucesso.");
                }
                break;

            case "blocked":
                if (this.status === "blocked") {
                    console.log("Usuário já está bloqueado.");
                } else {
                    this.status = "blocked";
                    console.log("Usuário bloqueado com sucesso.");
                }
                break;

            case "canceled":
                if (this.status === "canceled") {
                    console.log("Usuário já está cancelado.");
                } else {
                    this.status = "canceled";
                    console.log("Usuário cancelado com sucesso.");
                }
                break;

            default:
                console.log("Status inválido.");
        }
    }

    getStatus() {
        console.log(`Status atual: ${this.status}`);
    }
}

No começo, parece tranquilo. Mas conforme o sistema evolui, o inferno começa: um mar de condicionais espalhadas pelo código. Manutenção? Um pesadelo.

Solução

O State Pattern resolve isso. Em vez de espalhar lógica de estado, cada estado vira uma classe separada. O objeto principal apenas mantém uma referência ao estado atual e delega as decisões para ele.

Menos bagunça, mais organização. E quando precisar adicionar um novo estado? Só criar uma nova classe, sem tocar no código existente. Quer código flexível e fácil de manter? State Pattern é o caminho.

Exemplo

Aqui está um exemplo de implementação do State Pattern em TypeScript para modelar o status de uma conta (Account), que pode estar em um dos seguintes estados:

Active
WaitingActivation
Blocked
Cancelled

Cada estado implementará um comportamento diferente para a conta. Vamos definir as classes de estado e a classe de contexto (Account), que gerencia o estado atual.

📌 Passo 1: Definir a Interface do Estado

Cada estado da conta precisa implementar essa interface para garantir que todos os estados tenham os mesmos métodos.

interface AccountState {
  activate(): void;
  block(): void;
  cancel(): void;
  getStatus(): string;
}

📌 Passo 2: Criar as Implementações dos Estados

Cada estado terá uma implementação específica, alterando o comportamento da conta de acordo com a regra de negócio.

class ActiveState implements AccountState {
  constructor(private account: Account) {}

  activate(): void {
    console.log("A conta já está ativa.");
  }

  block(): void {
    console.log("Bloqueando a conta...");
    this.account.setState(new BlockedState(this.account));
  }

  cancel(): void {
    console.log("Cancelando a conta...");
    this.account.setState(new CancelledState(this.account));
  }

  getStatus(): string {
    return "Active";
  }
}

class WaitingActivationState implements AccountState {
  constructor(private account: Account) {}

  activate(): void {
    console.log("Ativando a conta...");
    this.account.setState(new ActiveState(this.account));
  }

  block(): void {
    console.log("A conta ainda não está ativada e não pode ser bloqueada.");
  }

  cancel(): void {
    console.log("Cancelando a conta antes da ativação...");
    this.account.setState(new CancelledState(this.account));
  }

  getStatus(): string {
    return "WaitingActivation";
  }
}

class BlockedState implements AccountState {
  constructor(private account: Account) {}

  activate(): void {
    console.log("Não é possível ativar uma conta bloqueada. Contate o suporte.");
  }

  block(): void {
    console.log("A conta já está bloqueada.");
  }

  cancel(): void {
    console.log("Cancelando a conta bloqueada...");
    this.account.setState(new CancelledState(this.account));
  }

  getStatus(): string {
    return "Blocked";
  }
}

class CancelledState implements AccountState {
  constructor(private account: Account) {}

  activate(): void {
    console.log("Uma conta cancelada não pode ser reativada.");
  }

  block(): void {
    console.log("Uma conta cancelada não pode ser bloqueada.");
  }

  cancel(): void {
    console.log("A conta já está cancelada.");
  }

  getStatus(): string {
    return "Cancelled";
  }
}

📌 Passo 3: Criar a Classe `Account`

Essa classe é sua entidade e gerencia o estado atual da conta e delega chamadas para o estado correto.

class Account {
  private state: AccountState;

  constructor() {
    // Estado inicial: aguardando ativação
    this.state = new WaitingActivationState(this);
  }

  setState(state: AccountState): void {
    this.state = state;
  }

  activate(): void {
    this.state.activate();
  }

  block(): void {
    this.state.block();
  }

  cancel(): void {
    this.state.cancel();
  }

  getStatus(): string {
    return this.state.getStatus();
  }
}

📌 Passo 4: Testar a Implementação

Agora, vamos criar uma conta e testar as transições de estado, a execução seria algo assim:

const myAccount = new Account();
console.log("Status inicial:", myAccount.getStatus());

myAccount.activate(); // Deve ativar a conta
console.log("Status atual:", myAccount.getStatus());

myAccount.block(); // Deve bloquear a conta
console.log("Status atual:", myAccount.getStatus());

myAccount.cancel(); // Deve cancelar a conta
console.log("Status atual:", myAccount.getStatus());

myAccount.activate(); // Tentativa de ativar uma conta cancelada (deve falhar)
console.log("Status final:", myAccount.getStatus());

📌 Explicação

Encapsulamento dos estados: Cada estado implementa um comportamento específico e sabe para qual estado pode transitar.
Mudança dinâmica de comportamento: A classe Account delega a execução das ações ao estado atual.
Evita if-else desnecessários: O código fica mais organizado e escalável.

Isso garante uma implementação flexível e permite adicionar novos estados sem modificar a lógica central da Account. 🚀

Conclusão

No State Pattern que a gente montou, vários princípios entraram em jogo sem a gente nem precisar pensar muito. Olha só:

Encapsulamento? Sim Cada estado tem sua própria lógica, sem espalhar código bagunçado por aí. O Account nem precisa saber como cada estado funciona, só delega e segue o jogo.

Responsabilidade Única? Sim Cada classe faz uma coisa só. O estado lida com as regras do status da conta, e o Account só troca de estado quando precisa. Sem mistura de responsabilidades.

Aberto/Fechado? Sim. Se amanhã precisar de um novo estado tipo SuspendedState, só criar e encaixar. Não precisa mexer no código velho e correr risco de quebrar tudo.

Substituição de Liskov? Sim. O Account nem sabe qual estado tá rodando. Ele só chama os métodos da interface e confia que o estado resolve. Pode trocar um pelo outro sem dor de cabeça.

Inversão de Dependência? Sim. O Account depende da abstração (AccountState), não de implementações específicas. Zero acoplamento, total flexibilidade.

No fim, isso aqui é código escalável, fácil de manter e sem aquele monte de if espalhado. Quer mudar um comportamento? Troca o estado e pronto. Isso é POO do jeito certo. 🚀

Links

https://refactoring.guru/pt-br/design-patterns/state
https://elemarjr.com/clube-de-estudos/artigos/voce-precisa-conhecer-o-state-pattern/

Como testes mudaram minha forma de trabalhar

Humberto Barbosa — Tue, 18 Mar 2025 00:30:10 +0000

Antes, eu confiava no feeling. Escrevia código, rodava manualmente, dava aquela conferida na tela e, se parecia ok, bora pro deploy. Mas depois que comecei a testar do jeito certo, tudo mudou…

O que eu fazia antes

Cada alteração era um risco. Ajustava uma coisa e, sem perceber, quebrava outra. Às vezes, gastava mais tempo testando manualmente do que escrevendo código. Já aconteceu de estar confiante, subir pra produção e… surpresa: bug.

O que aprendi

Testes não são sobre evitar bugs (porque eles vão acontecer), mas sobre ter controle. Saber que, se algo quebrar, você vai descobrir antes do cliente. Testes te colocam num ciclo rápido de feedback: você muda algo e, em segundos, já sabe se quebrou alguma coisa.

O impacto

Menos medo de refatorar. Mais confiança pra evoluir o código. Tempo economizado que antes era gasto preenchendo formulário pra testar fluxo manualmente. A mentalidade mudou: agora penso primeiro em como testar, antes de sair escrevendo código.

Se você ainda não aplica isso, está perdendo tempo

Dá trabalho no começo, mas depois que entra no fluxo, vira hábito. E um hábito que salva tempo, evita dor de cabeça e deixa seu código mais seguro.

📌 E você, qual foi a maior mudança na sua forma de trabalhar nos últimos anos?

O que acontece quando não tem testes?

Humberto Barbosa — Tue, 18 Mar 2025 00:28:36 +0000

Cada deploy é uma torcida. Você muda uma linha e fica esperando pra ver se algo quebrou. Feedback lento, retrabalho.

Já passou um tempão preenchendo um formulário só pra testar um fluxo? Já quebrou algo numa parte do sistema que aparentemente não tinha nada a ver? (eu já, várias vezes).

Isso gera medo de mexer no código. E medo de mexer no código significa evolução mais lenta. Agora, quando você tem testes rodando pra vários cenários, qual o motivo pra temer?

Testes não garantem que nunca vai ter um bug. Mas garantem que você tem mais controle sobre o código quando precisar mexer.

O que realmente é um teste automatizado?

É basicamente definir entradas e verificar se a saída tá batendo com a expectativa.

Given: preparo do cenário
When: execução do comportamento
Then: validação do resultado

E se os testes forem lentos e dependentes entre si? Aí já começou errado. Eles devem rodar rápido e de forma independente.

E o famoso "não tenho tempo pra testar"? Mas tem tempo pra corrigir bug em produção, responder cliente puto, testar na mão, lidar com código legado que ninguém quer mexer, treinar dev novo… Pois é.

Como Desacoplar um Serviço Externo do Seu Código (Sem Sofrer no Futuro)

Humberto Barbosa — Sat, 15 Mar 2025 00:00:50 +0000

Manter um sistema desacoplado de serviços externos não é frescura, é necessidade. Se você quer um código mais flexível, testável e resiliente, precisa seguir algumas boas práticas. Vamos direto ao ponto:

1. Use um Gateway para Intermediar o Acesso

Um Gateway é basicamente um intermediário entre o seu código e o serviço externo. Ou seja, em vez de chamar diretamente a API do serviço, seu código conversa com um Gateway, que gerencia essa comunicação.

🔹 O que isso resolve?
✅ Você pode trocar o serviço externo sem quebrar seu código.
✅ Facilita a implementação de cache, logs e validações.
✅ Reduz a dependência direta da aplicação no serviço externo.

No livro Patterns of Enterprise Application Architecture reforça que eles são essenciais para encapsular o acesso a sistemas externos.

2. Aplique o Princípio da Inversão de Dependência (DIP)

O DIP, um dos princípios SOLID, diz que o código deve depender de abstrações, não de implementações concretas.

🔹 Como aplicar?
✅ Crie interfaces para os serviços externos e injete implementações via dependência.
✅ Evite acoplar sua aplicação diretamente a APIs externas.
✅ Facilita testes unitários, já que você pode mockar a interface em vez de bater na API real.

Exemplo prático: imagine que sua aplicação depende de uma api externa para fazer pagamentos. Em vez de chamar uma classe especifica que encapsula a lib do serviço de pagamento por exemplo: pagarmeService.pay(), você pode criar uma interfacePaymentServicee injetar diferentes implementações (PaymentServicePagarme,PaymentServicePagseguro`, etc.).

3. Arquitetura Hexagonal (Ports and Adapters) ou clean arch

A arquitetura Ports and Adapters resolve um problema clássico: separar a lógica de negócio da infraestrutura.

🔹 Como funciona?
✅ Portas (Ports) → Interfaces que sua aplicação expõe ou consome.
✅ Adaptadores (Adapters) → Traduções entre sua aplicação e serviços externos.

Exemplo prático:

Sua aplicação precisa enviar um email? Você define uma interface EmailService.
Depois, pode implementar um SendGridEmailService, desacoplando sua aplicação do serviço especifico.

Isso significa que, no futuro, se precisar trocar o sendgrid pelo SES, por exemplo, o impacto no código será mínimo.

4. Utilize Eventos de Domínio (E faça as coisas de forma assíncrona)

Se você ainda acha que precisa chamar serviços externos de forma síncrona o tempo todo, está perdendo uma grande oportunidade de melhorar a escalabilidade e resiliência do seu sistema.

🔹 O que fazer?
✅ Publicar eventos em vez de chamar APIs diretamente.
✅ Deixe outro serviço consumir o evento e interagir com a API externa.
✅ Se o serviço externo estiver fora do ar, o evento pode ser processado depois.

Isso reduz o acoplamento temporal, ou seja, sua aplicação não precisa esperar uma resposta imediata do serviço externo para continuar funcionando.

5. Mantenha o Domínio Isolado

🔹 O que isso significa na prática?
✅ Seu modelo de domínio não deve ter nada relacionado a serviços externos.
✅ Qualquer integração deve estar nas camadas externas da arquitetura.

Se seu domínio está cheio de chamadas para APIs de terceiros, você está cometendo um erro grave de design. Uma boa prática é garantir que a camada de domínio não tenha imports de outras camadas, mantendo-a pura e independente.

Anti-Corruption Layer (ACL): Blindando Seu Domínio Contra "Poluição Externa"

Quando dois sistemas se comunicam, existe um risco de que um modelo de dados acabe "contaminando" o outro. Para evitar isso, usamos a Anti-Corruption Layer (ACL).

🔹 O que a ACL faz?
✅ Traduz e adapta os dados entre sistemas diferentes.
✅ Evita que regras de negócio de um serviço externo afetem seu domínio.
✅ Permite agregar dados de múltiplas fontes sem bagunçar sua aplicação.

Alistair Cockburn até critica o nome "Anti-Corruption Layer" (acha que parece negativo), mas defende a ideia: é uma camada intermediária que traduz a comunicação entre seu sistema e um serviço externo para evitar que as regras externas "corrompam" seu domínio.

Exemplo prático:
Se sua aplicação precisa se integrar a um ERP antigo, você não deve fazer chamadas diretas a ele. Em vez disso, cria-se uma ACL que traduz os dados do ERP para um formato que sua aplicação entende, na pratica você vai usar o pattern adapter.

Contextos Delimitados: Entenda Onde Cada Conceito Faz Sentido

No Domain-Driven Design (DDD), um Contexto Delimitado define onde um conceito faz sentido dentro do seu sistema.

🔹 O que isso resolve?
✅ Evita que um termo tenha significados diferentes dentro do mesmo sistema.
✅ Ajuda na organização modular do código.
✅ Facilita a modelagem de serviços independentes.

Exemplo prático:
O que significa "cliente"? No setor financeiro de um hospital, pode significar um paciente pagante. Já no setor de internação, "cliente" pode ser qualquer paciente. O contexto muda completamente!

Cada contexto delimitado pode ter seu próprio modelo de dados, regras e até sua própria equipe de desenvolvimento.

Dica:
Contextos bem definidos não significam automaticamente microserviços, mas podem ajudar na modularização e escalabilidade do sistema.

As 4 Perguntas que Todo Arquiteto de Software Deve Fazer

Ao avaliar uma proposta de design, um arquiteto de software precisa responder 4 perguntas essenciais:

1️⃣ Essa solução atende aos objetivos do negócio?

Se não atende, não faz sentido implementá-la. 2️⃣ A solução respeita as restrições do projeto?
Não adianta propor algo que não cabe dentro das limitações do sistema. 3️⃣ Ela cumpre os atributos de qualidade?
Performance, escalabilidade, segurança, etc. 4️⃣ Existe uma alternativa mais barata ou menos arriscada?
Se existir, volte para a prancheta e refaça o planejamento.

💡 Se a resposta para a quarta pergunta for "sim", é melhor reconsiderar a solução. Um bom arquiteto não busca apenas a "melhor" solução, mas sim a solução mais eficiente dentro do contexto do negócio.

Conclusão

Se você quer um sistema desacoplado de verdade, precisa aplicar boas práticas de arquitetura.

🔹 Use Gateways para encapsular integrações externas.
🔹 Aplique DIP para evitar dependências diretas.
🔹 Adote Ports and Adapters para separar seu domínio da infraestrutura.
🔹 Use eventos assíncronos para melhorar escalabilidade e resiliência.
🔹 Proteja seu domínio com ACL e defina contextos delimitados no DDD.

O objetivo final é simples: um código flexível, fácil de manter e preparado para mudanças. Se seu sistema ainda está acoplado diretamente a serviços externos, você está deixando um problema enorme para o futuro.

Agora, bora refatorar esse código! 🚀

Links

Hexagonal Architecture (Ports and Adapters) with Alistair Cockburn // Live #98
SOLID DIP Dependency Inversion Principle + Design Patterns Adapter
Como criar e desacoplar camadas usando SOLID
10 perguntas sobre Domain-Driven Design
Domain Driven Design do Jeito Certo
DDD, Domain-Driven Design com Elemar Jr. // Live #52
Event-Driven Architecture, Microservices e CQRS: A combinação perfeita

O que é Clean Architecture?

Humberto Barbosa — Tue, 17 Jan 2023 01:38:54 +0000

O que é arquitetura de software?

Que raio é isso? O que isso faz? Vamos começar com algumas definições de caras que sabem o que estão falando.

Robert Martin (Uncle Bob) diz o seguinte:

The goal of software architecture is to minimize the human resources required to build and maintain the required system.

Ou seja, o objetivo da arquitetura de software é minimizar os recursos humanos necessários para construir e manter um sistema.

Já Martin Fowler define assim:

Software architecture is those decisions which are both important and hard to change.

Ou seja, a arquitetura de software são as decisões importantes e difíceis de mudar.

Agora, bora descomplicar: arquitetura de software tem a ver com organização, estrutura, design, relacionamento e comportamento.

Se você já escreveu um software do zero ou participou da reescrita de um sistema legado, sabe do que estou falando. O chefe deu carta branca, escolheu-se tecnologia, servidores, frameworks… tudo isso são decisões arquiteturais. E, adivinha? Elas vão te acompanhar enquanto o sistema estiver no ar.

Essas decisões são afetadas por fatores como:

O escopo do produto
O orçamento da empresa (quanto tem para equipe, servidores, etc.)
O volume de requisições
O nível técnico da equipe (sênior, pleno, júnior, estagiários…)
O prazo de entrega

Agora, pense comigo: se a empresa tem meia dúzia de clientes, faz sentido criar um sistema distribuído com Kafka, Kubernetes e banco replicado? Ou será que seria um gasto desnecessário?

Cada tipo de software exige uma arquitetura diferente. Um ERP não é um jogo de RPG online, uma plataforma de streaming não é um simples CLI. Existem várias arquiteturas: monolítica, distribuída, cliente-servidor, orientada a eventos, serverless... e cada uma resolve um problema específico.

E só porque você usou Clean Architecture em um projeto, não significa que precisa replicar isso em todos os outros. Se você tem um sistema que só cadastra um e-mail numa newsletter, faz sentido implementar Clean Architecture, Hexagonal Architecture ou MVC? Não.

O que é Clean Architecture?

Clean Architecture é um modelo arquitetural focado em desacoplar as regras de negócio dos recursos externos (como banco de dados, frameworks, etc.).

Exemplo: seu ORM deve ficar isolado na camada dele, fazendo apenas operações de banco (salvar, atualizar, deletar). Enquanto isso, a entidade do ORM (que representa uma tabela) não deve ser a mesma entidade que contém as regras de negócio.

Como surgiu a Clean Architecture?

O próprio Uncle Bob criou esse conceito enquanto desenvolvia um software junto com o filho dele. Era um sistema onde os usuários criavam testes baseados em uma wiki.

Durante o projeto, ele percebeu que quando olhava para a estrutura de pastas, só via Rails. Ele não queria ver Rails, queria enxergar o propósito da aplicação. O problema? O sistema estava totalmente dependente do framework.

Então, ele começou a separar as regras de negócio das dependências externas, focando no core da aplicação e nos testes.

Foi daí que surgiu a ideia: o centro da aplicação não é o banco de dados e nem o framework. O centro da aplicação são os casos de uso.

Use Cases: O Coração da Aplicação

Uncle Bob definiu assim:

The center of your application is not the database, nor is it one or more of the frameworks you may be using. The center of your application is the use cases of your application.

Ou seja, o centro da sua aplicação são os casos de uso.

Se liga: quando você projeta um sistema, qual a primeira coisa que a maioria das empresas pensa? No banco de dados. "Qual vai ser a tabela?", "Quais colunas precisa ter?"

Esse pensamento está invertido. O certo seria definir os casos de uso primeiro.

Casos de uso são as intenções do usuário dentro do sistema. Exemplo:

Fazer check-in
Adicionar itens ao carrinho
Processar um pagamento

Esses casos de uso contêm as regras de negócio e chamam as entidades para resolver as operações.

E se, ao escrever um caso de uso, você percebe que ele depende de uma regra contida em outro caso de uso? A resposta é não reutilizar casos de uso diretamente. Se isso aconteceu, significa que você identificou uma regra de negócio independente e que ela deve estar na camada de entidades.

Entities: O Núcleo das Regras de Negócio

Aqui entram as regras de negócio puras, que podem ser aplicadas em diferentes contextos.

E aqui está um erro comum: confundir entidade de regra de negócio com entidade de ORM.

A entidade do ORM mapeia o banco de dados (ex: mapeamento de colunas para atributos). Já a entidade da Clean Architecture representa um conceito de negócio, independente do banco.

O que acontece se você misturar as duas coisas?

Se adicionar decorators, annotations ou outras dependências do ORM dentro da sua entidade de regra de negócio, você cria alto acoplamento. Resultado? Uma simples mudança na tabela do banco pode quebrar as regras de negócio.

Entidades precisam ser independentes. Elas podem ser classes ou simplesmente um conjunto de funções puras. A forma depende do seu estilo de código e do time.

Interface Adapters: A Ponte Entre Mundo Externo e Casos de Uso

Essa camada traduz os dados entre o mundo externo e a lógica de negócio.

Aqui entra toda a arquitetura MVC: controllers, middlewares, presenters...

O fluxo é assim:

O usuário faz uma requisição.
O dado chega na camada de Interface Adapters, que adapta e joga dentro de um DTO.
O DTO vai para o caso de uso, que processa tudo e retorna um resultado.
A resposta é adaptada novamente e enviada para o usuário.

Essa camada não deve conhecer detalhes como banco de dados, mensageria, etc.

Frameworks and Drivers: O Mundo Externo

Essa é a camada mais externa. Aqui entram:

Banco de dados
Redis
Nginx
Kafka
Qualquer outra dependência externa

A ideia é manter esses componentes isolados, evitando que impactem a lógica de negócio.

Conclusão

Não confunda camadas lógicas com pastas no projeto. Você pode jogar todos os arquivos na raiz e ainda assim manter as camadas organizadas. O que define as camadas é a dependência:

O que está fora pode depender do que está dentro.
O que está dentro nunca pode depender do que está fora.

Vantagens da Clean Architecture

✔ Isolamento das regras de negócio

✔ Definição clara de camadas e responsabilidades

✔ Fluxo de dependência ordenado e direcional

✔ Facilidade para testar

✔ Independência de frameworks e banco de dados

✔ Facilidade para evolução tecnológica

Links Úteis

O que é runtime javascript ?

Humberto Barbosa — Mon, 02 Jan 2023 12:18:06 +0000

O que é o ambiente de execução(runtime environment) ?

No contexto do browser esse ambiente de execução é composto por:

Javascript Engine
Web API
Fila de callbacks(The callback queue)
Loop de eventos(Event Loop)

Javascript Engine

Javascript Engine é um programa que executa código JavaScript. É o que torna possível a execução de código JavaScript em um navegador web ou em um ambiente de servidor, como o Node.js e agora mais recentemente o Deno.

Cada navegador web tem sua própria implementação de uma engine JavaScript, como o JavaScript V8 da Google, que é usado no Chrome e no Chromium, ou o Spider Monkey da Mozilla, que é usado no Firefox.

As engines JavaScript são otimizadas para interpretar e executar o código JavaScript de maneira rápida e eficiente. Elas fazem isso através de diversas técnicas, como pré-compilação de código e otimização de memória. As engines também implementam APIs JavaScript, como a API do Document Object Model (DOM), que permite que o código JavaScript acesse e manipule elementos HTML na página da web.

Call Stack: Dentro dessa engine nos temos a call stack e memory heap, toda vez que agente executa um código javascript as funções vão para a call stack que é o local onde as funções são empilhadas para serem executadas, essa estrutura é formada ultimo a entrar é primeiro a sair e só passa para a próxima execução quando concluir a atual.
Caso existe uma função da web api na call stack essa função é enviada para lá, apos o termino da execução o callback é enviado para a fila de callback(callback queue) para retornar pra call stack pra concluir a execução do código

Memory Heap: é um "pedaço" da memória do computador que é usada para alocar novos objetos. Quando um novo objeto é criado no código JavaScript, ele é alocado na memory heap.

A memory heap é dividida em duas partes: new space e old space. O new space é usada para alocar novos objetos e é otimizada para alocação rápida. O old space é usado para objetos que são mantidos por mais tempo e é otimizada para acesso rápido.

Quando new space está cheia, o V8 realiza uma operação chamada garbage collection, durante a qual ele examina os objetos no new space e remove aqueles que não são mais usados pelo código. Os objetos que ainda são usados são movidos para o old space. Isso libera espaço no new space para novos objetos.

O V8 também faz o garbage collection no old space, mas elas são menos frequentes e mais lentas do que as coletas no new space, pois envolvem a verificação de todos os objetos no old space.

Espero que isso tenha esclarecido um pouco sobre como a memory heap funciona no JavaScript V8.

Web API

JavaScript Web APIs são conjuntos de interfaces de programação de aplicativos (APIs) que fornecem acesso a recursos do navegador e do sistema operacional. Eles permitem a criação de aplicativos web que possam fazer coisas como acessar a câmera e o microfone do usuário, enviar solicitações HTTP, manipular o DOM e muito mais. Alguns exemplos de JavaScript Web APIs incluem:

Geolocation API: permite que os aplicativos web acessem as informações de localização do usuário.
Web Audio API: permite que os aplicativos web reproduzam áudio e criem efeitos de áudio complexos.
Web Storage API: permite que os aplicativos web armazenem dados no navegador do usuário, como informações de login ou preferências de usuário.
Essas são apenas algumas das muitas APIs disponíveis para os desenvolvedores de aplicativos web. Elas fornecem uma ampla gama de recursos que podem ser usados para criar aplicativos web poderosos e interativos.
O famoso setTimeout, ajax(xmlhttprequest) fazem parte da web api

Callback queue e Event Loop

A fila de callbacks, também conhecida como a "fila de eventos", é uma fila de funções que são chamadas quando um evento específico ocorre. No JavaScript, esses eventos podem incluir coisas como o carregamento de uma página web, o clique em um botão ou o recebimento de uma resposta de uma solicitação HTTP.

Quando um evento ocorre, a função de callback associada a ele é adicionada à fila de callbacks. O JavaScript possui um loop de eventos que executa continuamente e verifica a fila de callbacks para ver se há funções para serem chamadas. Quando uma função está disponível na fila, ela é removida da fila e chamada. Isso permite que o código JavaScript responda a eventos de maneira assíncrona.

Por exemplo, quando um usuário clica em um botão em uma página web, é adicionada uma função de callback à fila de callbacks. Quando o loop de eventos verifica a fila, essa função é chamada e o código associado ao clique no botão é executado. Isso permite que o código continue a ser executado enquanto o navegador está ocupado processando o clique do botão, sem bloquear a interface do usuário.

Node.js

O node.js é uma runtime para executar o javascript no backend a diferença do browser é que em vez de ter a Web Api ele tem a libuv que é onde ocorre a execuçaõ de funções assincronas.

Se você quer visualizar essas coisas acontecendo tem esse site http://latentflip.com/loupe onde é possivel ver o código passando pelos mecanismos da runtime, ao entrar no site já existe um código de exemplo mas você pode colocar esse abaixo ou inventar algum:

`
console.log("Hi!");

setTimeout(function timeout() {
console.log("5 segundos depois");
}, 5000);

console.log("executei antes do setTimeout");
`

Links pesquisados:
https://medium.com/@gemma.croad/understanding-the-javascript-runtime-environment-4dd8f52f6fca
https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Introduction
https://nodejs.org/en/docs/guides/diagnostics/memory/using-gc-traces/

DEV Community: Humberto Barbosa

Promises em Nodejs Paralelo, Sequencial e Corrida – Qual usar?

Promises em Node.js: Paralelo, Sequencial e Corrida – Como Escolher?

🧠 Antes de tudo: o que é uma Promise?

🔧 Função base para nosso exercício

🟩 Execução Paralela (Parallel)

Exemplo:

O que acontece aqui?

Execução Sequencial (Sequential)

Exemplo:

O que acontece?

Corrida (Race)

Exemplo:

Resultado:

🧪 Testando os três modos

Quando usar cada um?

Conclusão

Integração Correios para Rastreamento de Entregas: Arquitetura Escalável com NestJS e Kafka

Introdução

Desenho da Solução

Pontos de Complexidade

Abstração via API Gateway

Boas Práticas Adotadas

Testes Unitários

🧪 Exemplo de Teste com Gateway Mockado

Lições Aprendidas

Conclusão

Evitando Erros de Índice Único (E11000) ao Usar findOneAndUpdate com upsert no Mongoose

✅ Cenário

💾 Estrutura simplificada dos dados

🔐 Definindo o índice único

📈 O Risco pro negocio

❌ O erro clássico: E11000

✅ Solução: usar o filtro certo

🧠 Conclusão

Como os pilares da Programação Orientada a Objetos (POO) se conectam ao SOLID

1. Abstração

2. Encapsulamento

3. Herança

4. Polimorfismo

Os 5 Princípios SOLID

1. Single Responsibility Principle (SRP) – Princípio da Responsabilidade Única

2. Open/Closed Principle (OCP) – Princípio Aberto/Fechado

3. Liskov Substitution Principle (LSP) – Princípio da Substituição de Liskov

4. Interface Segregation Principle (ISP) – Princípio da Segregação de Interface

Por que isso importa? (segundo Uncle bob)

5. Dependency Inversion Principle (DIP) – Princípio da Inversão de Dependência

RELAÇÃO: PILARES da POO → PRINCÍPIOS SOLID

Código tem que ser simples

Publicando eventos a partir do domínio - com NestJS

📌 Eventos de Domínio: O que são e por que usar?

🚀 Implementação na prática

🎯 Quando usar eventos de domínio?

📌 Cenário:

Criando o Evento de Domínio

Criando o Agregado Raiz

Criando o Serviço de Usuário

✅ Recapitulando

Links

As três leis do TDD em 'The Clean Coder'

O Ciclo Virtuoso do TDD

Benefícios do TDD

O Maior Benefício: Certeza

State Pattern na prática - pare de sofrer com lógicas de estado bagunçadas

Solução

Exemplo

📌 Passo 1: Definir a Interface do Estado

📌 Passo 2: Criar as Implementações dos Estados

📌 Passo 3: Criar a Classe Account

📌 Passo 4: Testar a Implementação

📌 Explicação

Conclusão

Links

Como testes mudaram minha forma de trabalhar

O que eu fazia antes

O que aprendi

O impacto

Se você ainda não aplica isso, está perdendo tempo

O que acontece quando não tem testes?

O que realmente é um teste automatizado?

📌 Passo 3: Criar a Classe `Account`