Quando uma tarefa simples vira um monstro distribuído

Tutoriais normalmente apresentam serviços isolados. No mundo real, uma spike de entendimento cria o mapa de fronteiras, dependências e planos de contingência que uma entrega distribuída precisa.

A maioria dos tutoriais ensina a criar serviços isolados.
O mundo real não é assim.

Hoje vou abrir o capô de um caso real: um componente visual novo na tela de pós-compra de um e-commerce de alta escala — e um comportamento oculto do Project Reactor que quase derrubou o fluxo inteiro.

A tela de "Parabéns pela compra" de um marketplace

Por que uma feature "simples" precisa de vários microsserviços?

• Alguém precisa decidir se o card aparece (regra de negócio + dado da compra).
• Alguém precisa buscar o conteúdo (texto, ícone, link) sem hardcode no checkout.
• Alguém precisa montar a tela a partir de peças que vêm prontas do servidor.
• Alguém precisa medir se o card funciona, sem travar o fluxo se a medição falhar.

Cada responsabilidade dessas mora, literalmente, num serviço diferente. Antes de ver como eles se conectam, vamos alinhar 3 conceitos.

O que é programação reativa (em 60 segundos)

Em Java, isso chega via Project Reactor (usado pelo Spring WebFlux): Mono<T> representa 0 ou 1 valor assíncrono; Flux<T>, uma sequência de valores. Tudo o que vamos ver hoje é Mono.

Uma rota HTTP é só uma anotação em cima de um método

Se você já viu @Path / @GET do JAX-RS (o padrão Jakarta EE para expor APIs REST em Java) ou @GetMapping do Spring — é a mesma ideia central: uma anotação mapeia um método Java para uma rota HTTP.

@Path("/feedback")
public class FeedbackResource {
  @GET @Path("/{id}")
  public Response get(@PathParam("id") String id) { ... }
}

@RestController
public class FeedbackController {
  @GetMapping("/feedback/{id}")
  public Mono<Feedback> get(@PathVariable String id) { ... }
}

A diferença que importa hoje não é a anotação — é o tipo de retorno: Mono<Feedback> em vez de Feedback. É isso que torna o endpoint não-bloqueante.

O cliente é burro (e isso é ótimo)

{
  "type": "info_card",
  "icon": "document_outline",
  "title": "Meus Direitos",
  "body": "Este produto tem prazo de troca estendido.",
  "action": { "label": "Ver detalhes", "url": "..." }
}

As 5 camadas do ecossistema

Nenhuma camada sabe da regra de negócio da outra. Isso é arquitetura, não acidente. Vamos ver isso como um diagrama de fato.

Como as camadas se conectam

O ciclo de vida de uma requisição

Quem decide não é quem desenha

Essa separação de responsabilidade é o que permite os dois times evoluírem sem se travar um no outro.

Strategy + Factory + switch exaustivo

public class RightsCardStrategy
    implements CardStrategy {

  public boolean handles(CardType t) {
    return t == CardType.MEUS_DIREITOS;
  }

  public Brick buildBrick(ctx) {
    // ícone, título, deeplink
  }
}

return switch (cardType) {
  case MEUS_DIREITOS ->
      rightsCardStrategy.buildBrick(ctx);
  case FRETE_GRATIS  ->
      shippingStrategy.buildBrick(ctx);
  case RECOMENDADO  ->
      recommendedStrategy.buildBrick(ctx);
  // esquecer um case aqui NÃO COMPILA
};

Segurança em tempo de compilação: adicionar um card novo sem registrar o case quebra o build — não a produção. Essa é a "fonte única de verdade" que decide se um card renderiza.

Mudanças aditivas são as únicas seguras

"real_state": {
  "meusDireitos": {}
}

"real_state": {
  "meusDireitos": {
    "title": "Meus Direitos",
    "deadline": "30 dias"
  }
}

O middleend precisa conhecer o campo novo antes do backend ir pra produção — mudança de contrato é coisa de dois times, coordenada.

Como agregamos 7 fontes de dados em paralelo

O middleend não espera uma fonte terminar pra chamar a próxima — ele dispara todas ao mesmo tempo e junta o resultado com Mono.zip(): recomendações, frete, pontos de fidelidade, upsell, avaliação, compartilhamento e o card de "Meus Direitos".

Mono.zip(
    recomendacoesMono, freteMono, pontosMono,
    upsellMono, avaliacaoMono, compartilharMono,
    meusDireitosMono
).map(tuple -> montarTela(tuple));

Mono.zip() só emite quando todos os Monos emitirem. É rápido, é elegante — e tem uma armadilha que não está em nenhum tutorial de WebFlux.

O perigo oculto do Mono.zip()

Uma pergunta simples decide o destino das outras 6 chamadas:o que o handler retorna quando dá erro?

Isso não está em nenhum tutorial de WebFlux. E vai derrubar sua tela inteira em produção se você não souber.

Como o bug se esconde numa linha de fallback

public Mono<RightsCard> buscarMeusDireitos(PurchaseContext ctx) {
    return governanceApiClient.getContent(ctx.categoryId())
        .onErrorResume(ex -> Mono.empty()); // ⚠️ cancela o zip inteiro
}

Parece defensivo — "se der erro, retorno vazio". Mas dentro de um Mono.zip(), vazio ≠ ausência de valor. Um Mono vazio nunca emite, e o zip fica esperando para sempre por um valor que não vai chegar → cancela tudo.

A correção é trocar "vazio" por "objeto vazio"

public Mono<RightsCard> buscarMeusDireitos(PurchaseContext ctx) {
    return governanceApiClient.getContent(ctx.categoryId())
        .onErrorResume(ex -> Mono.just(RightsCard.builder().build())); // ✅ fail-safe real
}

Agora o Mono emite um valor — só que esse valor representa "nada para mostrar". O zip() recebe seus 7 valores, monta a tela normalmente, e o middleend simplesmente não desenha o card.

Demo: derrubando (e consertando) o zip()

→ Abrir Demo interativa agora!

Um detalhe de default, um efeito cascata

• Com Mono.empty(): a resposta inteira nunca chega — as outras 6 fontes trabalharam à toa.
• Com Mono.just(objetoVazio): a resposta chega completa, e o card só não aparece.
• A diferença é uma linha de código. O impacto é o fluxo inteiro do usuário.

O que é uma feature flag?

if (featureFlags.isEnabled("ff-meus-direitos", ctx.categoryId())) {
    // busca conteúdo e monta o card
}

Guarde esse conceito — ele volta duas vezes: no obstáculo do bot de review e na hora de falar de deploy.

Ferramentas de review não têm contexto de arquitetura

Saber quando confiar na ferramenta e quando questionar é parte do trabalho — não terceirizável.

Deploy é parte da feature

• O middleend precisa conhecer o campo novo antes do backend ir pra produção.
• Esquecer um case no switch exaustivo não sobe — o compilador barra.
• A ordem de deploy, a feature flag e o plano de rollback são desenhados junto com o código, não depois.

Antes de escrever código, descubra onde a decisão acontece.

Mapeie quem recebe o pedido, quem decide a regra e quem só exibe o resultado. Assim, cada mudança vai para o serviço certo.

Em sistemas distribuídos, mudanças aditivas são mais seguras.

Ao criar um novo campo ou comportamento, mantenha o comportamento anterior funcionando. Os serviços podem migrar no próprio ritmo, sem uma entrega “tudo ou nada”.

Código que parece certo pode falhar quando não entendemos o que a ferramenta realmente faz.

Foi o caso de Mono.empty() com zip(): “vazio” não significa “um valor sem conteúdo”; significa que nada foi emitido. Conhecer essa semântica evita bugs escondidos por APIs aparentemente simples.

Bots de review apontam o risco.
Somente o comportamento real confirma, ou não, um bug.

Use ferramentas para levantar hipóteses, mas valide no fluxo: o que cada operador emite, o que o consumidor espera e qual caso o teste cobre.

Uma feature só está pronta quando pode ser ligada,
desligada e revertida.

A ordem de deploy, a feature flag e o rollback fazem parte do desenho. Sem isso, o código existe — mas a entrega ainda é arriscada.