DEV Community: Gustavo B. de Abreu

Sobrevivendo ao Inevitável: Engenharia do Caos na Prática com o ChaosEngineeringMasterDeck

Gustavo B. de Abreu — Sun, 11 Oct 2026 02:18:55 +0000

Se você trabalha com arquiteturas modernas em nuvem e microsserviços, provavelmente já se deparou com a clássica citação de Werner Vogels, CTO da Amazon:

"Failures are a given and everything will eventually fail over time." (Falhas são inevitáveis e tudo falhará com o tempo).

Em sistemas distribuídos, isso não é apenas uma frase de efeito; é uma realidade técnica. Redes sofrem partições, zonas de disponibilidade passam por degradação, storages saturam, garbage collectors pausam execuções e bancos de dados encontram contenções de lock. Conforme os serviços se multiplicam em topologias complexas, o comportamento emergente dessas interações torna-se não linear e altamente imprevisível.

O Limite dos Testes Tradicionais

Historicamente, a engenharia de software concentrou seus esforços de qualidade em testes unitários, testes de integração e testes ponta a ponta. Embora indispensáveis, os testes tradicionais validam exclusivamente condições conhecidas — a essência da premissa assert(A == B) executada em um ambiente isolado e previsível.

O perigo em produção mora no desconhecido: o que acontece quando uma API externa não cai de vez (retornando um HTTP 500 rápido), mas começa a responder com latência intermitente de 900 ms e perda pontual de pacotes? Na ausência de isolamento, isso gera esgotamento de pools de threads, tempestades de retentativas (retry storms) e indisponibilidade generalizada.

É nesse cenário que a Engenharia do Caos (Chaos Engineering) atua:

"Chaos Engineering é a disciplina de experimentar sobre um sistema a fim de construir confiança em sua capacidade de resistir a condições turbulentas em produção." — Principles of Chaos Engineering.

Como sintetizou Nora Jones: "O caos não causa problemas. Ele os revela."

Mudar a mentalidade da equipe significa abandonar a busca utópica por sistemas invulneráveis e adotar a prática de projetar para degradação graciosa, failover testado e contenção ativa.

2. Dissecando o ChaosEngineeringMasterDeck

O ChaosEngineeringMasterDeck consolida os aprendizados desenvolvidos nos GameDays da Amazon e na experiência de resiliência da AWS e Netflix. No fluxo de trabalho do nosso projeto, o Master Deck atua como um catálogo operacional e framework para conduzir testes baseados no método científico.

As 5 Fases de Cada Experimento

Estado Estável (Steady State): Definição do comportamento nominal do sistema orientada a métricas de negócio e experiência do usuário. O Master Deck reforça que métricas puramente computacionais (como CPU a 60%) não garantem que o usuário está sendo atendido. Mede-se o estado estável por indicadores como taxa de checkout por segundo (similar ao SPS da Netflix) ou latência percebida na borda.
Hipótese (Hypothesis): Formulação técnica estruturada no formato "E se...?" (What if...?). Por exemplo: "Se o gateway de pagamentos atrasar 800 ms, o Circuit Breaker abrirá e as requisições serão degradadas graciosamente sem travar o pool de conexões". Princípio-chave: "Never assume. If you haven't verified it, it's probably broken."
Execução (Run Experiment): Injeção da falha com escopo delimitado.
Verificação (Verify): Avaliação precisa do impacto e dos tempos operacionais:
- Time to Detect (Tempo de detecção);
- Time to Graceful Degradation (Tempo de acionamento do fallback);
- MTTR (Mean Time to Repair).

A disponibilidade de qualquer serviço é governada pela relação:

Disponibilidade = MTBF / (MTBF + MTTR)

Como falhas sempre ocorrerão em algum momento (desafiando o MTBF), a automação e o teste contínuo reduzem o MTTR para proteger o SLA.

Melhoria (Improve): Condução de análise pós-incidente (Correction of Errors - COE) e implementação das correções de arquitetura.

Controles Críticos de Segurança

Blast Radius (Raio de Explosão) Controlado: Os testes começam na menor granularidade possível (instância única, tráfego canário ou staging espelhado) antes de expandir.
Emergency Stop (Botão de Aborto Imediato): Se as métricas vitais de negócio ultrapassarem o limiar tolerado de segurança, o experimento é interrompido instantaneamente.

3. Estudo de Caso Prático: Simulando Falha em Microsserviços

Para tangibilizar o processo, aplicamos as diretrizes do Master Deck a uma arquitetura distribuída de e-commerce e processamento de pedidos.

A "Carta" de Caos Selecionada

Identificador da Instrução: DECK-NET-03: Latency & Packet Loss in Downstream Dependency.
Alvo: Rota de comunicação entre o microsserviço de pedidos (Order Service) e o proxy de integração com o gateway de pagamento externo.
Mecanismo de Injeção: Configuração do ToxiProxy para introduzir uma latência de 850 ms (com jitter de ±150 ms) e uma taxa de perda de pacotes de 5%.

# Injetando latência e perda de pacotes via ToxiProxy CLI
toxiproxy-cli toxic add payment_service \
  --type latency \
  --attribute latency=850 \
  --attribute jitter=150

toxiproxy-cli toxic add payment_service \
  --type loss \
  --attribute percent=5

Hipótese do Experimento

"Sob latência média de 850 ms e perda de pacotes de 5% no gateway de pagamento, o Circuit Breaker configurado no Order Service deverá transicionar para o estado OPEN em menos de 5 segundos. Com isso, o fallback será disparado, enviando os pedidos para liquidação assíncrona com confirmação provisória, preservando a taxa de sucesso da rota acima de 99% e impedindo o esgotamento do pool de threads do Tomcat."

Delimitação do Blast Radius

Ambiente: Ambiente de staging espelhado com carga sintética de 350 requisições/s gerada via ferramenta de benchmarking.
Gatilho de Aborto (Emergency Stop): Se a taxa de respostas HTTP 500 subir acima de 2% no API Gateway ou a latência p99 exceder 1.500 ms, a injeção é cessada imediatamente.

4. Observabilidade e Resultados

Cronologia da Execução

Tempo	Comportamento Registrado na Telemetria	Ação dos Padrões de Resiliência
T+00:00	Estado estável: 350 req/s, latência p95 de 42 ms, taxa de erro de 0%.	Sistema operando dentro dos parâmetros nominais.
T+01:00	Ativação dos tóxicos de latência e perda de pacotes no ToxiProxy.	Elevação pontual na fila de conexões pendentes.
T+01:04	A taxa de chamadas lentas excede o limiar de 50% na janela deslizante.	Circuit Breaker transiciona para OPEN.
T+01:05	Chamadas síncronas bloqueadas localmente via fast-fail.	O método de Fallback entra em ação: registra o pedido em status pendente e repassa a liquidação para processamento assíncrono em fila.
T+01:06 - T+08:00	Carga de 350 req/s mantida sob falha da dependência.	Latência p95 cai para 38 ms graças ao retorno imediato do fallback; zero esgotamento de threads.
T+08:00	Remoção do tóxico no ToxiProxy.	O circuito transiciona para HALF-OPEN, valida as chamadas de teste e retorna ao estado CLOSED.

Configuração de Resiliência Aplicada

resilience4j.circuitbreaker:
  instances:
    paymentService:
      slidingWindowType: COUNT_BASED
      slidingWindowSize: 20
      minimumNumberOfCalls: 10
      failureRateThreshold: 50
      slowCallRateThreshold: 50
      slowCallDurationThreshold: 500ms
      waitDurationInOpenState: 10000ms
      permittedNumberOfCallsInHalfOpenState: 5
      automaticTransitionFromOpenToHalfOpenEnabled: true

resilience4j.timelimiter:
  instances:
    paymentService:
      timeoutDuration: 600ms

Implementação do Padrão com Fallback Gracioso

@Service
public class OrderCheckoutService {

    private final PaymentClient paymentClient;
    private final PendingPaymentQueue pendingPaymentQueue;

    @CircuitBreaker(name = "paymentService", fallbackMethod = "processPaymentFallback")
    public CheckoutResponse processOrder(OrderRequest request) {
        PaymentResult result = paymentClient.authorize(request.getPaymentDetails());
        return CheckoutResponse.approved(request.getOrderId(), result.getTransactionId());
    }

    public CheckoutResponse processPaymentFallback(OrderRequest request, Throwable ex) {
        log.warn("Serviço de pagamento indisponível ou instável. Acionando fallback assíncrono.");
        pendingPaymentQueue.enqueueForAsyncProcessing(request);
        return CheckoutResponse.acceptedAsync(request.getOrderId(), 
            "Seu pedido foi recebido e está sendo liquidado em segundo plano.");
    }
}

Padrões Arquiteturais Validados

Circuit Breaker com Fast-Fail: Interrompeu a espera de rede, evitando bloqueio generalizado e exaustão do pool de threads.
Bulkhead (Isolamento de Recursos): A saturação da integração de pagamentos não comprometeu o catálogo de produtos ou endpoints de autenticação.
Retry com Backoff Exponencial e Jitter: Garantiu que o reprocessamento da fila de contingência não gerasse um pico repentino de carga (thundering herd) quando o gateway se recuperou.
Auto-Healing e Multi-AZ: Em testes adicionais de derrubada de nós, o pool de instâncias restabeleceu conexões com a réplica sem indisponibilidade de transações.

5. Conclusão e Lições de Cultura

A execução periódica de experimentos guiados pelo ChaosEngineeringMasterDeck transforma a postura operacional da organização.

Principais Lições Aprendidas

Suposições teóricas não substituem validação prática: Antes do teste, acreditava-se que os timeouts de rede padrão protegeriam a aplicação, quando na prática teriam derrubado o pool de conexões em poucos segundos sob carga moderada.
Cultura Blameless (Sem Culpa): Incidentes identificados durante os testes servem para aprimorar o sistema. Seguindo o modelo de Correction of Errors (COE), a equipe investiga causas sistêmicas por meio dos 5 Porquês, eliminando pontos únicos de falha de forma contínua.
Treinamento e Prontidão de Resposta: Conduzir simulações combate a atrofia de habilidades das equipes de engenharia e operações. Como bem pontuou Jesse Robbins, criador dos GameDays na Amazon: > "You don't choose the moment, the moment chooses you. You only choose how prepared you are when it does."

Engenharia do Caos não é quebrar coisas sem controle; é um método estruturado para assegurar previsibilidade e confiança na infraestrutura.

Nas palavras finais de Adrian Hornsby no Master Deck:

"Chaos Engineering won't make your system more robust, People will." (A Engenharia do Caos não tornará seu sistema mais robusto; as pessoas farão isso).

Referências e Leituras Recomendadas

Principles of Chaos Engineering (principlesofchaos.org).
Chaos Engineering on AWS: Building Resilient Systems — Adrian Hornsby.
ByteByteGo: System Design Interview & Resilient Patterns — Alex Xu.
Release It!: Design and Deploy Production-Ready Software — Michael T. Nygard.
The Amazon Builders' Library: Challenges with Distributed Systems — AWS.

Mastering the Adapter Pattern in Java: Bridging Modern Architectures and Legacy Systems

Gustavo B. de Abreu — Sun, 30 Aug 2026 20:52:01 +0000

1. Fundamental Base: The Problem and the Theory

1.1 Introduction

The Adapter Pattern (also widely known by its alias, Wrapper) belongs to the Structural Design Patterns category. Structural patterns deal with object composition, establishing clean relationships and interfaces across disparate classes to form larger, flexible structures without introducing tight coupling.

According to the canonical definition by the Gang of Four (GoF):

"Convert the interface of a class into another interface clients expect. Adapter lets classes work together that couldn't otherwise because of incompatible interfaces." (Gamma et al., 1994).

In enterprise Java ecosystems, the Adapter pattern serves as an indispensable architectural bridge whenever we need to integrate legacy components, proprietary third-party SDKs, or external services whose contracts diverge from our core domain model.

1.2 The Problem: Architectural Friction with Incompatible Interfaces

In day-to-day software engineering, teams frequently encounter highly stable, battle-tested utilities, mainframe integrations, or third-party libraries whose public interfaces do not match the domain interface required by the consuming system.

When this structural friction occurs, developers often face three problematic alternatives:

Modifying the existing class/service (Adaptee): Often impossible when consuming compiled third-party JARs or closed-source code. Even if the source code is available, forcing low-level infrastructure or external utilities to adopt domain-specific contracts violates the Single Responsibility Principle (SRP).
Polluting the client code: Littering domain services with primitive type conversions, legacy status parsing, and foreign dependencies introduces tight coupling and tech debt.
Rewriting the component from scratch: Incurs massive engineering costs, delivery delays, and high regression risks in critical, already-validated business logic.

The core problem the Adapter pattern solves is: how can we enable collaboration between decoupled, unrelated classes without altering either the client's expected interface or the existing component's implementation

1.3 The Concept: How the Pattern Works

The Physical Analogy

Consider international travel: you bring a laptop with a standard Brazilian/European three-pin power plug and need to plug it into a US wall socket (two flat pins).

You cannot break the hotel wall to replace the electrical outlet (Adaptee).
You do not cut off your laptop charger’s cord (Client).
You simply plug your charger into a travel power adapter (Adapter), which accepts your laptop plug on one side and fits into the wall socket on the other, translating the physical interface transparently.

Structural Breakdown

The pattern defines four core participants:

Target: Defines the domain-specific interface that the Client expects and uses.
Client: Collaborates with objects conforming to the Target interface.
Adaptee: Defines the existing, incompatible interface that requires adaptation.
Adapter: Implements the Target interface and delegates requests internally to the Adaptee.

Object Adapter vs. Class Adapter

The GoF specification outlines two distinct implementation strategies:

Object Adapter (Composition-based): The Adapter implements the Target interface and holds an internal reference (composition) to the Adaptee instance. When a target method is called, it translates parameters and invokes the corresponding method on the adaptee. This is the standard, idiomatic approach in Java, adhering to the principle of favoring object composition over class inheritance.
Class Adapter (Multiple Inheritance-based): The Adapter inherits simultaneously from both Target and Adaptee. In Java (which does not support multiple inheritance of concrete classes), this variant is only possible when Target is a pure interface and Adaptee is inherited via extends.

2. Development: Case Study, Architecture, and Implementation

2.1 Real-World Scenario: Modern Payment Gateway vs. Legacy Core Banking

Consider a typical high-throughput engineering scenario: an e-commerce platform transitioning towards a modern microservices architecture. The checkout domain enforces a standardized contract (ProcessadorPagamento) using expressive, immutable domain models, BigDecimal precision, UUID transaction tracking, and explicit result objects.

However, settlement operations must integrate directly with an on-premises Legacy Banking System (LegacyBankService). This legacy service is provided via a proprietary binary client and presents several constraints:

It rejects modern domain models and exclusively accepts primitive data types (e.g., transaction amounts formatted as integer cents using long).
It returns raw numeric status codes (where 200 represents success and other integers denote specific failure states) rather than rich domain objects or structured exceptions.
The legacy component cannot be modified, as it is a shared dependency across multiple institutional applications.

Without an architectural buffer, the checkout domain would become coupled to legacy data types, custom status parsing, and external SDK logic. By introducing an Object Adapter, we establish an Anti-Corruption Layer that isolates the domain while delegating execution to the legacy core.

2.2 Visual Representation: Class Structure and System Architecture

1. UML Class Diagram

The class diagram below illustrates the structural relationships between the client, the domain interface, the adapter implementation, and the legacy dependency.

2. High-Level Software Architecture Diagram

The architecture diagram below highlights where the Adapter pattern sits within the end-to-end checkout pipeline, buffering domain microservices from legacy downstream infrastructure.

2.3 Java Implementation

Below is the complete, decoupled, and production-grade implementation of the Adapter pattern in Java.

1. Target Interface & Domain Models

PaymentProcessor.java (Target Interface)

package com.article.adapter.target;

import com.article.adapter.domain.PaymentCharge;
import com.article.adapter.domain.PaymentResult;

/**
 * TARGET: The standard contract expected by modern internal services.
 */
public interface PaymentProcessor {
    PaymentResult process(PaymentCharge charge);
}

Click to view Domain Models (PaymentCharge & PaymentResult)

PaymentCharge.java

package com.article.adapter.domain;

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

/**
 * Immutable Domain Model representing an incoming payment request.
 */
public class PaymentCharge {
    private final String transactionId;
    private final BigDecimal amount;
    private final String customerEmail;

    public PaymentCharge(String transactionId, BigDecimal amount, String customerEmail) {
        if (amount == null || amount.compareTo(BigDecimal.ZERO) &lt;= 0) {
            throw new IllegalArgumentException("Payment amount must be strictly positive.");
        }
        this.transactionId = Objects.requireNonNull(transactionId, "Transaction ID cannot be null.");
        this.customerEmail = Objects.requireNonNull(customerEmail, "Customer email cannot be null.");
        this.amount = amount;
    }

    public String getTransactionId() { return transactionId; }
    public BigDecimal getAmount() { return amount; }
    public String getCustomerEmail() { return customerEmail; }
}

PaymentResult.java

package com.article.adapter.domain;

/**
 * Domain-level result object returned to consuming services.
 */
public class PaymentResult {
    private final boolean successful;
    private final String message;

    public PaymentResult(boolean successful, String message) {
        this.successful = successful;
        this.message = message;
    }

    public boolean isSuccessful() { return successful; }
    public String getMessage() { return message; }

    @Override
    public String toString() {
        return "PaymentResult{successful=" + successful + ", message='" + message + "'}";
    }
}

2. The Legacy Adaptee Component

LegacyBankingService.java (Adaptee)

package com.article.adapter.legacy;

/**
 * ADAPTEE: Closed legacy SDK expecting primitive data types and returning raw status codes.
 */
public class LegacyBankingService {

    public int executeLegacyTransaction(long amountInCents, String transactionCode) {
        System.out.println("[LEGACY CORE BANKING] Processing on-premise transaction...");
        System.out.printf(" -> Identifier: %s | Amount in Cents: %d\n", transactionCode, amountInCents);

        // Simulation: Amounts greater than zero return legacy success code 200
        if (amountInCents > 0) {
            return 200; // Success
        } else {
            return 500; // Error
        }
    }
}

3. The Object Adapter (Anti-Corruption Layer)

LegacyBankingAdapter.java (Adapter)

package com.article.adapter.adapter;

import com.article.adapter.domain.PaymentCharge;
import com.article.adapter.domain.PaymentResult;
import com.article.adapter.legacy.LegacyBankingService;
import com.article.adapter.target.PaymentProcessor;

import java.math.BigDecimal;
import java.math.RoundingMode;

/**
 * ADAPTER: Implements PaymentProcessor (Target) and wraps LegacyBankingService (Adaptee).
 */
public class LegacyBankingAdapter implements PaymentProcessor {

    private final LegacyBankingService legacyBankingService;

    // Composition via Dependency Injection
    public LegacyBankingAdapter(LegacyBankingService legacyBankingService) {
        this.legacyBankingService = legacyBankingService;
    }

    @Override
    public PaymentResult process(PaymentCharge charge) {
        // 1. Data Transformation: Convert BigDecimal to total cents (long)
        long amountInCents = convertToCents(charge.getAmount());

        // 2. Delegation: Forward translated payload to the Adaptee
        int statusCode = legacyBankingService.executeLegacyTransaction(
                amountInCents,
                charge.getTransactionId()
        );

        // 3. Response Translation: Map primitive status codes to rich domain results
        if (statusCode == 200) {
            return new PaymentResult(true, "Transaction settled successfully by core banking.");
        } else {
            return new PaymentResult(false, "Settlement failed. Legacy error code: " + statusCode);
        }
    }

    private long convertToCents(BigDecimal amount) {
        return amount.multiply(BigDecimal.valueOf(100))
                     .setScale(0, RoundingMode.HALF_UP)
                     .longValueExact();
    }
}

4. Client Execution & Demonstration

Click to view OrderService & Main Demonstration Execution

OrderService.java (Client)

package com.article.adapter.client;

import com.article.adapter.adapter.LegacyBankingAdapter;
import com.article.adapter.domain.PaymentCharge;
import com.article.adapter.domain.PaymentResult;
import com.article.adapter.legacy.LegacyBankingService;
import com.article.adapter.target.PaymentProcessor;

import java.math.BigDecimal;
import java.util.UUID;

/**
 * CLIENT: Consumes the PaymentProcessor contract without direct coupling to legacy code.
 */
public class OrderService {

    private final PaymentProcessor paymentProcessor;

    public OrderService(PaymentProcessor paymentProcessor) {
        this.paymentProcessor = paymentProcessor;
    }

    public void completeCheckout(PaymentCharge charge) {
        System.out.println("[CLIENT] Submitting payment request to processor...");
        PaymentResult result = paymentProcessor.process(charge);
        System.out.println("[CLIENT] Result received: " + result.getMessage());
    }

    public static void main(String[] args) {
        // 1. Instantiate the legacy SDK (Adaptee)
        LegacyBankingService legacySdk = new LegacyBankingService();

        // 2. Wrap the Adaptee with our Adapter
        PaymentProcessor adapter = new LegacyBankingAdapter(legacySdk);

        // 3. Inject the Adapter into the Client
        OrderService checkout = new OrderService(adapter);

        PaymentCharge charge = new PaymentCharge(
                UUID.randomUUID().toString(),
                new BigDecimal("250.75"),
                "customer@email.com"
        );

        checkout.completeCheckout(charge);
    }
}

2.4 Trade-offs: Pros and Cons

Adopting the Adapter pattern requires evaluating architectural benefits against operational trade-offs:

Pros

Adherence to the Single Responsibility Principle (SRP): Encapsulates data conversion and contract translation away from the core business logic.
Adherence to the Open/Closed Principle (OCP): New adapters for additional banking providers or third-party services can be introduced without modifying existing client code.
Reusability of Legacy Code: Extends the lifecycle of mission-critical systems without necessitating high-risk complete rewrites.
Anti-Corruption Layer: Protects the domain model from obsolete terminology, primitive obsession, and vendor-specific data structures.

Cons & Trade-offs

Increased Structural Complexity: Introduces additional interfaces and wrapper classes, increasing the overall number of artifacts in the repository.
Indirection Overhead: Adds an extra layer of method delegation and object referencing, though performance impact is negligible in typical enterprise workloads.
Risk of Conceptual Misalignment: If the abstractions between the target and the adaptee differ drastically (such as synchronous calls versus asynchronous queue semantics), the adapter can become overly complex and difficult to maintain.

3. Conclusion: Wrap-up, Reflections, and Next Steps

3.1 Summary

Throughout this article, we examined how the Adapter Design Pattern serves as a foundational enabler for software evolution and architectural resilience. By mediating communication between mismatched interfaces, it enables modern services to collaborate seamlessly with legacy components and closed third-party SDKs without requiring structural modifications on either side.

In our payment processing case study, we demonstrated how the Adapter functions as a robust Anti-Corruption Layer: it safeguards the integrity of the core domain, centralizes low-level data conversions, and translates raw status codes into meaningful domain representations. This approach ensures that legacy stability and modern clean architecture can coexist with minimal coupling.

3.2 Personal Perspective

For a long time, working with legacy codebases often felt like an invitation to tedious rework. In day-to-day software engineering, refactoring and maintaining systems built on outdated architectures without standardized design can be significantly harder than designing new solutions from the ground up. However, delving into the Adapter Pattern reshapes that perspective: it offers a pragmatic strategy to leverage and extend the lifespan of proven systems, reducing rewrite overhead while reinforcing solid architectural decision-making.

In practice, the most noticeable benefit is how cleanly the domain logic remains isolated. The adapter acts as a protective boundary, keeping business rules decoupled from primitive type conversions and proprietary response formats, which dramatically improves testability through interfaces and mocks. Nevertheless, applying the pattern demands architectural discipline: it should not be treated as a catch-all fix. Forcing an adapter between components with fundamentally incompatible concurrency models, transaction boundaries, or domain concepts can introduce accidental complexity and obscure underlying system flaws.

Looking at modern trends—particularly with the surge of AI-driven architectures, multi-agent frameworks, and extensive third-party API integrations—the Adapter pattern remains exceptionally relevant. It provides a clean, standardized mechanism to plug, swap, and orchestrate heterogeneous external services with minimal friction, proving that classical object-oriented design principles remain vital in modern distributed engineering.

3.3 Discussion

Have you implemented the Adapter Pattern in your projects to integrate legacy subsystems, proprietary SDKs, or third-party APIs? What was the biggest hurdle you encountered when mapping divergent data contracts or handling incompatible error models?

💬 Share your insights and experiences in the comments below! Let's discuss lessons learned and best practices for bridging legacy and modern architectures.