DEV Community: Maxwell Anabil

Sobrevivendo ao Caos: como o ChaosEngineeringMasterDeck testa a resiliência de microsserviços

Maxwell Anabil — Fri, 23 Oct 2026 23:24:32 +0000

E se um serviço ficar lento agora? A pergunta importante não é se falhas vão acontecer, mas se a arquitetura consegue absorvê-las sem transformar um problema pequeno em uma indisponibilidade geral.

Introdução: por que provocar falhas de propósito?

Em sistemas distribuídos, uma aplicação pode funcionar perfeitamente em condições normais e ainda assim falhar quando uma dependência fica lenta, uma instância desaparece ou uma conexão com o banco de dados é interrompida. Isso acontece porque os serviços não trabalham isoladamente: filas, redes, APIs, caches e bancos de dados criam relações que podem amplificar uma falha inicial.

Chaos Engineering, ou engenharia do caos, é a prática de realizar experimentos controlados para descobrir como um sistema se comporta diante de situações adversas. A ideia não é causar indisponibilidade por diversão, nem testar sem planejamento. É formular uma hipótese, introduzir uma falha limitada, observar o comportamento real e usar as evidências para melhorar a arquitetura. Os princípios da disciplina recomendam medir o estado normal do sistema, experimentar com eventos realistas e procurar diferenças entre o comportamento esperado e o comportamento observado [1].

Essa abordagem muda a mentalidade da equipe. Em vez de assumir que tudo deve funcionar sempre, partimos do princípio de que componentes podem falhar — e projetamos o sistema para limitar o impacto, continuar oferecendo funções essenciais e se recuperar com segurança.

Então, por que testar em staging ou até mesmo em produção? Testes em ambientes de homologação reduzem o risco inicial e são o ponto de partida recomendado. Com maturidade, controles e autorização, experimentos cuidadosamente delimitados em produção podem revelar comportamentos que não aparecem em ambientes artificiais, por exemplo, devido ao tráfego real e às dependências de verdade. Não se começa derrubando serviços críticos em produção: começa-se pequeno, com monitoramento, plano de interrupção e critérios objetivos para interromper o teste. A documentação do AWS Fault Injection Service também recomenda planejar o experimento e começar em ambiente de teste ou pré-produção [2].

O que é o ChaosEngineeringMasterDeck?

Neste projeto, o ChaosEngineeringMasterDeck é um catálogo versionado de experimentos de resiliência apresentado como um baralho de cartas. Cada carta descreve uma falha possível e transforma essa falha em um experimento repetível, com objetivo, limites, métricas e procedimento de recuperação.

O formato de baralho torna a prática mais acessível durante revisões de arquitetura, simulações de incidentes e dinâmicas de equipe. Uma carta pode ser sorteada em uma sessão de treinamento, mas sua execução não deve ser improvisada: ela precisa ter sido revisada, aprovada e preparada para o ambiente definido.

O Deck não substitui ferramentas de injeção de falhas, telemetria ou automação. Ele funciona como uma camada de padronização e governança sobre essas ferramentas, registrando por que o experimento existe, como será executado e quais evidências indicarão sucesso ou falha.

O que cada carta contém?

Identificação e objetivo: nome, serviço-alvo, ambiente e risco que queremos investigar.
Hipótese: o comportamento que esperamos observar depois de introduzir a falha.
Estado estável (steady state): indicadores que descrevem o funcionamento normal para o usuário, como latência, taxa de erro e conclusão de operações importantes.
Variável de caos: a condição que será alterada, como latência de rede, indisponibilidade de uma instância ou falha de conexão.
Blast radius: limites explícitos sobre quais serviços, usuários, requisições e recursos poderão ser afetados.
Observabilidade: painéis, logs, métricas, rastreamentos distribuídos e alertas que serão consultados.
Critérios de abortagem e recuperação: condições para interromper o teste, como restaurar o serviço e como confirmar que tudo voltou ao normal.
Resultado e aprendizado: evidências coletadas, lacunas identificadas e ações corretivas com responsáveis.

Esse modelo impede que a experiência se resuma a “derrubamos alguma coisa e vimos no que deu”. O experimento passa a ter uma hipótese que pode ser confirmada, refutada ou refinada.

Exemplo de uma carta do Deck

id: CE-004
nome: Latência elevada no serviço de recomendações
ambiente: staging
alvo: recommendation-service
falha:
  tipo: latencia
  atraso_adicional: 800ms
  duracao: 5m
blast_radius:
  trafego: usuarios-sinteticos
  percentual_maximo: 10%
  endpoint: /api/recommendations
hipotese: >
  O catálogo continuará respondendo em até 500 ms no p95,
  a taxa global de erros ficará abaixo de 1% e a compra
  continuará funcionando mesmo sem recomendações personalizadas.
abortagem:
  - taxa_global_de_erros_acima_de: 1%
  - alerta_critico_disparado
  - falha_no_fluxo_de_compra

Os valores do exemplo são parâmetros ilustrativos para o cenário deste artigo. Em uma aplicação real, limites e métricas precisam ser definidos a partir dos SLOs, dos dados históricos e do impacto aceitável para o negócio.

Estudo de caso: recomendações lentas, catálogo disponível

Imagine uma loja virtual implantada na AWS. A aplicação usa microsserviços Java com Spring Boot e executa tarefas em mais de uma zona de disponibilidade. O balanceador distribui as requisições, e a tela de produtos consulta dois serviços: o Catálogo, responsável pelos dados essenciais dos produtos, e o Recomendações, que personaliza sugestões com base no perfil do cliente.

A recomendação melhora a experiência, mas não é indispensável para consultar um produto ou concluir uma compra. Se esse serviço ficar lento, o sistema deve continuar útil: a página pode mostrar uma lista popular previamente armazenada em cache, em vez de manter a requisição inteira bloqueada.

1. Hipótese e estado estável

Antes do experimento, a equipe observa o sistema em condições normais e define o que significa “saudável” do ponto de vista do cliente. Para esta simulação didática, usaremos a seguinte linha de base:

Indicador	Estado normal ilustrativo	Limite durante o experimento
Latência p95 do Catálogo	210 ms	Até 500 ms
Taxa global de erros HTTP	0,2%	Abaixo de 1%
Conclusão do fluxo de compra	99,7%	Sem queda relevante atribuível ao teste
Fallback de recomendações	Não acionado normalmente	Deve assumir quando necessário

A hipótese é: se adicionarmos 800 ms de latência ao serviço de recomendações por cinco minutos, o Catálogo continuará dentro do limite de latência, a taxa global de erros permanecerá abaixo de 1% e o fluxo de compra não será interrompido.

A hipótese é mensurável. Assim, a equipe não depende de impressões como “pareceu rápido” ou “ninguém percebeu nada”.

2. Execução controlada e Blast Radius

O experimento começa em staging, com dados de teste e geração de tráfego sintético. A falha é aplicada somente ao caminho de comunicação com o serviço de recomendações, por meio de um proxy de teste ou ferramenta de injeção de falhas. Apenas até 10% das requisições sintéticas entram nesse caminho, e a duração máxima é de cinco minutos.

Esse limite é o Blast Radius, ou raio de explosão: a área potencialmente afetada caso algo saia do previsto. Neste caso, ele exclui o serviço de pagamentos, o banco de dados de pedidos e o tráfego de clientes reais. O time também define antecipadamente quem pode iniciar o experimento, quem acompanha os painéis e quem pode encerrá-lo.

O teste é cancelado automaticamente ou manualmente se a taxa global de erros superar 1%, se o fluxo de compra falhar ou se um alerta crítico for acionado. Ao terminar, a injeção de latência é removida e a equipe verifica a recuperação. Esses limites são essenciais porque ferramentas como o AWS Fault Injection Service executam ações reais sobre recursos selecionados; por isso, a seleção dos alvos e os controles devem ser revisados antes da execução [2].

3. Quais padrões de resiliência esperamos observar?

Timeouts: a chamada ao serviço de recomendações tem um limite de espera. Sem timeout, uma chamada lenta poderia ocupar conexões e threads por tempo excessivo.

Circuit Breaker: quando as chamadas falham ou ultrapassam os limites configurados, o disjuntor abre temporariamente e impede novas chamadas repetidas ao serviço degradado. Isso reduz a chance de que uma dependência lenta consuma os recursos do restante da aplicação. Em projetos Spring Boot, bibliotecas como Resilience4j oferecem suporte a Circuit Breaker, Retry, Bulkhead e TimeLimiter [3].

Fallback: com o serviço de recomendações indisponível, a aplicação utiliza uma lista de produtos populares armazenada em cache. O fallback não deve fabricar resultados críticos nem declarar uma operação financeira como concluída; ele só substitui a funcionalidade opcional de personalização.

Bulkhead: limites de concorrência isolam os recursos usados pelas chamadas de recomendação, reduzindo o risco de que elas esgotem as threads ou conexões necessárias ao Catálogo.

Retries limitados: novas tentativas, quando necessárias, usam limite e intervalo de espera. Repetir chamadas indefinidamente pode amplificar uma falha e gerar uma tempestade de retries. Em uma dependência já lenta, pode ser melhor falhar rápido e acionar o fallback.

O escalonamento automático pode ajudar quando o problema é falta de capacidade, mas não corrige automaticamente toda falha. Se a causa for uma dependência travada, aumentar a quantidade de instâncias pode não resolver — e, em alguns casos, até aumentar a pressão sobre essa dependência.

4. Observabilidade: como sabemos se funcionou?

Durante o teste, o time acompanha um painel com métricas e sinais correlacionados:

Métricas: latência p50/p95/p99, taxa de erros, volume de requisições, timeouts, estado do Circuit Breaker, uso de CPU e memória e taxa de acionamento do fallback.
Logs estruturados: registros com identificador de correlação, para encontrar uma requisição ao longo dos serviços sem expor dados sensíveis.
Rastreamento distribuído: traces para confirmar em qual dependência o tempo foi consumido e se o atraso se propagou ao Catálogo.
Alertas: notificações sobre violações dos limites definidos e sinais de degradação do fluxo de compra.

A equipe deve monitorar tanto o serviço atingido quanto a experiência do usuário. Uma queda no consumo de CPU, por exemplo, não prova que o sistema está saudável: o serviço pode estar recusando requisições. Da mesma forma, a aplicação pode continuar respondendo com HTTP 200, mas entregar uma experiência lenta ou incompleta. Por isso, indicadores técnicos precisam estar ligados a resultados observáveis para o cliente. Os princípios de Chaos Engineering destacam latência, vazão e taxa de erros como medidas possíveis do estado estável [1].

5. Resultados ilustrativos da simulação

Como este artigo descreve um cenário didático, os números a seguir são resultados hipotéticos de referência, não medições de um experimento real:

Indicador	Exemplo de resultado	Interpretação
Latência p95 do Catálogo	285 ms	Abaixo do limite de 500 ms
Taxa global de erros HTTP	0,6%	Abaixo do limite de 1%
Recomendações personalizadas	Degradadas durante a injeção	Falha isolada na funcionalidade opcional
Fallback	Acionado com sucesso	Página continuou oferecendo sugestões genéricas
Fluxo de compra	Sem interrupção atribuível ao teste	Função essencial preservada

Nesse resultado ilustrativo, a hipótese seria aceita: a falha local não comprometeu o caminho crítico. Ainda assim, o teste não provaria que o sistema está preparado para todo tipo de incidente. Ele mostraria apenas que um tipo específico de latência, dentro dos limites definidos, foi absorvido de forma aceitável.

Caso os indicadores ultrapassassem os limites, isso não seria simplesmente um “teste fracassado”. Seria uma evidência útil: talvez o timeout estivesse alto demais, o Circuit Breaker abrisse tarde, o fallback dependesse da mesma infraestrutura degradada ou a concorrência das chamadas não estivesse isolada. A equipe registraria a descoberta, corrigiria a arquitetura e repetiria o mesmo experimento para confirmar a melhoria.

Como ampliar o Deck com segurança

Depois de validar experimentos menores, o catálogo pode incluir cartas para cenários mais amplos, como falha de conexão com o banco, indisponibilidade de uma instância, esgotamento de recursos ou perda de uma zona de disponibilidade. A AWS, por exemplo, documenta um cenário de interrupção de energia de uma Availability Zone para avaliar aplicações distribuídas em múltiplas zonas [4]. Esse tipo de teste tem raio de impacto muito maior e exige revisão específica de alvos, permissões, dependências, capacidade de recuperação e plano de interrupção.

Uma progressão sensata é:

Começar em ambiente de teste, com um alvo e uma falha simples.
Conferir observabilidade e abortagem antes de aumentar o alcance.
Automatizar a execução e a coleta de resultados, evitando depender de memória individual.
Repetir após mudanças relevantes, como alterações de arquitetura, infraestrutura ou bibliotecas de resiliência.
Avançar para ambientes mais representativos gradualmente, incluindo produção somente quando houver maturidade operacional, autorização e limites seguros.

O Deck também deve guardar o que foi aprendido: hipótese inicial, configuração aplicada, horário, métricas antes/durante/depois, alarmes acionados, incidentes observados e ações corretivas. Assim, um resultado deixa de ser uma experiência isolada e passa a fortalecer o conhecimento coletivo da equipe.

Conclusão: resiliência se demonstra, não se presume

Nenhuma arquitetura distribuída elimina todas as falhas. O objetivo da engenharia de resiliência é evitar que uma falha localizada se transforme em um problema sistêmico, proteger os fluxos essenciais e recuperar o serviço dentro de limites aceitáveis.

O ChaosEngineeringMasterDeck organiza essa prática em experimentos repetíveis e compreensíveis: cada carta descreve uma hipótese, limita o Blast Radius, define métricas de controle e registra o aprendizado. No estudo de caso, a latência é aplicada a uma funcionalidade opcional para verificar se o Catálogo e o fluxo de compra continuam operando.

A principal lição é cultural: confiabilidade não é responsabilidade exclusiva de uma equipe de infraestrutura nem uma etapa realizada somente antes do lançamento. Desenvolvimento, operações, arquitetura e produto precisam compartilhar hipóteses, dados e decisões. Quando o caos é introduzido com método e segurança, ele deixa de ser apenas uma ameaça e se torna uma oportunidade de aprender — antes que uma falha real ensine a mesma lição aos clientes.

Referências

Principles of Chaos Engineering. Fundamentos de estado estável, hipóteses, eventos realistas e minimização do Blast Radius. https://principlesofchaos.org/
AWS — Planning your AWS FIS experiments. Recomendações para planejar experimentos, definir o estado estável, formular hipóteses e começar em ambientes de teste. https://docs.aws.amazon.com/fis/latest/userguide/getting-started-planning.html
Resilience4j — Getting Started. Biblioteca de tolerância a falhas com Circuit Breaker, Retry, Bulkhead, Cache e TimeLimiter. https://resilience4j.readme.io/docs/getting-started
AWS — AZ Availability: Power Interruption. Cenário para avaliar os efeitos de uma interrupção em uma zona de disponibilidade. https://docs.aws.amazon.com/fis/latest/userguide/az-availability-scenario.html
Microsoft Azure Well-Architected Framework — Reliability testing strategy. Conceitos de resiliência, recuperação, injeção de falhas e testes de confiabilidade. https://learn.microsoft.com/en-us/azure/well-architected/reliability/reliability-test

Nota sobre o estudo de caso: a arquitetura e os resultados numéricos deste artigo são ilustrativos e foram incluídos para demonstrar como estruturar um experimento. Eles não representam uma execução real nem resultados observados em um ambiente de produção.

Adapter Pattern em Java: integrando novas transportadoras sem quebrar um sistema legado

Maxwell Anabil — Wed, 09 Sep 2026 19:29:59 +0000

Maxwell Anabil Macabeu da Silva

Bacharelado em Engenharia de Software — UniEvangélica

Anápolis — Goiás — Brasil

Resumo

Sistemas de e-commerce dependem de integrações com serviços externos, como gateways de pagamento, plataformas de logística e transportadoras. Um problema recorrente aparece quando cada fornecedor disponibiliza uma API diferente, com métodos, formatos de dados e estruturas de resposta incompatíveis com o sistema existente.

Neste artigo apresento a aplicação do Adapter Pattern, um padrão estrutural do catálogo GoF, em um cenário de integração de transportadoras dentro de um sistema de e-commerce desenvolvido em Java.

A proposta é criar uma interface padrão utilizada pelo sistema e implementar adaptadores responsáveis por traduzir a comunicação com diferentes APIs externas. Dessa forma, o sistema principal não precisa conhecer os detalhes específicos de cada transportadora.

Além da explicação do padrão, será apresentado um estudo de caso, um diagrama UML de classes, uma visão de arquitetura, uma implementação em Java e uma análise das vantagens e dos trade-offs envolvidos.

Palavras-chave: Adapter Pattern; Design Patterns; Java; Engenharia de Software; APIs; Integração de Sistemas; E-commerce.

1. Base Fundamental

1.1 O que são Design Patterns?

Durante o desenvolvimento de software, alguns problemas aparecem repetidamente em diferentes projetos.

Como organizar a criação de objetos? Como permitir que comportamentos sejam alterados sem modificar várias partes do sistema? Como integrar sistemas que possuem interfaces incompatíveis?

Os Design Patterns, ou padrões de projeto, representam soluções conhecidas e reutilizáveis para problemas recorrentes de design de software.

Eles não são códigos prontos que simplesmente copiamos para o projeto. Na realidade, são maneiras de estruturar classes e responsabilidades para resolver determinados tipos de problema.

Os padrões originalmente apresentados pelo chamado Gang of Four (GoF) são geralmente divididos em três grupos:

Categoria	Objetivo	Exemplos
Criacionais	Organizam a criação de objetos	Factory Method, Builder, Singleton
Estruturais	Organizam como objetos e classes se relacionam	Adapter, Decorator, Facade
Comportamentais	Organizam responsabilidades e comportamentos	Strategy, Observer, Command

O padrão abordado neste artigo é o Adapter Pattern, pertencente à categoria dos padrões estruturais.

1.2 O problema: quando cada API fala uma língua diferente

Imagine um sistema de e-commerce que possui um módulo responsável por calcular o valor do frete de um pedido.

Inicialmente, a empresa utilizava apenas uma transportadora. O código poderia ser semelhante a:

public class ShippingService {

    private LegacyCarrierClient client;

    public BigDecimal calculateShipping(
            String originZip,
            String destinationZip,
            int weightInGrams) {

        return client.calculate(
                originZip,
                destinationZip,
                weightInGrams
        );
    }
}

Enquanto existe apenas uma integração, essa estrutura parece suficiente.

O problema aparece quando a empresa decide oferecer mais opções de entrega. Uma segunda transportadora pode possuir algo semelhante a:

fastShipClient.getRate(
    new FastShipPayload(
        origin,
        destination,
        weightInKg
    )
);

Observe que as duas APIs não trabalham da mesma maneira.

Uma pode utilizar peso em gramas, parâmetros separados e valor retornado em centavos. Outra pode utilizar peso em quilogramas, um objeto de requisição e valor retornado como BigDecimal.

O sistema começa então a acumular verificações:

if (carrier.equals("LEGACY")) {

    // chama API da primeira transportadora

} else if (carrier.equals("FAST_SHIP")) {

    // converte peso
    // cria payload
    // chama outra API
    // converte resposta

} else if (carrier.equals("OUTRA_TRANSPORTADORA")) {

    // outra implementação
}

Quanto mais integrações surgem, maior fica esse código.

Além disso, o ShippingService passa a conhecer detalhes que não deveriam fazer parte de sua responsabilidade, como formato de requisição de cada fornecedor, unidades de medida, nomes de métodos externos, estruturas de resposta e tratamento específico de cada API.

É exatamente nesse tipo de situação que o Adapter Pattern pode ajudar.

1.3 Como funciona o Adapter Pattern?

A palavra adapter significa adaptador.

Uma analogia simples é um adaptador de tomada. Você possui um dispositivo com um padrão de tomada, mas chega a um local onde a tomada possui outro formato. Em vez de modificar o aparelho ou a instalação elétrica, coloca um adaptador entre os dois.

No desenvolvimento de software, a ideia é semelhante:

Sistema existente
       ↓
Interface conhecida pelo sistema
       ↓
Adapter
       ↓
API externa incompatível

O Adapter recebe uma chamada utilizando o formato esperado pelo sistema e realiza a tradução necessária para o formato exigido pelo serviço externo.

Normalmente temos três participantes principais:

Target: interface que o sistema gostaria de utilizar.
Adapter: implementa essa interface e converte a chamada.
Adaptee: classe ou API existente que possui uma interface incompatível.

No nosso exemplo:

Target
ShippingProvider

Adapters
LegacyCarrierAdapter
FastShipAdapter

Adaptees
LegacyCarrierClient
FastShipClient

Assim, o restante do sistema trabalha apenas com ShippingProvider e não precisa saber qual API realmente está por trás daquele objeto.

1.4 Adapter não é Strategy

Os dois padrões podem parecer semelhantes porque ambos utilizam interfaces e composição. Porém, resolvem problemas diferentes.

O Strategy Pattern normalmente é utilizado quando existem diferentes algoritmos capazes de executar uma mesma tarefa.

Já o Adapter Pattern é utilizado principalmente quando queremos tornar interfaces incompatíveis compatíveis.

No nosso cenário, nossa aplicação espera:

quote(ShippingRequest request)

mas uma API externa oferece:

calculate(originZip, destinationZip, weightGrams)

e outra oferece:

getRate(FastShipPayload payload)

O Adapter cria uma camada de tradução entre essas interfaces.

2. Desenvolvimento

2.1 Cenário do Mundo Real

Considere um e-commerce que vende produtos para diferentes regiões e precisa calcular o frete durante o checkout.

O fluxo é aproximadamente:

Cliente seleciona os produtos
          ↓
Informa o endereço
          ↓
Sistema solicita cotações
          ↓
Transportadoras calculam o frete
          ↓
Sistema apresenta preço e prazo
          ↓
Cliente escolhe a opção

Inicialmente, o sistema possuía integração apenas com uma transportadora. Com o crescimento da operação, surgiu a necessidade de conectar novos provedores logísticos.

Porém, cada fornecedor possuía sua própria API.

Um deles trabalhava com peso em gramas, enquanto outro utilizava quilogramas. Um retornava valores em centavos, enquanto outro retornava BigDecimal. Um utilizava vários parâmetros no método, enquanto outro esperava um objeto de requisição.

Alterar o ShippingService sempre que uma nova integração fosse adicionada faria com que o serviço se tornasse cada vez mais acoplado às APIs externas.

A solução escolhida é definir uma interface comum chamada ShippingProvider. Cada API externa recebe então seu próprio Adapter.

2.2 Diagrama UML de Classes

Figura 1 — Diagrama UML do Adapter Pattern aplicado ao serviço de fretes.

O ponto mais importante do diagrama é observar que o ShippingService depende apenas de ShippingProvider.

Ele não conhece diretamente LegacyCarrierClient nem FastShipClient. Esses detalhes ficam escondidos dentro dos adapters.

2.3 Arquitetura de Software

Figura 2 — Arquitetura de alto nível do sistema de cotação de fretes.

O cliente não entra em contato diretamente com as transportadoras.

O Order Service solicita ao Shipping Service uma cotação. Dentro do Shipping Service, os adapters ficam responsáveis por conversar com cada API externa.

Essa separação é importante porque uma alteração realizada por uma transportadora afeta principalmente seu Adapter, em vez de espalhar modificações pelo restante da aplicação.

2.4 Implementação em Java

2.4.1 Representando a solicitação de frete

import java.math.BigDecimal;
import java.util.Objects;

public record ShippingRequest(
        String originZip,
        String destinationZip,
        BigDecimal weightKg
) {

    public ShippingRequest {

        Objects.requireNonNull(originZip);
        Objects.requireNonNull(destinationZip);
        Objects.requireNonNull(weightKg);

        if (weightKg.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException(
                    "O peso deve ser maior que zero."
            );
        }
    }
}

Independentemente da transportadora utilizada, nosso sistema trabalhará internamente com peso em quilogramas.

2.4.2 Representando a resposta

import java.math.BigDecimal;

public record ShippingQuote(
        String provider,
        BigDecimal price,
        int deliveryDays
) {
}

Agora qualquer transportadora utilizada pelo sistema deverá fornecer nome do provedor, preço e prazo de entrega.

2.4.3 Criando a interface padrão

Este é o nosso Target:

public interface ShippingProvider {

    ShippingQuote quote(ShippingRequest request);

}

O ShippingService conhecerá somente essa interface.

Ele não precisa conhecer nenhuma API externa diretamente.

2.4.4 API da primeira transportadora

Imagine que uma integração antiga utiliza esta interface:

public interface LegacyCarrierClient {

    LegacyCarrierResponse calculate(
            String originZip,
            String destinationZip,
            int weightInGrams
    );

}

E retorna:

public record LegacyCarrierResponse(
        long priceInCents,
        int estimatedDays
) {
}

Nosso sistema trabalha com quilogramas e BigDecimal, enquanto essa integração utiliza gramas e centavos.

As interfaces são incompatíveis.

2.4.5 Criando o primeiro Adapter

É aqui que entra o padrão:

import java.math.BigDecimal;

public class LegacyCarrierAdapter
        implements ShippingProvider {

    private final LegacyCarrierClient client;

    public LegacyCarrierAdapter(
            LegacyCarrierClient client
    ) {
        this.client = client;
    }

    @Override
    public ShippingQuote quote(
            ShippingRequest request
    ) {

        int weightInGrams = request
                .weightKg()
                .multiply(BigDecimal.valueOf(1000))
                .intValueExact();

        LegacyCarrierResponse response =
                client.calculate(
                        request.originZip(),
                        request.destinationZip(),
                        weightInGrams
                );

        BigDecimal price = BigDecimal
                .valueOf(response.priceInCents())
                .movePointLeft(2);

        return new ShippingQuote(
                "Legacy Carrier",
                price,
                response.estimatedDays()
        );
    }
}

Perceba que toda a incompatibilidade ficou dentro dessa classe.

O Adapter realiza as conversões necessárias e transforma a resposta externa em um ShippingQuote.

O restante do sistema não precisa conhecer nenhuma dessas conversões.

2.4.6 Integrando uma segunda transportadora

Agora imagine uma API mais moderna:

public interface FastShipClient {

    FastShipRate getRate(
            FastShipPayload payload
    );

}

Seu payload:

import java.math.BigDecimal;

public record FastShipPayload(
        String from,
        String to,
        BigDecimal weight
) {
}

E sua resposta:

import java.math.BigDecimal;

public record FastShipRate(
        BigDecimal amount,
        int businessDays
) {
}

Novamente, podemos criar um Adapter:

public class FastShipAdapter
        implements ShippingProvider {

    private final FastShipClient client;

    public FastShipAdapter(
            FastShipClient client
    ) {
        this.client = client;
    }

    @Override
    public ShippingQuote quote(
            ShippingRequest request
    ) {

        FastShipPayload payload =
                new FastShipPayload(
                        request.originZip(),
                        request.destinationZip(),
                        request.weightKg()
                );

        FastShipRate response =
                client.getRate(payload);

        return new ShippingQuote(
                "Fast Ship",
                response.amount(),
                response.businessDays()
        );
    }
}

Apesar de as duas APIs externas serem diferentes, para o restante do sistema elas agora possuem exatamente o mesmo contrato:

ShippingQuote quote(ShippingRequest request);

Esse é o principal benefício do Adapter Pattern.

2.4.7 O ShippingService

Agora podemos criar um serviço que recebe diversas implementações de ShippingProvider:

import java.util.Comparator;
import java.util.List;

public class ShippingService {

    private final List<ShippingProvider> providers;

    public ShippingService(
            List<ShippingProvider> providers
    ) {
        this.providers = providers;
    }

    public ShippingQuote bestQuote(
            ShippingRequest request
    ) {

        return providers.stream()
                .map(provider ->
                        provider.quote(request)
                )
                .min(
                    Comparator.comparing(
                        ShippingQuote::price
                    )
                )
                .orElseThrow(() ->
                    new IllegalStateException(
                        "Nenhuma transportadora disponível."
                    )
                );
    }
}

Observe que não existe um if ou switch para tratar cada transportadora.

O serviço simplesmente sabe que possui objetos capazes de executar quote(request).

A implementação específica deixa de ser responsabilidade dele.

2.4.8 Utilizando o serviço

Um exemplo simplificado seria:

import java.math.BigDecimal;
import java.util.List;

public class CheckoutDemo {

    public static void main(String[] args) {

        ShippingProvider legacyProvider =
                new LegacyCarrierAdapter(
                        new LegacyCarrierClientImpl()
                );

        ShippingProvider fastShipProvider =
                new FastShipAdapter(
                        new FastShipClientImpl()
                );

        ShippingService shippingService =
                new ShippingService(
                        List.of(
                                legacyProvider,
                                fastShipProvider
                        )
                );

        ShippingRequest request =
                new ShippingRequest(
                        "75000-000",
                        "74000-000",
                        new BigDecimal("2.5")
                );

        ShippingQuote best =
                shippingService.bestQuote(request);

        System.out.println(
                "Transportadora: " +
                best.provider()
        );

        System.out.println(
                "Frete: R$ " +
                best.price()
        );

        System.out.println(
                "Prazo: " +
                best.deliveryDays() +
                " dias"
        );
    }
}

Se uma terceira transportadora for adicionada posteriormente, podemos criar outra implementação de ShippingProvider e registrá-la no serviço, sem reescrever a lógica de cálculo existente.

2.5 Testabilidade

Outra vantagem dessa estrutura aparece nos testes.

Podemos testar cada Adapter isoladamente:

import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.*;

import java.math.BigDecimal;

import org.junit.jupiter.api.Test;

class LegacyCarrierAdapterTest {

    @Test
    void deveConverterQuilogramasParaGramas() {

        LegacyCarrierClient client =
                mock(LegacyCarrierClient.class);

        when(
            client.calculate(
                "75000-000",
                "74000-000",
                2500
            )
        ).thenReturn(
            new LegacyCarrierResponse(
                1890,
                4
            )
        );

        LegacyCarrierAdapter adapter =
                new LegacyCarrierAdapter(client);

        ShippingRequest request =
                new ShippingRequest(
                    "75000-000",
                    "74000-000",
                    new BigDecimal("2.5")
                );

        ShippingQuote quote =
                adapter.quote(request);

        assertEquals(
                new BigDecimal("18.90"),
                quote.price()
        );

        assertEquals(
                4,
                quote.deliveryDays()
        );
    }
}

O teste consegue verificar a lógica do Adapter sem precisar executar todo o checkout.

Isso facilita encontrar erros em conversões e integrações.

2.6 Boas práticas aplicadas

Além do Adapter Pattern, algumas decisões ajudam a manter o projeto organizado.

A aplicação utiliza injeção de dependência, pois os clientes das transportadoras são recebidos pelo construtor dos Adapters em vez de serem criados internamente.

Também existe uma separação entre os objetos do domínio e os objetos utilizados pelas APIs externas.

Por exemplo, ShippingRequest pertence à aplicação, enquanto FastShipPayload pertence à integração externa.

Essa separação evita que alterações realizadas por uma transportadora contaminem diretamente os modelos internos do sistema.

Outro ponto importante é o uso de BigDecimal para representar valores monetários, evitando problemas comuns de precisão que podem ocorrer com tipos de ponto flutuante.

2.7 Prós e Contras do Adapter Pattern

Como qualquer decisão arquitetural, o Adapter Pattern possui benefícios e custos.

Vantagens

Reduz o acoplamento com bibliotecas e APIs externas.
Permite manter uma interface consistente dentro da aplicação.
Facilita a substituição de fornecedores.
Melhora a testabilidade das integrações.
Concentra conversões e adaptações em classes específicas.
Evita espalhar detalhes de APIs externas pelo sistema.
Facilita adicionar novas integrações.
Favorece o princípio de responsabilidade única.

Desvantagens e trade-offs

Aumenta o número de classes do projeto.
Cada API externa exige seu próprio Adapter.
Mudanças frequentes no fornecedor podem exigir manutenção constante do adaptador.
Em sistemas muito pequenos, a abstração pode ser desnecessária.
Uma má implementação pode transformar o Adapter em uma classe com responsabilidades demais.
O padrão não elimina a complexidade da integração: ele organiza e isola essa complexidade.

Portanto, utilizar Adapter para qualquer integração simples também pode gerar complexidade desnecessária.

O padrão faz mais sentido quando a interface externa realmente é incompatível com o modelo utilizado pelo restante da aplicação.

3. Conclusão

3.1 Resumo

O Adapter Pattern apresenta uma solução simples para um problema comum na engenharia de software: integrar componentes que possuem interfaces diferentes.

No cenário apresentado, cada transportadora possuía sua própria forma de calcular frete.

Sem uma camada de adaptação, o ShippingService precisaria conhecer os detalhes de cada API, criando alto acoplamento e dificultando a manutenção do código.

Com a criação da interface ShippingProvider, o sistema passou a trabalhar com um único contrato.

As classes LegacyCarrierAdapter e FastShipAdapter passaram a ser responsáveis por traduzir a comunicação entre o domínio da aplicação e os serviços externos.

O resultado é uma arquitetura mais desacoplada, extensível e testável.

3.2 Visão Pessoal

Ao estudar o Adapter Pattern, o que mais me chamou atenção foi perceber que um Design Pattern não precisa obrigatoriamente envolver uma solução extremamente complexa.

A ideia do Adapter é relativamente simples: criar uma camada de tradução entre duas interfaces incompatíveis.

Mesmo sendo simples, essa decisão pode ter um impacto grande na organização de um projeto.

Antes de estudar esse padrão, seria natural pensar em adaptar cada nova API diretamente dentro do serviço principal utilizando condicionais e conversões.

Porém, com o Adapter, fica mais claro que os detalhes de integração pertencem a uma classe específica.

Também percebi que padrões de projeto não devem ser aplicados apenas porque existem. Eles precisam resolver um problema real.

Se o sistema possuir apenas uma integração simples e que dificilmente será alterada, talvez criar vários níveis de abstração não seja necessário.

Por outro lado, quando diferentes APIs precisam conviver dentro de um mesmo sistema, o Adapter pode reduzir bastante o acoplamento e tornar futuras alterações mais seguras.

Para mim, esse foi um dos principais aprendizados: Design Patterns não servem apenas para deixar o código mais sofisticado, mas para tornar determinadas mudanças mais fáceis de realizar.

3.3 E você?

Você já precisou integrar uma API que possuía uma estrutura completamente diferente da utilizada pelo seu sistema?

Usaria o Adapter Pattern nesse cenário ou escolheria outra abordagem?

Compartilhe sua opinião nos comentários.

Referências

GAMMA, Erich; HELM, Richard; JOHNSON, Ralph; VLISSIDES, John. Design Patterns: Elements of Reusable Object-Oriented Software. Boston: Addison-Wesley, 1994.

FOWLER, Martin. Refactoring: Improving the Design of Existing Code. 2. ed. Boston: Addison-Wesley, 2018.

FREEMAN, Eric; ROBSON, Elisabeth. Head First Design Patterns. 2. ed. Sebastopol: O'Reilly Media, 2020.