O problema não é o conceito. O problema é que a maioria do conteúdo que existe sobre Agent Skills é tão raso quanto as skills que ensina a criar.

Se você já julgou que LLM’s não entregam qualidade suficiente, ou acredita que o código resultante de uma LLM é ruim, se você já passou por isso e ainda não entendeu como skills podem, de fato, mudar a qualidade do que a IA entrega no seu projeto: Esse post é para você.

Antes de tudo, dois fundamentos

Os modelos LLM possuem “todo o conhecimento do mundo”

Essa afirmação é exagerada, mas não da forma como você imagina.

Do ponto de vista de um projeto de software, o volume de conteúdo ingerido na fase de treinamento é vasto o suficiente para construir qualquer coisa mainstream. É mais que suficiente para quase tudo que já fizemos e tudo que ainda vamos fazer no mercado.

Se você não trabalha para uma agência governamental com uma cadeia de pesquisa ultrassecreta, provavelmente tudo que você quer fazer é factível.

e factível de se fazer bem feito com ajuda da IA.

Mas “bem feito” não é um exercício fácil, muito menos barato. Perde-se tempo, gasta-se dinheiro, e o resultado oscila entre o aceitável e o medíocre.

Agent Skills mudaram isso no meu dia a dia. Entender o porquê é o primeiro passo.

Skills são receitas de foco

Um modelo LLM tem conhecimento sobre praticamente tudo, mas justamente por isso, precisa de direcionamento para entregar algo preciso. É como pedir para alguém que sabe cozinhar qualquer coisa preparar “algo bom”: Sem receita, sem ingredientes definidos, sem restrições. O resultado vai ser comestível, mas dificilmente vai ser o que você queria.

Agent Skills são receitas que conduzem o modelo a filtrar o que ele sabe e focar estritamente no que seu projeto precisa. Uma skill pode ser genérica ou absolutamente específica.

E é na especificidade que mora a diferença entre resultado aceitável e resultado preciso.

Skill não é tool, tool não é feature

Uma tool é uma capacidade atômica. Um único comando que o agente consegue executar: rodar um bash, buscar na web, ler um arquivo, fazer uma chamada HTTP. Ferramentas são martelos, serras e furadeiras.

Uma skill é um conjunto de instruções que ensina o agente a orquestrar múltiplas tools para cumprir uma tarefa complexa com qualidade. A skill não dá capacidades novas ao modelo. Ela dá expertise na combinação das capacidades que já existem. Skills são receitas que dizem quais ferramentas usar, em que ordem, e quais erros evitar.

Uma feature é um conceito de produto — algo que o usuário vê e pode ligar ou desligar. “Code Execution”, “Web Search”, “Artifacts” são features. Cada feature é alimentada por uma combinação de tools e skills trabalhando juntas.

A skill do docx, por exemplo, não dá ao Claude a capacidade de criar Word. Ele já consegue. O que ela faz é ensinar que o docx-js usa A4 por padrão, que bullets unicode quebram em certos viewers, que o page size precisa ser explícito. Sem a skill, o resultado é tecnicamente funcional. Com a skill, é profissional.

Exemplos de Skills

Note quão abstrata são as skills mais famosas, ou mais usadas do mercado

---
name: nano-banana-pro
description: Generate or edit images via Gemini 3 Pro Image (Nano Banana Pro).
homepage: https://ai.google.dev/
metadata:
  {
    "openclaw":
      {
        "emoji": "🍌",
        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"] },
        "primaryEnv": "GEMINI_API_KEY",
        "install":
          [
            {
              "id": "uv-brew",
              "kind": "brew",
              "formula": "uv",
              "bins": ["uv"],
              "label": "Install uv (brew)",
            },
          ],
      },
  }
---

# Nano Banana Pro (Gemini 3 Pro Image)

Use the bundled script to generate or edit images.

Generate

```bash
uv run {baseDir}/scripts/generate_image.py --prompt "your image description" --filename "output.png" --resolution 1K
```

Edit (single image)

```bash
uv run {baseDir}/scripts/generate_image.py --prompt "edit instructions" --filename "output.png" -i "/path/in.png" --resolution 2K
```

Multi-image composition (up to 14 images)

```bash
uv run {baseDir}/scripts/generate_image.py --prompt "combine these into one scene" --filename "output.png" -i img1.png -i img2.png -i img3.png
```

API key

- `GEMINI_API_KEY` env var
- Or set `skills."nano-banana-pro".apiKey` / `skills."nano-banana-pro".env.GEMINI_API_KEY` in `~/.openclaw/openclaw.json`

Notes

- Resolutions: `1K` (default), `2K`, `4K`.
- Use timestamps in filenames: `yyyy-mm-dd-hh-mm-ss-name.png`.
- The script prints a `MEDIA:` line for OpenClaw to auto-attach on supported chat providers.
- Do not read the image back; report the saved path only.

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "google-genai>=1.0.0",
#     "pillow>=10.0.0",
# ]
# ///
"""
Generate images using Google's Nano Banana Pro (Gemini 3 Pro Image) API.

Usage:
    uv run generate_image.py --prompt "your image description" --filename "output.png" [--resolution 1K|2K|4K] [--api-key KEY]

Multi-image editing (up to 14 images):
    uv run generate_image.py --prompt "combine these images" --filename "output.png" -i img1.png -i img2.png -i img3.png
"""

import argparse
import os
import sys
from pathlib import Path


def get_api_key(provided_key: str | None) -> str | None:
    """Get API key from argument first, then environment."""
    if provided_key:
        return provided_key
    return os.environ.get("GEMINI_API_KEY")


def main():
    parser = argparse.ArgumentParser(
        description="Generate images using Nano Banana Pro (Gemini 3 Pro Image)"
    )
    parser.add_argument(
        "--prompt", "-p",
        required=True,
        help="Image description/prompt"
    )
    parser.add_argument(
        "--filename", "-f",
        required=True,
        help="Output filename (e.g., sunset-mountains.png)"
    )
    parser.add_argument(
        "--input-image", "-i",
        action="append",
        dest="input_images",
        metavar="IMAGE",
        help="Input image path(s) for editing/composition. Can be specified multiple times (up to 14 images)."
    )
    parser.add_argument(
        "--resolution", "-r",
        choices=["1K", "2K", "4K"],
        default="1K",
        help="Output resolution: 1K (default), 2K, or 4K"
    )
    parser.add_argument(
        "--api-key", "-k",
        help="Gemini API key (overrides GEMINI_API_KEY env var)"
    )

    args = parser.parse_args()

    # Get API key
    api_key = get_api_key(args.api_key)
    if not api_key:
        print("Error: No API key provided.", file=sys.stderr)
        print("Please either:", file=sys.stderr)
        print("  1. Provide --api-key argument", file=sys.stderr)
        print("  2. Set GEMINI_API_KEY environment variable", file=sys.stderr)
        sys.exit(1)

    # Import here after checking API key to avoid slow import on error
    from google import genai
    from google.genai import types
    from PIL import Image as PILImage

    # Initialise client
    client = genai.Client(api_key=api_key)

    # Set up output path
    output_path = Path(args.filename)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    # Load input images if provided (up to 14 supported by Nano Banana Pro)
    input_images = []
    output_resolution = args.resolution
    if args.input_images:
        if len(args.input_images) > 14:
            print(f"Error: Too many input images ({len(args.input_images)}). Maximum is 14.", file=sys.stderr)
            sys.exit(1)

        max_input_dim = 0
        for img_path in args.input_images:
            try:
                with PILImage.open(img_path) as img:
                    copied = img.copy()
                    width, height = copied.size
                input_images.append(copied)
                print(f"Loaded input image: {img_path}")

                # Track largest dimension for auto-resolution
                max_input_dim = max(max_input_dim, width, height)
            except Exception as e:
                print(f"Error loading input image '{img_path}': {e}", file=sys.stderr)
                sys.exit(1)

        # Auto-detect resolution from largest input if not explicitly set
        if args.resolution == "1K" and max_input_dim > 0:  # Default value
            if max_input_dim >= 3000:
                output_resolution = "4K"
            elif max_input_dim >= 1500:
                output_resolution = "2K"
            else:
                output_resolution = "1K"
            print(f"Auto-detected resolution: {output_resolution} (from max input dimension {max_input_dim})")

    # Build contents (images first if editing, prompt only if generating)
    if input_images:
        contents = [*input_images, args.prompt]
        img_count = len(input_images)
        print(f"Processing {img_count} image{'s' if img_count > 1 else ''} with resolution {output_resolution}...")
    else:
        contents = args.prompt
        print(f"Generating image with resolution {output_resolution}...")

    try:
        response = client.models.generate_content(
            model="gemini-3-pro-image-preview",
            contents=contents,
            config=types.GenerateContentConfig(
                response_modalities=["TEXT", "IMAGE"],
                image_config=types.ImageConfig(
                    image_size=output_resolution
                )
            )
        )

        # Process response and convert to PNG
        image_saved = False
        for part in response.parts:
            if part.text is not None:
                print(f"Model response: {part.text}")
            elif part.inline_data is not None:
                # Convert inline data to PIL Image and save as PNG
                from io import BytesIO

                # inline_data.data is already bytes, not base64
                image_data = part.inline_data.data
                if isinstance(image_data, str):
                    # If it's a string, it might be base64
                    import base64
                    image_data = base64.b64decode(image_data)

                image = PILImage.open(BytesIO(image_data))

                # Ensure RGB mode for PNG (convert RGBA to RGB with white background if needed)
                if image.mode == 'RGBA':
                    rgb_image = PILImage.new('RGB', image.size, (255, 255, 255))
                    rgb_image.paste(image, mask=image.split()[3])
                    rgb_image.save(str(output_path), 'PNG')
                elif image.mode == 'RGB':
                    image.save(str(output_path), 'PNG')
                else:
                    image.convert('RGB').save(str(output_path), 'PNG')
                image_saved = True

        if image_saved:
            full_path = output_path.resolve()
            print(f"\nImage saved: {full_path}")
            # OpenClaw parses MEDIA tokens and will attach the file on supported providers.
            print(f"MEDIA: {full_path}")
        else:
            print("Error: No image was generated in the response.", file=sys.stderr)
            sys.exit(1)

    except Exception as e:
        print(f"Error generating image: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()

---
name: blogwatcher
description: Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI.
homepage: https://github.com/Hyaxia/blogwatcher
metadata:
  {
    "openclaw":
      {
        "emoji": "📰",
        "requires": { "bins": ["blogwatcher"] },
        "install":
          [
            {
              "id": "go",
              "kind": "go",
              "module": "github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest",
              "bins": ["blogwatcher"],
              "label": "Install blogwatcher (go)",
            },
          ],
      },
  }
---

# blogwatcher

Track blog and RSS/Atom feed updates with the `blogwatcher` CLI.

Install

- Go: `go install github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest`

Quick start

- `blogwatcher --help`

Common commands

- Add a blog: `blogwatcher add "My Blog" https://example.com`
- List blogs: `blogwatcher blogs`
- Scan for updates: `blogwatcher scan`
- List articles: `blogwatcher articles`
- Mark an article read: `blogwatcher read 1`
- Mark all articles read: `blogwatcher read-all`
- Remove a blog: `blogwatcher remove "My Blog"`

Example output

```
$ blogwatcher blogs
Tracked blogs (1):

  xkcd
    URL: https://xkcd.com
```

```
$ blogwatcher scan
Scanning 1 blog(s)...

  xkcd
    Source: RSS | Found: 4 | New: 4

Found 4 new article(s) total!
```

Notes

- Use `blogwatcher <command> --help` to discover flags and options.

---
name: acp-router
description: Route plain-language requests for Pi, Claude Code, Codex, OpenCode, Gemini CLI, or ACP harness work into either OpenClaw ACP runtime sessions or direct acpx-driven sessions ("telephone game" flow). For coding-agent thread requests, read this skill first, then use only `sessions_spawn` for thread creation.
user-invocable: false
---

# ACP Harness Router

When user intent is "run this in Pi/Claude Code/Codex/OpenCode/Gemini/Kimi (ACP harness)", do not use subagent runtime or PTY scraping. Route through ACP-aware flows.

## Intent detection

Trigger this skill when the user asks OpenClaw to:

- run something in Pi / Claude Code / Codex / OpenCode / Gemini
- continue existing harness work
- relay instructions to an external coding harness
- keep an external harness conversation in a thread-like conversation

Mandatory preflight for coding-agent thread requests:

- Before creating any thread for Pi/Claude/Codex/OpenCode/Gemini work, read this skill first in the same turn.
- After reading, follow `OpenClaw ACP runtime path` below; do not use `message(action="thread-create")` for ACP harness thread spawn.

## Mode selection

Choose one of these paths:

1. OpenClaw ACP runtime path (default): use `sessions_spawn` / ACP runtime tools.
2. Direct `acpx` path (telephone game): use `acpx` CLI through `exec` to drive the harness session directly.

Use direct `acpx` when one of these is true:

- user explicitly asks for direct `acpx` driving
- ACP runtime/plugin path is unavailable or unhealthy
- the task is "just relay prompts to harness" and no OpenClaw ACP lifecycle features are needed

Do not use:

- `subagents` runtime for harness control
- `/acp` command delegation as a requirement for the user
- PTY scraping of pi/claude/codex/opencode/gemini/kimi CLIs when `acpx` is available

## AgentId mapping

Use these defaults when user names a harness directly:

- "pi" -> `agentId: "pi"`
- "claude" or "claude code" -> `agentId: "claude"`
- "codex" -> `agentId: "codex"`
- "opencode" -> `agentId: "opencode"`
- "gemini" or "gemini cli" -> `agentId: "gemini"`
- "kimi" or "kimi cli" -> `agentId: "kimi"`

These defaults match current acpx built-in aliases.

If policy rejects the chosen id, report the policy error clearly and ask for the allowed ACP agent id.

## OpenClaw ACP runtime path

Required behavior:

1. For ACP harness thread spawn requests, read this skill first in the same turn before calling tools.
2. Use `sessions_spawn` with:
   - `runtime: "acp"`
   - `thread: true`
   - `mode: "session"` (unless user explicitly wants one-shot)
3. For ACP harness thread creation, do not use `message` with `action=thread-create`; `sessions_spawn` is the only thread-create path.
4. Put requested work in `task` so the ACP session gets it immediately.
5. Set `agentId` explicitly unless ACP default agent is known.
6. Do not ask user to run slash commands or CLI when this path works directly.

Example:

User: "spawn a test codex session in thread and tell it to say hi"

Call:

```json
{
  "task": "Say hi.",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}
```

## Thread spawn recovery policy

When the user asks to start a coding harness in a thread (for example "start a codex/claude/pi/kimi thread"), treat that as an ACP runtime request and try to satisfy it end-to-end.

Required behavior when ACP backend is unavailable:

1. Do not immediately ask the user to pick an alternate path.
2. First attempt automatic local repair:
   - ensure plugin-local pinned acpx is installed in `extensions/acpx`
   - verify `${ACPX_CMD} --version`
3. After reinstall/repair, restart the gateway and explicitly offer to run that restart for the user.
4. Retry ACP thread spawn once after repair.
5. Only if repair+retry fails, report the concrete error and then offer fallback options.

When offering fallback, keep ACP first:

- Option 1: retry ACP spawn after showing exact failing step
- Option 2: direct acpx telephone-game flow

Do not default to subagent runtime for these requests.

## ACPX install and version policy (direct acpx path)

For this repo, direct `acpx` calls must follow the same pinned policy as the `@openclaw/acpx` extension.

1. Prefer plugin-local binary, not global PATH:
   - `./extensions/acpx/node_modules/.bin/acpx`
2. Resolve pinned version from extension dependency:
   - `node -e "console.log(require('./extensions/acpx/package.json').dependencies.acpx)"`
3. If binary is missing or version mismatched, install plugin-local pinned version:
   - `cd extensions/acpx && npm install --omit=dev --no-save acpx@<pinnedVersion>`
4. Verify before use:
   - `./extensions/acpx/node_modules/.bin/acpx --version`
5. If install/repair changed ACPX artifacts, restart the gateway and offer to run the restart.
6. Do not run `npm install -g acpx` unless the user explicitly asks for global install.

Set and reuse:

```bash
ACPX_CMD="./extensions/acpx/node_modules/.bin/acpx"
```

## Direct acpx path ("telephone game")

Use this path to drive harness sessions without `/acp` or subagent runtime.

### Rules

1. Use `exec` commands that call `${ACPX_CMD}`.
2. Reuse a stable session name per conversation so follow-up prompts stay in the same harness context.
3. Prefer `--format quiet` for clean assistant text to relay back to user.
4. Use `exec` (one-shot) only when the user wants one-shot behavior.
5. Keep working directory explicit (`--cwd`) when task scope depends on repo context.

### Session naming

Use a deterministic name, for example:

- `oc-<harness>-<conversationId>`

Where `conversationId` is thread id when available, otherwise channel/conversation id.

### Command templates

Persistent session (create if missing, then prompt):

```bash
${ACPX_CMD} codex sessions show oc-codex-<conversationId> \
  || ${ACPX_CMD} codex sessions new --name oc-codex-<conversationId>

${ACPX_CMD} codex -s oc-codex-<conversationId> --cwd <workspacePath> --format quiet "<prompt>"
```

One-shot:

```bash
${ACPX_CMD} codex exec --cwd <workspacePath> --format quiet "<prompt>"
```

Cancel in-flight turn:

```bash
${ACPX_CMD} codex cancel -s oc-codex-<conversationId>
```

Close session:

```bash
${ACPX_CMD} codex sessions close oc-codex-<conversationId>
```

### Harness aliases in acpx

- `pi`
- `claude`
- `codex`
- `opencode`
- `gemini`
- `kimi`

### Built-in adapter commands in acpx

Defaults are:

- `pi -> npx pi-acp`
- `claude -> npx -y @zed-industries/claude-agent-acp`
- `codex -> npx @zed-industries/codex-acp`
- `opencode -> npx -y opencode-ai acp`
- `gemini -> gemini`
- `kimi -> kimi acp`

If `~/.acpx/config.json` overrides `agents`, those overrides replace defaults.

### Failure handling

- `acpx: command not found`:
  - for thread-spawn ACP requests, install plugin-local pinned acpx in `extensions/acpx` immediately
  - restart gateway after install and offer to run the restart automatically
  - then retry once
  - do not ask for install permission first unless policy explicitly requires it
  - do not install global `acpx` unless explicitly requested
- adapter command missing (for example `claude-agent-acp` not found):
  - for thread-spawn ACP requests, first restore built-in defaults by removing broken `~/.acpx/config.json` agent overrides
  - then retry once before offering fallback
  - if user wants binary-based overrides, install exactly the configured adapter binary
- `NO_SESSION`: run `${ACPX_CMD} <agent> sessions new --name <sessionName>` then retry prompt.
- queue busy: either wait for completion (default) or use `--no-wait` when async behavior is explicitly desired.

### Output relay

When relaying to user, return the final assistant text output from `acpx` command result. Avoid relaying raw local tool noise unless user asked for verbose logs.

Escolhi 3 exemplos super expressivos:

acp-router

Esse skill é um roteador para o “OpenClaw” que intercepta pedidos do tipo “rode isso no Claude Code / Codex / Gemini / Pi / OpenCode / Kimi” e os encaminha para sessões ACP (Agent Communication Protocol) em vez de usar scraping de terminal ou subagentes genéricos.

Em resumo, ele faz três coisas:

1. Detecta a intenção de usar um coding agent externo (Pi, Claude Code, Codex, etc.) e mapeia o nome para um agentId padronizado.
2. Escolhe o caminho de execução: ou via runtime ACP nativo do OpenClaw (sessions_spawn), ou via CLI acpx diretamente (o “telephone game”, onde o OpenClaw repassa prompts para o harness e devolve as respostas).
3. Gerencia ciclo de vida: criação de sessões persistentes com nomes determinísticos, recuperação automática quando o backend ACP falha (reinstala o acpx local, reinicia o gateway, tenta de novo), e fallback ordenado só se tudo falhar.

Basicamente é a cola que permite ao OpenClaw orquestrar múltiplos agentes de código externos de forma padronizada, sem que o usuário precise lidar com CLI ou comandos manuais.

Se não faz ideia do que seja ACP, estamos falando de Agent Communication Protocol saiba mais.

blogwatcher

Essa skill é um wrapper para o CLI blogwatcher — uma ferramenta em Go que monitora blogs e feeds RSS/Atom.

Ela permite ao agente adicionar blogs para acompanhar, escanear por novos posts, listar artigos encontrados e marcá-los como lidos, tudo via linha de comando. É basicamente um leitor de RSS minimalista operado pelo agente, útil para ficar de olho em atualizações de blogs técnicos ou qualquer fonte com feed.

nano-banana-pro

Essa skill é um wrapper para geração e edição de imagens usando o Gemini 3 Pro (codinome interno “Nano Banana Pro”).

Ela expõe um script Python (rodado via uv) que aceita prompts de texto para gerar imagens do zero, editar uma imagem existente com instruções, ou compor múltiplas imagens (até 14) numa cena só. Suporta resoluções de 1K a 4K e usa a API key do Gemini. O agente só precisa informar o prompt e o nome do arquivo de saída.

A aparente simplicidade dos exemplos esconde o ponto central. O modelo já sabe o que é uma CLI, sabe interagir com um MCP, sabe chamar tools, sabe executar projetos .NET, Python, Node. Tudo que a skill precisa dizer é como, diante da vastidão de conhecimento, executar estritamente aquela operação para cumprir a tarefa. Skills são mecanismos de foco, de atenção, de redução de escopo.

É aqui que a mágica acontece

Embora o modelo seja treinado com código bom, código médio, mas potencialmente majoritariamente com código ruim, você consegue entregar, via skills tudo que o modelo precisa para realizar, no detalhe, com perfeição:

• Da forma como você deseja
• Com o nível de detalhe que você precisa.
• Independente do que você esteja fazendo

Skill não é sinônimo de arquivo markdown

A maioria dos exemplos que circulam por aí são arquivos .md com instruções em linguagem natural. É o formato mais comum, mas não é o único.

Uma skill é, no fundo, expertise codificada sobre como executar uma tarefa bem. Essa expertise pode viver em vários formatos:

• um arquivo markdown com instruções
• um script Python que executa a tarefa diretamente
• um JSON schema
• um conjunto de exemplos de input/output
• ou uma combinação de tudo isso.

Markdown funciona bem quando a tarefa envolve ambiguidade e julgamento, quando você precisa que o modelo raciocine sobre o que fazer. Scripts diretos funcionam melhor quando você precisa de execução determinística, sem variação, toda vez. Na prática, o design mais robusto é híbrido: um script que faz o trabalho pesado, com um markdown que ensina o agente quando invocar e como interpretar os resultados.

Como eu descobri isso?

Embora eu só tenha de fato entrado de cabeça para usar IA agora em FEV/2026, em outubro 16/OUT com o lançamento das Claude Skills, agora Agent Skills, ficou claro que era possível assumir o controle, com precisão, do resultado.

De fato eu não tenho muito interesse em que a IA faça o que eu não sei fazer,
eu quero que ela faça o que eu sei fazer,
de forma mais rápida e mais eficiente,
de tal forma que eu possa corrigir, mas nunca perder o controle.

Controle é a palavra-chave que explica Skills.

Sempre foi claro para mim, que por melhor que fossem os prompts, a codebase não era suficiente para expressar o padrão ou as intenções, em especial quando se trata de microsserviço, com um nível de automação e infraestrutura elevado.

Quando se alimenta débitos técnicos, pior ainda.

E é essa minha realidade atual.

A IA é o braço para saná-los. Mas como ensiná-la a fazer certo? Ou ignorando certo ou errado, como fazer da forma exata e precisa que eu quero?

Agent Skills parecia a resposta que queria que caísse dos céus.

E de fato era!

O mercado escolheu falar e criar skills tão rasas quanto o próprio conhecimento

O título desse post é provocativo intencionalmente. A maior parte do que vemos no youtube, a maior parte das skills da comunidade, dos repositórios, são skills absolutamente superficiais.

Ao invés de codificar expertise concreta, elas dizem “Faça da melhor forma seguindo os melhores padrões”. Nesse momento, você delegou ao modelo a descoberta de qual padrão se aplica, e o resultado vai refletir a média do treinamento, não a sua intenção. A skill deixou de ser uma receita e virou um pedido genérico ao chef. O modelo não ganhou expertise nenhuma. Ganhou liberdade para improvisar, que é exatamente o oposto do que você queria.

E o que é “boa prática”?!

Nem todo mundo foi por essa linha, a skill nano-banana-pro, do exemplo acima, por exmemplo, aprofunda no detalhe, trazendo inclusive um script python para ser chamado. Isso é controle!

Não é preciso detalhar tudo, mas é importante saber que é possível, que tem como. O óbvio não precisa ser detalhado, mas toda vez que você quer assumir o controle, detalhar se torna fundamental.

E tem um problema que vai além da superficialidade do conteúdo: o triggering. Uma skill pode ser tecnicamente excelente, mas se a description for vaga, o agente simplesmente não vai invocá-la. Ele não vai reconhecer que aquela skill se aplica ao contexto atual. A description de uma skill não é um resumo para humanos — é uma instrução de matching para o modelo. Precisa ser específica o suficiente para que o agente identifique, sem ambiguidade, quando usá-la. Esse é mais um ponto que o conteúdo raso não ensina.

Exemplo – API Gateway

Vou detalhar até que ponto conseguimos entregar detalhes para a IA.

Conexto

Meu primeiro contato real, e intencional com os Code Agents se deu depois de meses de projeto, há praticamente 2 meses de entrar em produção.

A demanda por automação

O projeto tem muita coisa que foge ao padrão dos projetos que encontramos nas empresas daqui do Brasil e em especial no github.

Por acaso, por se tratar de um projeto cloud native, nos moldes do que eu faço e falo há anos, endereça também soluções para as críticas que faço aqui no gago.io, motivo que fez fazer parte do projeto.

Entre outras coisas, nesse tipo de projeto (criação de plataforma), a aplicação precisa tocar na infraestrutura para reconfigurar a infraestrutura em virtude de operações de negócio.

Porque não é concebível ou aceitável que em pleno 2026 quando um cliente é cadastrado na plataforma e cria uma API Key, um humano precise apertar um botão para aplicar essa api key no api gateway.

Imagina se cada vez que você cria uma API Key na Anthropic, OpenAI, Google, Microsoft, um humano precisasse replicar isso no gateway via algum tipo de botão ou script.

Na visão de produto, é inaceitável.

• A criação da API KEY
• A sincronização com o API SIX
• A criação do container do cliente

todas essas tarefas devem acontecer em multiplos datacenters, ao vivo, instantaneamente, e automaticamente, sem humanos como gargalo.

Apache APISIX

Como API Gateway, dessa vez saí do clássico Kong/Konga e optei pelo Apache APISIX e foi a melhor mudança que fiz nos últimos anos.

• Apache APISIX não possui plugins pagos, todos são gratuitos, diferente do Kong,
• É mantido sob a guarda da Apache Software Foundation

Esses foram os principais elementos que me fizeram dar uma chance, ainda no Academia Pay, e deu muito certo!

Como esse foi meu primeiro projeto depois do Academia Pay, fez muito sentido adotá-lo aqui.

As operações básicas de subida da infra acontecem via curl configurados como job no kubernetes. Já na máquina local do dev, um container dos vários do docker compose faz a tarefa.

Mas uma perna precisa ser dinâmica: A criação das API Keys. Essa tarefa não é um curl que resolve é a aplicação então resolvi estruturar isso de forma correta e daí nasce:

• Interface para o Refit
• DTO’s e mais DTO’s…

Bom, está claro que estamos diante de algo customizado, algo feito sob demanda para um problema específico de um projeto peculiar de plataforma.

Algo que não está no treinamento do modelo. Não exatamente como fizemos aqui.

Criando Agent Skills

Uma vez que você tem uma arquitetura funcional, pedir para o claude code construir uma skill é muito fácil. Eu criei um prompt com as documentações de Skills de todos os principais providers de agentes.

• https://agentskills.io/home
• https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview
• https://developers.openai.com/codex/skills/
• https://manus.im/pt-br/features/agent-skills
• https://learn.microsoft.com/en-us/agent-framework/agents/skills
• https://code.visualstudio.com/docs/copilot/customization/agent-skills
• https://opencode.ai/docs/skills/
• https://cursor.com/pt-BR/docs/skills

(na época a lista era bem menor, 5 links, sendo 2 da agentskills.io e 2 da platform.claude.com)

Eu fiz o trabalho de ir ao google, achar os principais links que explicam Agent Skills, e pedi para, com base na codebase e na documentação, criar skills para essa integração e esse foi o resultado.

---
name: apisix-gateway
description: Configure and manage ApiSix gateway for API authentication, rate limiting, and consumer management. Use when working with API keys, rate limits, or gateway configuration.
context: fork
agent: Explore
---

## Overview

ApiSix is the API gateway that sits in front of xxxxxxxxxx, handling authentication via API keys, rate limiting, and request transformation. Consumers (representing API keys) are automatically synchronized from xxxxxxxxxx's database to ApiSix via the Event Driven Architecture.

## When to Use This Skill

Use this skill when:
- Configuring new API routes in ApiSix
- Troubleshooting 401/429 errors
- Understanding API key authentication flow
- Modifying rate limiting behavior
- Adding new plugins to routes
- Managing consumers manually

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ API Request with X-API-Key header                                           │
└─────────────────────────────────────────────────────────────────────────────┘
                                     ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ ApiSix Gateway (Port 7777)                                                  │
│                                                                             │
│ ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐               │
│ │   key-auth      │→ │   limit-count   │→ │ attach-consumer │               │
│ │   plugin        │  │   plugin        │  │ -label plugin   │               │
│ └─────────────────┘  └─────────────────┘  └─────────────────┘               │
│                                                                             │
│ Validates API key    Checks rate limit   Injects consumer                   │
│ Loads consumer       per consumer        labels as headers                  │
└─────────────────────────────────────────────────────────────────────────────┘
                                     ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│ xxxxxxxxxx API (Port 8080)                                                   │
│                                                                             │
│ Receives headers:                                                           │
│ - X-Consumer-Account-Id                                                     │
│ - X-Consumer-Organization-Id                                                │
│ - X-Consumer-Role                                                           │
│ - X-Consumer-Api-Key-Id                                                     │
│ - X-Request-Id                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Key Configuration Files

```
compose/apisix/
├── apisix_conf/
│   └── config.yaml          # Base ApiSix configuration
├── apisix-configurer/
│   └── api.sh               # Route and plugin setup scripts
└── docker-compose.yaml      # Local development
```

## Consumer Synchronization Flow

Consumers are automatically managed via Event Driven Architecture:

```
ApiKey Created/Updated/Deleted in xxxxxxxxxx
              ↓
Event: apikey.{created|changed|deleted}
              ↓
Queue: events.apikey.{event}.flow.work
              ↓
Command: sync-api-key-on-gateway
              ↓
Queue: commands.sync-api-key-on-gateway.work
              ↓
Worker calls IApiSix.CreateConsumerAsync() / DeleteConsumerAsync()
              ↓
ApiSix Admin API: PUT /apisix/admin/consumers/{username}
```

## Consumer Structure

### Labels (Metadata)

```csharp
public class Labels
{
    public string ApiKeyId { get; set; }
    public string AccountId { get; set; }
    public string AccountName { get; set; }
    public string OrganizationId { get; set; }
    public string OrganizationName { get; set; }
    public string Role { get; set; }      // "Account", "Organization", "System"
    public string Region { get; set; }    // "default"
}
```

### Plugins

```csharp
public class Plugins
{
    [JsonPropertyName("key-auth")]
    public KeyAuthConsumerPlugin KeyAuth { get; set; }

    [JsonPropertyName("limit-count")]
    public LimitCountConsumerPlugin LimitCount { get; set; }
}

public class KeyAuthConsumerPlugin
{
    [JsonPropertyName("key")]
    public string ApiKey { get; set; }  // The raw API key value
}

public class LimitCountConsumerPlugin
{
    [JsonPropertyName("count")]
    public int Count { get; set; }       // Requests allowed

    [JsonPropertyName("time_window")]
    public int TimeWindow { get; set; }  // Time window in seconds

    [JsonPropertyName("rejected_code")]
    public int RejectedCode { get; set; } = 429;

    [JsonPropertyName("key")]
    public string Key { get; set; } = "remote_addr";
}
```

## API Key Format

xxxxxxxxxx API keys follow this format:

```
{sys|org|acc}_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Prefix: sys_ – System-level API Key
        org_ – Organization-level API Key
        acc_ – Account-level API Key
Key:    32 random alphanumeric characters
Total:  36 characters
```

### Create/Update Consumer

```csharp
app.MapQueue("commands.sync-api-key-on-gateway.work", async (
    [FromBody] GenericCommand currentCommand,
    [FromServices] IApiKeyRepository apiKeyRepository,
    [FromServices] IApiSix apiSix,
    [FromServices] ILogger<Program> logger) =>
{
    var apiKeyId = currentCommand.GetMetadata<Guid>(nameof(ApiKey.ApiKeyId));
    var eventName = currentCommand.GetMetadata<string>("EventName");

    if (eventName == "deleted")
    {
        // Delete consumer
        await apiSix.DeleteConsumerAsync(apiKeyId.ToString("N"));
        logger.LogInformation("Consumer deleted: {ApiKeyId}", apiKeyId);
        return AmqpResults.Ack();
    }

    // Load ApiKey with related entities
    var apiKey = await apiKeyRepository.GetOneAsync(apiKeyId);

    if (apiKey == null)
    {
        logger.LogWarning("ApiKey not found: {ApiKeyId}", apiKeyId);
        return AmqpResults.Nack(false);  // Nack requeue=false to avoid reprocessing
    }

    // Create/Update consumer
    await apiSix.CreateConsumerAsync(new ApiSixCreateConsumerRequest()
    {
        Username = apiKey.ApiKeyId.ToString("N"),
        Labels = new Labels(){ ... },
        Plugins = new Plugins { ... }
    });

    logger.LogInformation(
        "Consumer synced: {ApiKeyId}, Role: {Role}, Limit: {Limit}/{Seconds}s",
        apiKeyId,
        apiKey.Account != null ? "Account" : "Organization",
        apiKey.ResourcePlan.Limit,
        apiKey.ResourcePlan.Seconds);

    return AmqpResults.Ack();
})
.WithSafeRunnerConnection("rabbitmq_events")
.WithDispatchConcurrency(1)
.WithPrefetch(1);
```

## IApiSix Interface

**File:** `Infrastructure/ApiSix/IApiSix.cs`

```csharp
public interface IApiSix
{
    [Put("/apisix/admin/consumers/{username}")]
    Task<ApiSixResponse> CreateConsumerAsync(
        [AliasAs("username")] string username,
        [Body] ApiSixCreateConsumerRequest request);

    [Delete("/apisix/admin/consumers/{username}")]
    Task<ApiSixResponse> DeleteConsumerAsync(
        [AliasAs("username")] string username);

    [Get("/apisix/admin/consumers/{username}")]
    Task<ApiSixConsumerResponse> GetConsumerAsync(
        [AliasAs("username")] string username);

    [Get("/apisix/admin/consumers")]
    Task<ApiSixConsumersListResponse> ListConsumersAsync();
}
```

## Route Configuration

**File:** `compose/apisix/apisix-configurer/api.sh`

```bash
#!/bin/bash

ADMIN_KEY="${APISIX_ADMIN_KEY:-xxxxxxxxxxxxxxxxxxxxxxxxxx}"
APISIX_HOST="${APISIX_HOST:-http://apisix:9180}"

# Wait for ApiSix to be ready
until curl -s "${APISIX_HOST}/apisix/status" > /dev/null; do
    echo "Waiting for ApiSix..."
    sleep 2
done

# Create main API route
curl -X PUT "${APISIX_HOST}/apisix/admin/routes/xxxxxxxxxx-api" \
    -H "X-API-KEY: ${ADMIN_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
    "uri": "/api/*",
    "name": "xxxxxxxxxx API",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "xxxxxxxxxx-api:8080": 1
        },
        "timeout": {
            "connect": 5,
            "send": 60,
            "read": 60
        }
    },
    "plugins": {
        "key-auth": {
            "header": "X-API-Key",
            "hide_credentials": true
        },
        "request-id": {
            "header_name": "X-Request-Id",
            "include_in_response": true,
            "algorithm": "uuid"
        },
        "limit-req": {
            "rate": 1000,
            "burst": 500,
            "rejected_code": 429,
            "key_type": "consumer_name"
        },
        "proxy-rewrite": {
            "headers": {
                "set": {
                    "X-Forwarded-Host": "$host"
                }
            }
        },
        "attach-consumer-label": {
            "headers": [
                "X-Consumer-Account-Id:accountId",
                "X-Consumer-Account-Name:accountName",
                "X-Consumer-Organization-Id:organizationId",
                "X-Consumer-Organization-Name:organizationName",
                "X-Consumer-Role:role",
                "X-Consumer-Api-Key-Id:apiKeyId",
                "X-Consumer-Region:region"
            ]
        }
    }
}'

echo "Route configured successfully"
```

## Base Configuration

**File:** `compose/apisix/apisix_conf/config.yaml`

```yaml
apisix:
  node_listen: 7777
  enable_admin: true
  admin_key:
    - name: admin
      key: xxxxxxxxxxxxxxxxxxxxxxxxxx
      role: admin

etcd:
  host:
    - "http://etcd:2379"
  prefix: "/apisix"
  timeout: 30

plugins:
  - key-auth
  - limit-count
  - limit-req
  - request-id
  - proxy-rewrite
  - attach-consumer-label

plugin_attr:
  log-rotate:
    interval: 3600
    max_kept: 168
```

## Debugging ApiSix
### Check Consumer Exists

```bash
# List all consumers
curl -s http://apisix:9180/apisix/admin/consumers \
    -H "X-API-KEY: $ADMIN_KEY" | jq '.list[] | {username, labels}'

# Get specific consumer
curl -s http://apisix:9180/apisix/admin/consumers/{apiKeyId} \
    -H "X-API-KEY: $ADMIN_KEY" | jq
```

### Test Authentication

```bash
# Test valid API key
curl -v https://api.xxxxxxxxxx.io/api/health \
    -H "X-API-Key: mfy_xxxxxxxxxxxxx"

# Check response headers
# - X-Request-Id: generated
# - X-RateLimit-Limit: from consumer
# - X-RateLimit-Remaining: requests left
```

### Check Rate Limit Status

```bash
# Multiple requests to trigger rate limit info
for i in {1..5}; do
    curl -s -I https://api.xxxxxxxxxx.io/api/health \
        -H "X-API-Key: mfy_xxxxxxxxxxxxx" | grep -i ratelimit
done
```

### View ApiSix Logs

```bash
# Docker logs
docker logs apisix --tail 100 -f

# Access log
docker exec apisix tail -f /usr/local/apisix/logs/access.log

# Error log
docker exec apisix tail -f /usr/local/apisix/logs/error.log
```

## Common Issues

### 401 Unauthorized

**Causes:**
- API key not found in header
- Consumer not synchronized to ApiSix
- Invalid API key format

**Debug:**
```bash
# Check header is being sent
curl -v ... -H "X-API-Key: mfy_xxx"

# Check consumer exists
curl http://apisix:9180/apisix/admin/consumers -H "X-API-KEY: $ADMIN_KEY"

# Check event processing
rabbitmqadmin get queue=commands.sync-api-key-on-gateway.work count=10
```

### 429 Too Many Requests

**Causes:**
- Rate limit exceeded
- ResourcePlan has low limits
- Multiple clients sharing same API key

**Debug:**
```bash
# Check rate limit headers
curl -I ... | grep RateLimit

# Check consumer's limit-count config
curl http://apisix:9180/apisix/admin/consumers/{id} | jq '.plugins.limit-count'

# Check ResourcePlan in database
SELECT * FROM resource_plans WHERE resource_plan_id = '...';
```

### Missing X-Consumer-* Headers

**Causes:**
- Consumer labels not set
- attach-consumer-label plugin not configured
- Plugin mapping incorrect

**Debug:**
```bash
# Check consumer labels
curl http://apisix:9180/apisix/admin/consumers/{id} | jq '.labels'

# Check route plugins
curl http://apisix:9180/apisix/admin/routes | jq '.list[] | .plugins["attach-consumer-label"]'
```

## Adding New Routes

### Webhook Route (No Auth)

```bash
curl -X PUT "${APISIX_HOST}/apisix/admin/routes/webhooks" \
    -H "X-API-KEY: ${ADMIN_KEY}" \
    -d '{
    "uri": "/webhooks/*",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "xxxxxxxxxx-api:8080": 1
        }
    },
    "plugins": {
        "request-id": {}
    }
}'
```

### Health Check Route (No Auth)

```bash
curl -X PUT "${APISIX_HOST}/apisix/admin/routes/health" \
    -H "X-API-KEY: ${ADMIN_KEY}" \
    -d '{
    "uri": "/health/*",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "xxxxxxxxxx-api:8080": 1
        }
    },
    "plugins": {}
}'
```

## ResourcePlan Examples

| Plan         | Limit     | Seconds | Description           |
|--------------|-----------|---------|-----------------------|
| Free         |       100 |      60 |           100 req/min |
| Starter      |       500 |      60 |           500 req/min |
| Pro          |      2000 |      60 |          2000 req/min |
| Enterprise   |     10000 |      60 |         10000 req/min |
| Unlimited    |   1000000 |       1 | Effectively unlimited |

## Related Skills

- `event-driven-administration` - How consumers are synchronized
- `infrastructure-architecture` - Full infrastructure flow
- `add-api-endpoint` - Creating protected endpoints
- `debug-issue` - General debugging

## Related Documentation

- `message-flow/references/INFRASTRUCTURE_LAYER.md` - Infrastructure details
- `compose/apisix/` - Configuration files
- Apache APISIX Documentation: https://apisix.apache.org/docs/

Essse é o nível de especificidade que é possível alcançar.

Coisas importantes

Skill e MCP resolvem problemas diferentes

Se seu agente já se conecta a fontes de dados via MCP, a pergunta natural é: por que preciso de skills?

MCP é infraestrutura. Ele expõe dados e serviços, acesso a bancos, APIs, logs, sistemas internos. MCP é a cozinha profissional: fornece os ingredientes, os utensílios, os equipamentos.

Skills são orquestração. Elas definem como o agente deve usar os dados que o MCP entrega para produzir algo de valor. Skills são as receitas que dizem o que fazer com os ingredientes.

Na prática, o design que funciona é: acesso a dados, APIs e retrieval como tools (ou capacidades MCP); lógica de decisão e workflows como skills. A skill do APISIX no exemplo acima é exatamente isso: ela não acessa o APISIX diretamente, ela ensina o agente a orquestrar chamadas Refit, interpretar o fluxo de filas e compor consumers com a estrutura correta.

Eu não criei essa skill sozinho

Essa skill foi criada usando o próprio claude code.

Eu pedi para que analisasse a codebase, enviei links quie explicavam o que eram Agent Skills e qual formato desejado e pronto.

Detalhes específicos dessa arquitetura

Muitos pontos foram respeitados e detalhados.

• Refit
• Escolha dos plugins
• Escolha da estratégia de configuração.
• Ausência de try/catchs
• Uso do Oragon.RabbitMQ
• Entendimento do fluxo completo de filas (uma cadeia de 3 passos)

O fato de que um modelo de linguagem é capaz de olhar minha codebase e produzir essa explicação, já é tãoi admirável quanto assustador.

Considerar que esse arquivo é como um cache, uma memória, que evita a descoberta, e que será usado e respeitado para novas operações, é ainda mais aterrorisante quanto empolgante.

Claro, escolhi o apisix para esse post pois é um assunto limpo do viés da arquitetura adotada no projeto. É um exemplo pouco opinativo.

Quase todo projeto, dos do tipo que eu pego, e da maioria avassaladora dos leitores do gago.io são projetos que demandam API Gateways, sejam eles internos, dento da empresa, entre aplicações, ou externo, para o acesso púiblico, portanto esse assunto é parte do dia-a-dia.

Ao todo foram 31 skills, algumas inclusive com resource, todos construídos com ajuda do Claude Code para serem usados pelo Claude Code com base em fragmentos da codebase.

O poder que as skills entregam para o agente são ilimitados. Permitindo inclusive o direcionamento das decisões.

ou especificações do que são consideradas boas práticas no seu projeto:

esses 2 prints são prints da skill do Oragon.RabbitMQ no projeto. Se quiser ver mais exemplos, como o do Oragon.RabbitMQ, comenta aqui.

De coração espero que seu entendimento sobre agent skills tenha evoluído.

Me conte, mudou sua percepção sobre Agent Skills?

Um PedidoCriado disparado por uma rotina de correção. Um PagamentoConfirmado emitido por um job de reprocessamento. Um UsuarioCadastrado lançado por uma migração de base legada. O fato não aconteceu, mas o evento foi emitido assim mesmo — porque “já tem tudo plugado”.

Essa é a confusão mais destrutiva em event-driven architecture. Não é sobre nomenclatura. É sobre semântica. E quando a semântica quebra, o sistema inteiro passa a operar sobre premissas falsas.

Eventos e Comandos se parecem, mas representam coisas opostas

Um evento e um comando:

• podem ter o mesmo payload
• podem trafegar pela mesma infraestrutura
• podem até ter nomes parecidos

Mas a intenção que cada um carrega é fundamentalmente diferente.

Um evento é a notificação de um fato. Algo aconteceu. PedidoCriado significa que um pedido foi criado. Um passado consumado, irreversível.

O produtor do evento

• não sabe quem consome
• não espera uma reação específica
• não tem responsabilidade sobre o que acontece depois

Ele apenas registra que um fato ocorreu.

Um comando é um pedido de ação. Algo precisa acontecer. SepararEstoque significa que alguém está solicitando ao serviço de estoque que execute uma operação. O emissor sabe para quem está enviando, espera uma execução, e assume responsabilidade pela intenção.

O evento diz “isso aconteceu”. O comando diz “faça isso”.

Essa distinção parece óbvia quando escrita assim. Na prática, a infraestrutura conspira contra ela. O RabbitMQ, o Kafka, o SNS, todos tratam eventos e comandos como mensagens. A ferramenta nivela o que a arquitetura deveria separar. E quando tudo é “mensagem”, a distinção semântica se perde no vocabulário do dia a dia do time.

O handler de evento é o adaptador que absorve acoplamento

Entre o evento e o comando existe uma peça que raramente recebe a atenção que merece: o handler de evento.

O handler é quem traduz fato em intenção.

Ele recebe PedidoCriado e emite:

• SepararEstoque
• NotificarCliente
• GerarFatura

Cada handler consome o evento e produz o comando específico para o serviço que precisa agir.

Essa tradução não é um detalhe de implementação. É o mecanismo central que permite a EDA funcionar sem criar um emaranhado de dependências.

Sem o handler como adaptador, você tem duas alternativas ruins.

A primeira: o serviço que cria o pedido conhece e invoca diretamente todos os serviços que precisam reagir: estoque, notificação, faturamento. A pressão cognitiva sobre esse serviço cresce a cada novo consumidor.

A segunda: os serviços consumidores interpretam o evento diretamente como instrução de ação, acoplando sua lógica interna à estrutura de um evento que pertence a outro bounded context.

O handler elimina os dois problemas.

• O produtor continua ignorando quem consome.
• O consumidor recebe um comando limpo, com a interface que ele mesmo definiu.
• O handler é a fronteira onde o acoplamento entre contextos é absorvido e isolado.

Cada seta entre o handler e o serviço destino é um comando.

Cada comando

• tem contrato próprio
• versionamento próprio
• e pode ser invocado de qualquer origem

não apenas de um handler de evento.

Onde o reaproveitamento é legítimo e onde ele quebra?

Essa arquitetura tem três pontos com características de reaproveitamento completamente diferentes. Confundir esses três níveis é a origem da maioria dos problemas.

No consumo do evento, o reaproveitamento é o design.

Um único PedidoCriado pode ter dez handlers diferentes. Cada handler traduz o mesmo fato em um comando diferente para um serviço diferente.

Adicionar um novo comportamento ao sistema significa adicionar um novo handler:

• sem alterar o produtor
• sem alterar os handlers existentes

Open/closed principle aplicado na arquitetura, não apenas no código.

Na emissão do evento, o reaproveitamento é uma mentira.

O evento está amarrado ao fato que o originou. PedidoCriado só pode ser emitido quando um pedido é efetivamente criado.

Se você precisa disparar separação de estoque por outro motivo como:

• uma correção manual
• um reprocessamento
• uma migração

emitir PedidoCriado é mentir para o sistema. O pedido não foi criado. Todos os handlers vão reagir como se tivesse sido. O cliente vai receber uma notificação de pedido que ele não fez. O faturamento vai gerar um documento fiscal duplicado. A semântica contamina todo o fluxo downstream.

Nos comandos, o reaproveitamento é monumental.

SepararEstoque pode ser invocado pelo handler de PedidoCriado.

• Pode ser invocado por uma API de correção manual.
• Pode ser invocado por um job de reprocessamento.
• Pode ser invocado por um teste automatizado.

O comando não carrega contexto de origem, ele expressa uma capacidade do serviço. E capacidades são, por definição, reutilizáveis.

Quando alguém reclama que “precisou emitir o evento de novo porque era a única forma de disparar o fluxo”, o problema não é a arquitetura, o problema é que os comandos não foram desenhados como unidades independentes. O time construiu a integração inteira sobre eventos e não expôs os comandos como pontos de entrada autônomos.

O que acontece quando você emite eventos que não representam fatos?

Na teoria, a confusão entre evento e comando é um problema de modelagem. Na prática, as consequências são operacionais e caras.

Rastreabilidade falsa. Se PedidoCriado é emitido tanto pela criação real de um pedido quanto por uma rotina de correção, o log do sistema registra dois eventos semanticamente idênticos que representam situações completamente diferentes. Qualquer análise, auditoria ou debugging precisa de contexto externo para distinguir qual é qual. A observabilidade perde valor.

Efeitos colaterais incontroláveis. Cada handler que reage ao evento vai executar. Todos eles. Se você emitiu PedidoCriado só porque precisava do handler de estoque, vai ter que lidar com a notificação indevida, a fatura duplicada, e qualquer outro handler que o time tenha plugado desde a última vez que alguém olhou o fluxo completo. A quantidade de handlers cresce ao longo do tempo, e cada novo handler é um efeito colateral potencial para quem emite o evento fora de contexto.

Modelo mental corrompido. Quando o time percebe que eventos são emitidos sem que o fato correspondente tenha acontecido, a confiança no modelo se deteriora. Desenvolvedores começam a adicionar flags, campos de controle, condicionais dentro dos handlers para distinguir “evento real” de “evento forjado”. A complexidade acidental cresce até que ninguém confia na semântica de nenhum evento.

// Antipattern: forjando um evento para reaproveitar a cadeia
var eventoForjado = new PedidoCriado
{
    PedidoId = pedidoExistente.Id,
    // Campos preenchidos artificialmente
    // para disparar separação de estoque
};

await _bus.Publish(eventoForjado); 
// Todos os handlers vão reagir — inclusive os indesejados

// Correto: invocar o comando diretamente
var comando = new SepararEstoque
{
    PedidoId = pedidoExistente.Id,
    Itens = pedidoExistente.Itens,
    Origem = OrigemSeparacao.CorrecaoManual
};

await _bus.Send(comando); 
// Apenas o serviço de estoque reage

A diferença entre os dois trechos não é estilística. No primeiro, você acionou uma cadeia inteira de efeitos colaterais sem intenção. No segundo, você expressou exatamente o que precisava, para quem precisava.

A regra é simples, a disciplina é difícil

Quando você sente a necessidade de emitir um evento que não corresponde a um fato real, isso não é um sinal de que a arquitetura está limitada. É um sinal de que os comandos do serviço destino não estão expostos como deveriam.

O evento certo emitido pelo motivo errado causa mais dano do que o evento errado porque passa pelos validadores, é aceito pelos handlers, e contamina o sistema inteiro enquanto parece perfeitamente correto nos logs.

Na versão original, a “corrida dos ratos” é um conceito popularizado por Robert Kiyosaki no livro Rich Dad Poor Dad. A metáfora descreve um ciclo em que a pessoa trabalha mais para ganhar mais, gasta mais porque ganha mais, e precisa trabalhar ainda mais para sustentar o novo padrão de gastos. Exatamente como um rato correndo numa roda sem sair do lugar.

Esse conceito é a referência para o texto de hoje!

Na original, descrita por Kiyosaki, o ciclo é financeiro: ganhar mais, gastar mais, precisar de mais. Na versão técnica, o ciclo é cognitivo: não saber, delegar para a IA, não conseguir avaliar, não aprender, saber menos.

O mecanismo é o mesmo. A roda gira, o esforço aumenta, e você não sai do lugar.

O pedido que você não sabe fazer

Você não consegue pedir o que não conhece. Se você nunca modelou um domínio complexo, não vai saber pedir para uma IA modelar. Se nunca debugou um deadlock em produção, não vai saber descrever o problema com precisão e clareza suficientes para receber uma resposta útil.

A qualidade do que a IA entrega é proporcional à profundidade do que você sabe perguntar.

A avaliação que você não consegue fazer

Pior que um código ruim é um código ruim que parece bom. Modelos geram soluções sintaticamente corretas e semanticamente perigosas com a mesma confiança. Se você não domina os detalhes, aceita. Coloca em produção. E descobre o custo semanas depois, meses depois, ou até anos depois, quando seu projeto enfim passa a receber atenção após muito esforço.

O aprendizado que não acontece

Aprender exige fazer, errar, corrigir, refazer. Quando você delega antes de aprender, elimina exatamente o ciclo que constrói competência.

Não existe atalho: ninguém aprende a nadar assistindo vídeos de natação.

E ninguém aprende arquitetura colando output de LLM.

O ciclo vicioso

Aqui está a armadilha:

• Você não sabe, então pede para a IA.
• A IA entrega algo que você não consegue avaliar.
• Você aceita sem entender.
• Você não aprende.
• Na próxima vez, sabe ainda menos.

Cada iteração te torna mais dependente e menos capaz de identificar o que está errado.

A IA é uma ferramenta extraordinária para quem já construiu o repertório que permite usá-la com critério.

Para quem ainda não construiu, ela não é atalho.

É uma armadilha com interface amigável.

Antes de perguntar “como a IA pode fazer isso por mim“,
pergunte: “eu saberia avaliar se a resposta está errada?“

Se a resposta for não, o próximo passo não é um prompt melhor.

É estudar.

A pergunta que ninguém faz é: por que você está adotando uma solução cujo custo operacional mínimo você se recusa a pagar?

O problema não é a ferramenta — é o subterfúgio

Eu já perdi a conta de quantos projetos .NET eu avaliei onde a equipe adotou um conceito bom conceito, um bom padrão arquitetural, uma boa tecnologia, mas na hora de tornar real a implementação, optou por gambiarras que quebravam completamente o conceito original.

E os problemas são dos mais diversos, desde a :

• adoção de filas, mas em banco de dados.
• adoção de serviços de identidade, mas abstraindo o serviço
• adoção de cache, mas em banco ou em disco
• adoção de NuGet para publicar pacotes, mas compartilhando pacotes em diretórios
• adoção de docker ou kubernetes, mas sem querer adotar container registry

Os padrões se repetem com uma previsibilidade deprimente:

NuGet sem servidor — O time cria pacotes NuGet e distribui via pasta compartilhada, feed local, ou pior: copia DLLs entre repositórios. A consequência? Ninguém sabe qual versão está em produção. Não existe rastreabilidade. O pacote “compartilhado” vira um Frankenstein que cada projeto consome de um jeito.

Containers sem registry — O time escreve Dockerfiles, builda imagens localmente, e faz deploy via docker save e docker load, ou publica direto no host. Não existe versionamento de imagens. Não existe rollback confiável. O “container” virou um zip quase sofisticado.

Filas no banco de dados — O time precisa de processamento assíncrono, mas em vez de adotar RabbitMQ ou qualquer broker real, cria uma tabela queue_messages com polling a cada 5 segundos. O banco de dados, que já era o gargalo, agora também é o message broker. A fila não tem dead-letter, não tem retry com backoff, não tem observabilidade, não tem nada que uma fila de verdade oferece desde o primeiro segundo de operação.

Cada um desses cenários compartilha a mesma raiz: a recusa em assumir o custo operacional das decisões técnicas tomadas.

O custo invisível do atalho

Subterfúgios não são gratuitos. Eles parecem mais baratos no início porque transferem o custo do orçamento de infraestrutura para o orçamento de complexidade. E complexidade é a dívida mais cara que existe em software, porque ela cobra juros compostos em cada sprint.

Quando você evita um NuGet Server privado, você não economiza.

• Você paga com horas de debug tentando descobrir por que o projeto A usa a versão 2.1 do pacote e o projeto B usa a 2.3.
• Você paga com o time tentando descobrir um comportamento que só existe na biblioteca, que não reflete o que existe no repositório, e descobre que determinada versão foi gerada na máquina do dev, mas o respectivo código não foi corretamente versionado.
• Paga com builds quebrados porque alguém atualizou a DLL na pasta compartilhada sem avisar.
• Paga com a impossibilidade de fazer rollback de um componente compartilhado para uma versão anterior.

Quando você evita um Container Registry,

• você paga com deploys que não podem ser reproduzidos porque a imagem foi construída na máquina de alguém.
• Paga com zero auditoria sobre o que está rodando em produção.
• Paga com a incapacidade de escalar horizontalmente de forma confiável.
• Paga com a inviabilidade de usar serviços profissionais e gerenciados para lidar com seu workload.

Quando você substitui um message broker por uma tabela no banco,

• você paga com dead locks, contenção e degradação de performance no banco principal.
• Paga com mensagens perdidas silenciosamente quando o polling falha.
• Paga com um sistema de retry artesanal que nunca vai cobrir todos os edge cases que um broker dedicado já resolveu há décadas.
• Paga com uma infinidade de conexões atolando o banco de dados, tornando-o quase inoperante.
• Paga com a dependência.

A infraestrutura que você se recusa a pagar não desaparece. Ela reaparece como complexidade no seu dia-a-dia., na sua operação, mesmo que sequer tenha alcançado produção ainda.

Faça apenas uma vez, faça bem feito, faça de forma definitiva

As interpretações de ágil e o conceito de agilidade foram deturpados e usados pra criar justificativas pra a gambiarra.

Para o profissional ruim, fazer apenas “o necessário” é o suficiente para “funcionar”.

E assim se gastamos mais lidando com a gambiarra, do que fazendo do jeito certo uma só vez.

Se precisamos compartilhar código, criamos pacotes nuget.

Se precisamos criar pacotes NuGet, nós subimos na nossa infra ou contratamos como serviço um NuGet Server.

Se vamos trabalhar com containers, nós subimos na nossa infra ou contratamos como serviço um Container Registry.

Se precisamos de cache distribuído, nós adotamos Redis ou Dragonfly.

Se precisamos de filas, nós usamos RabbitMQ — não uma tabela no banco de dados.

Aí o zé gambiarra diz: “Mas isso adiciona complexidade operacional!” — Sim, adiciona.
E torço para que a escolha de um novo padrão, uma nova arquitetura ou uma nova tecnologia tenha sido feita por necessidade.

Pois não há adição de padrão, arquitetura ou tecnologia que não gere demanda adicional. Até porque é essa demanda adicional que, normalmente, é a solução para o problema que a tecnologia resolve.

A nova complexidade é explícita, documentada e gerenciável e principalmente: Conhecida. Não é novidade e não deveria ser surpresa. Ao ponto de facilmente poder ser adicionada a um requisito de vaga no LinkedIn.
Diferente da complexidade acidental que o subterfúgio adotado dentro de casa, ou melhor a gambiarra caseira criaria, que é invisível, imprevisível e cumulativa.

Mas adotar a ferramenta certa não significa aceitar burocracia desnecessária. Significa projetar o fluxo para que fazer o certo seja o caminho mais fácil.

Na prática: NuGet + git submodules = Zero Burocracia

Um dos cenários mais comuns é o desenvolvimento de componentes compartilhados via NuGet.

O fluxo ingênuo é:

• Alterar o código do componente
• Fazer commit e push para o repositório
• Esperar a pipeline rodar
• A pipeline publica no pacote no NuGet Server
• Atualizamos a referência no projeto consumidor
• Finalmente podemos testar o novo código.

4 passos adicionais entre codificar e testar uma mudança.

Isso definitivamente mata a produtividade e incentiva exatamente o tipo de atalho que queremos evitar.

A abordagem que eu uso combina git submodules com condicionais no .csproj para eliminar essa fricção sem abrir mão da governança:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
  </PropertyGroup>

  <!-- Em modo Debug, usa o código-fonte via submodule -->
  <ItemGroup Condition="'$(Configuration)' == 'Debug'">
    <ProjectReference Include="..\submodules\MeuComponente\src\MeuComponente.csproj" />
  </ItemGroup>

  <!-- Em modo Release, exige o pacote publicado -->
  <ItemGroup Condition="'$(Configuration)' == 'Release'">
    <PackageReference Include="MeuComponente" Version="3.2.1" />
  </ItemGroup>

</Project>

O que esse setup garante:

Durante o desenvolvimento (Debug), o componente é referenciado como projeto via submodule. O desenvolvedor altera o código do componente, compila, testa e depura — tudo localmente, sem pipeline, sem espera, sem burocracia.

No build oficial (Release), o componente é consumido como pacote NuGet. Se a versão 3.2.1 não existir no NuGet Server, o build falha. Não existe deploy sem a versão correta publicada.

Essa dualidade é o que torna o fluxo sustentável. O desenvolvedor não é penalizado durante o desenvolvimento — o ciclo de feedback é instantâneo. A pipeline não aceita atalhos — o pacote precisa existir, versionado e publicado, para que o release funcione. A rastreabilidade é total — cada release aponta para uma versão específica de cada componente.

O git submodule funciona como um portal bidirecional: em debug, você enxerga e edita o código real. Em release, a referência de projeto simplesmente não existe — o build exige o pacote concreto.

Dica: Eu uso esse mesmo conceito para microsserviços…

O princípio por trás da prática

O padrão aqui não é sobre NuGet ou git submodules. É sobre um princípio de design de fluxo de trabalho:

Fazer a coisa certa deve ser o caminho de menor resistência.
Fazer a coisa errada deve ser impossível — ou pelo menos, visivelmente mais difícil.

Quando você projeta o fluxo de forma que o build de release só funciona com o pacote publicado, você não precisa de documento de processo, não precisa de checklist, não precisa de code review focado em “será que ele atualizou a versão?”. O sistema impõe a regra.

Quando você dá ao desenvolvedor um submodule para iterar localmente, você remove o incentivo para copiar DLLs, referenciar pacotes locais, ou qualquer outra gambiarra que surge quando o caminho correto é burocrático demais.

E para o resto da infraestrutura?

O mesmo princípio se aplica a cada decisão operacional.

Container Registry — Sim, tem custo. O GitHub Container Registry tem um tier gratuito generoso. O GitLab tem registry integrado. O Harbor é open-source e pode ser self-hosted. O Azure Container Registry tem um SKU básico. A desculpa de custo não sobrevive a 15 minutos de pesquisa.

Message Broker — O RabbitMQ roda em um container com um docker compose up. O CloudAMQP tem tier gratuito para ambientes de desenvolvimento. Não existe cenário onde uma tabela com polling é mais fácil de operar do que um broker que já nasce com retry, dead-letter, exchange routing e management UI.

Cache distribuído — O Redis também roda em um container. O Dragonfly é um drop-in replacement com melhor performance e menor consumo de memória. Ambos oferecem observabilidade nativa que qualquer implementação caseira levaria meses para atingir.

Nenhuma dessas soluções é gratuita em termos de operação. Mas a operação delas é conhecida, documentada e suportada por comunidades enormes. A operação da sua gambiarra é conhecida por uma pessoa — e essa pessoa vai sair da empresa em algum momento.

Conclusão

A próxima vez que alguém no seu time sugerir “a gente resolve isso com uma tabela no banco” ou “dá pra compartilhar o pacote por pasta”, faça uma pergunta simples:

Se a solução correta existe, é acessível e é documentada
— por que estamos inventando uma versão pior?

A resposta quase sempre é uma combinação de preguiça operacional com medo de assumir responsabilidade por infraestrutura. E essas duas coisas, em um time que se propõe a trabalhar com sistemas distribuídos, são incompatíveis com o resultado que se espera entregar.

Faça o que precisa ser feito.
Pague o preço da decisão que você tomou
ou não tome a decisão alguma.

Existe uma expectativa velada em muitos times de desenvolvimento: a de que bons desenvolvedores simplesmente “se envolvem” com a arquitetura. Que eles naturalmente vão questionar decisões, propor melhorias e contribuir para a evolução técnica do projeto.

Mas aqui está o problema que quase ninguém está disposto a falar: como alguém pode ser proativo em relação a algo que não conhece, não enxerga e não tem acesso?

Em boa parte dos projetos .NET de grande porte que já restruturei, encontrei o mesmo padrão no legado. Os componentes arquiteturais existiam, funcionavam e sustentavam o ecossistema — mas viviam encapsulados na cabeça de quem os criou. Sem documentação acessível, sem convenções claras de contribuição, sem um caminho visível para quem quisesse entender o porquê das decisões tomadas.

O resultado é previsível: desenvolvedores que poderiam contribuir ficam à margem. Não por falta de interesse ou capacidade, mas por falta de acesso. E quando algo dá errado, a narrativa é sempre a mesma — “o time não é proativo”, “ninguém se preocupa com arquitetura”, “está na cabeça do arquiteto que saiu”.

A verdade é mais incômoda: não é possível cobrar proatividade, muito menos de quem não tem acesso à arquitetura. Se os componentes que sustentam o projeto não estão disponíveis, organizados e com regras claras de evolução, o problema não está no desenvolvedor. Está na governança.

E foi exatamente para resolver isso que, ao longo dos anos, construí um conjunto de regras que me ajudam a conduzir projetos de grande porte. Regras que não apenas organizam componentes, mas criam um caminho claro para quem quer — e pode — contribuir com a arquitetura e infraestrutura de aplicação.

Antes de chegar nelas, porém, é preciso reconhecer algo que muitos líderes técnicos ignoram: nem todo desenvolvedor tem a mesma relação com a arquitetura.

E está tudo bem.

Os 4 perfis de desenvolvedores diante da arquitetura

Ao longo dos anos, percebi que desenvolvedores se posicionam diante da arquitetura de formas muito diferentes. Não é uma questão de senioridade no crachá — é uma combinação de interesse, capacidade e momento de carreira. Identifico 4 perfis recorrentes:

Os que querem e podem. São desenvolvedores que têm interesse genuíno pela arquitetura e possuem a capacidade técnica para propor evoluções consistentes. Eles entendem trade-offs, conhecem o ecossistema e sabem que mudar um componente significa pensar em tudo que depende dele. Esses profissionais precisam de acesso e de um caminho formal para contribuir — sem isso, você os perde para a frustração ou para outra empresa.

Os que querem, mas ainda não podem. Têm a curiosidade e a vontade, mas ainda não acumularam a experiência necessária para propor mudanças arquiteturais seguras. São os futuros arquitetos do seu time — se você criar as condições certas para que aprendam. O erro mais comum é ignorá-los ou, pior, dar a eles liberdade total sem guardrails. O resultado quase sempre é retrabalho.

Os emocionados. Querem aprender, estão empolgados com a tecnologia, mas seu interesse é mais sobre absorver conhecimento do que sobre contribuir com mudanças. Não há nada de errado com isso. Eles são valiosos porque trazem energia e questionamentos que, muitas vezes, revelam pontos cegos na documentação ou na clareza dos componentes. Porém precisam de limites claros para não confundir entusiasmo com autonomia para alterar o que não compreendem por completo.

Os que não se importam — desde que funcione. Para eles, a arquitetura é um meio, não um fim. Querem entregar funcionalidades, resolver problemas de negócio e seguir em frente. Esse perfil não é um problema — é uma realidade. Nem todo desenvolvedor precisa se tornar arquiteto. O que você precisa garantir é que os componentes arquiteturais simplifiquem o trabalho deles, sem exigir que entendam cada decisão por trás do design.

Esses 4 perfis coexistem na maioria dos times. O papel da governança arquitetural não é forçar todos a se tornarem arquitetos, mas criar um sistema que atenda a cada perfil de forma adequada: acesso para quem pode contribuir, guardrails para quem está aprendendo, clareza para quem só quer usar, e um filtro natural para separar entusiasmo de comprometimento real.

É exatamente isso que as 7 regras a seguir fazem.

As 7 regras para governança de componentes arquiteturais

Essas regras não surgiram de teoria. Elas nasceram de projetos reais, com times reais, enfrentando os mesmos problemas que provavelmente você enfrenta hoje: componentes duplicados, mudanças que quebram o ecossistema, desenvolvedores que refazem o que não entenderam e uma sensação constante de que a arquitetura está se fragmentando.

Organizei as regras em 3 blocos para facilitar a compreensão: acesso e simplificação, organização e qualidade, e responsabilidade ecossistêmica.

Acesso e simplificação

Regra 1: os componentes arquiteturais precisam estar disponíveis para os desenvolvedores.

Parece óbvio, mas não é. Em muitos projetos, os componentes existem como pacotes NuGet internos mal documentados, ou como código em repositórios que poucos sabem que existem, ou pior — como conhecimento tácito na cabeça de alguém que já saiu do time.

Se um componente não está disponível de forma clara — com documentação, exemplos de uso e um caminho para entender suas decisões de design — ele não existe para o time. E você não pode cobrar envolvimento com algo que, na prática, é invisível.

Disponibilizar não significa apenas publicar um pacote. Significa tornar visível o quê o componente faz, por quê ele existe, como deve ser usado e quais são seus limites. Sem isso, cada desenvolvedor vai criar sua própria solução — e aí começam as duplicações, as inconsistências e a erosão arquitetural silenciosa que só aparece quando já é tarde demais.

Regra 2: os componentes arquiteturais devem simplificar o desenvolvimento e formalizar a forma de trabalho com determinadas tecnologias.

Um componente arquitetural que adiciona complexidade é um componente que falhou no seu propósito. Se o desenvolvedor precisa entender 15 camadas de abstração para publicar uma mensagem no RabbitMQ ou para configurar um cache no Redis, algo está errado.

O papel do componente é encapsular decisões arquiteturais e transformá-las em APIs simples e coerentes. Ele deve formalizar a forma como o time trabalha com determinada tecnologia — estabelecendo padrões, convenções e limites — mas sem criar uma barreira de entrada que afaste justamente quem deveria usá-lo.

Na prática, o componente deve ser o caminho mais fácil para fazer a coisa certa. Se o desenvolvedor percebe que é mais simples ignorar o componente e implementar diretamente, você tem um problema de design, não de disciplina.

Organização e qualidade

Regra 3: componentes são organizados em componentes locais (do projeto), regionais (compartilhados entre alguns projetos) e globais (da empresa).

Essa distinção é fundamental e resolve um problema que poucos times enfrentam de forma consciente: nem todo componente tem o mesmo escopo de impacto.

Componentes locais pertencem a um projeto específico. Eles encapsulam decisões que fazem sentido naquele contexto, para aquele domínio, com aquelas restrições. Seu raio de explosão é limitado — se algo der errado, o impacto é restrito ao projeto.

Componentes regionais são compartilhados entre um grupo de projetos que possuem afinidade técnica ou de domínio. Eles nascem quando dois ou mais projetos enfrentam o mesmo problema e a solução local se prova reutilizável — mas ainda não justifica uma adoção global. O regional é o nível mais traiçoeiro, porque vive no limbo entre a flexibilidade do local e a rigidez do global. Se não for governado com clareza, ele se torna um componente global disfarçado, sem o rigor que isso exige.

Componentes globais são compartilhados entre todos os projetos da empresa. Eles representam decisões arquiteturais que transcendem domínios específicos e afetam todo o ecossistema. Seu raio de explosão é proporcional ao número de consumidores — e, por definição, esse número é o maior possível.

Tratar os três da mesma forma é um erro. A exigência de qualidade, o processo de aprovação e a rigidez das validações precisam ser proporcionais ao impacto. E é exatamente isso que as duas regras seguintes estabelecem.

Regra 4: componentes locais possuem validações de arquitetura flexibilizadas para o processo educacional de formar novos arquitetos.

Componentes locais são o campo de treinamento. É aqui que os desenvolvedores dos perfis 2 e 3 — os que querem mas ainda não podem, e os emocionados — têm espaço para experimentar, errar e aprender.

Flexibilizar as validações não significa ausência de padrão. Significa que o custo de um erro é menor e que existe espaço para iteração. Um componente local pode ter uma abstração imperfeita, uma API que ainda não está no ponto ideal, um design que funciona mas não escala. Tudo isso é aceitável se o componente está contido no escopo do projeto e se serve como instrumento de aprendizado.

Esse é um ponto que muitos líderes técnicos erram: exigir o mesmo rigor de um componente local e de um componente global mata a iniciativa. O desenvolvedor que poderia estar aprendendo a pensar arquiteturalmente desiste porque o custo de contribuir é alto demais. E quando você perde essa janela de formação, perde futuros arquitetos.

Regra 5: componentes regionais e globais possuem validações exaustivas de qualidade — proporcionais ao seu alcance.

Se componentes locais são o campo de treinamento, componentes regionais e globais são produção. Aqui, o rigor é inegociável — mas a intensidade varia.

Um componente regional será consumido por um grupo conhecido de projetos. O processo de validação precisa ser rigoroso, mas o escopo de impacto é mapeável: você sabe quem são os consumidores, pode coordenar mudanças diretamente e o custo de uma migração é administrável. O rigor existe, mas com a vantagem de um raio de impacto controlado.

Um componente global vai ser consumido por todos os projetos da empresa, mantido por múltiplos times e vai sobreviver a múltiplas gerações de desenvolvedores. Ele precisa de testes exaustivos, documentação completa, versionamento rigoroso e um processo de revisão que garanta que cada mudança foi pensada no contexto do ecossistema inteiro. Aqui, o custo de um erro não é um projeto instável — é a confiança de toda a organização naquela fundação.

O padrão de qualidade mais alto não é burocracia — é proteção. Cada consumidor daquele componente confiou que ele se comportaria de determinada forma. Quebrar esse contrato sem critério é quebrar a confiança de todo o ecossistema.

Responsabilidade ecossistêmica

Regra 6: componentes não podem sobrepor-se em funcionalidade.

Sobreposição é o sintoma mais claro de governança ausente. Quando dois componentes fazem a mesma coisa de formas diferentes, o time perde a referência de qual é o caminho oficial. Cada desenvolvedor escolhe o que parece mais conveniente no momento, e a base de código se fragmenta.

Essa regra parece simples, mas sua aplicação exige disciplina constante. Toda vez que alguém propõe um novo componente, a primeira pergunta deve ser: isso já não existe? E se existe, por que não atende? Se a resposta for “porque eu não gosto de como foi feito”, voltamos ao próximo ponto — que é justamente sobre o que significa querer mudar algo que já existe.

Regra 7: ao querer recriar ou modificar um componente, é preciso pensar nos demais consumidores. Não é permitido manter duas versões totalmente diferentes em produção.

Essa é a regra mais exigente — e a mais importante. Ela estabelece que quem quer mudar um componente precisa assumir responsabilidade pelo ecossistema inteiro que depende dele.

Na prática, isso significa que subir uma nova versão de um componente global implica adaptar todos os projetos estáveis que o consomem. Não é permitido deixar a versão antiga rodando indefinidamente enquanto a nova segue em paralelo. Isso cria fragmentação, dificulta manutenção e gera inconsistências que se acumulam silenciosamente.

Essa regra é dura por design. Ela existe para filtrar mudanças impulsivas de mudanças fundamentadas. Se um desenvolvedor quer reescrever um componente, ele precisa primeiro entender por que o componente é como é — quais requisitos o moldaram, quais trade-offs foram aceitos, quais limitações foram deliberadas. Depois, precisa mapear todos os consumidores e planejar a migração.

Se, depois de tudo isso, ele ainda quer seguir em frente, é porque tem algo melhor a entregar. E esse dev merece livre passagem para entregar o seu melhor.

O filtro natural

Olhando para as 7 regras em conjunto, percebe-se que elas não são apenas governança técnica. Elas funcionam como um mecanismo de seleção natural.

Pense no desenvolvedor que quer modificar um componente global. Pelas regras, ele precisa:

• Entender todos os requisitos que levaram o componente a existir na forma atual.
• Mapear todos os projetos e serviços que dependem dele.
• Planejar uma migração que não quebre o ecossistema.
• Garantir que sua proposta atende às validações exaustivas de qualidade.

Cada uma dessas etapas é um filtro. Não um filtro burocrático, mas um filtro de comprometimento.

O desenvolvedor que desiste na primeira etapa aprendeu algo valioso: que o componente não é arbitrário, que existem razões concretas para cada decisão. Isso, por si só, já é uma vitória educacional — ele sai do processo entendendo o porquê, mesmo que não mude nada.

O desenvolvedor que desiste na segunda etapa descobriu a dimensão real do impacto. Percebeu que sua mudança não é isolada, que o ecossistema é maior do que o caso de uso que ele tinha em mente. Esse entendimento muda a forma como ele avalia mudanças dali em diante.

E o desenvolvedor que passa por todas as etapas e ainda quer seguir? Esse entendeu os requisitos, mapeou as dependências, planejou a migração e ainda assim está convencido de que tem algo melhor a entregar. Esse profissional não está agindo por impulso ou por preferência pessoal — está agindo por convicção técnica fundamentada.

Esse é o tipo de contribuição que evolui a arquitetura de verdade. E é exatamente o tipo de pessoa que as regras foram desenhadas para revelar.

Arquitetura aberta é arquitetura que evolui

Governança arquitetural não é sobre restringir. É sobre criar as condições certas para que a arquitetura evolua de forma sustentável, com contribuições de quem realmente entende o peso do que está mudando.

Abrir a arquitetura — tornar componentes disponíveis, documentados e com regras claras — não significa perder controle. Significa criar um funil que desenvolve pessoas enquanto protege o ecossistema. Os curiosos aprendem, os comprometidos contribuem e os que só querem entregar funcionalidades têm um caminho simples para fazê-lo.

O primeiro passo é simples, mas exige honestidade: olhe para o seu projeto hoje e se pergunte — os componentes estão realmente acessíveis? Existe um caminho claro para quem quer contribuir? Ou você está cobrando proatividade de quem nunca teve acesso?

Se a resposta for incômoda, talvez seja hora de começar pelas regras.

if (grupo.Tipo == TipoGrupo.Administrador)
{
    // pode acessar tudo
}
else if (grupo.Tipo == TipoGrupo.Operador)
{
    // pode acessar quase tudo
}
else if (grupo.Tipo == TipoGrupo.Visualizador)
{
    // só leitura
}

Esse código parece inofensivo. Está limpo, compila, passa no code review. Mas ele carrega um problema estrutural que escala de forma destrutiva: o comportamento do sistema está implícito no código, não explícito no modelo.

Quem olha para o enum TipoGrupo não sabe quais permissões cada tipo carrega. Quem olha para o banco de dados não encontra essa informação. Quem precisa adicionar um novo tipo precisa caçar todos os if e switch espalhados pela aplicação para entender o que precisa implementar.

Isso não é modelagem. É arqueologia.

o problema real: enums escondem especificações inteiras

Um enum em C# é, na essência, um inteiro com um apelido, um nome. Ele não carrega semântica, não expressa capacidades, não declara limites. Toda a inteligência que deveria estar associada àquele valor vive em outro lugar — dispersa em condicionais, enterrada em services, duplicada entre controllers e workers.

Considere um sistema de pedidos com status:

public enum StatusPedido
{
    Rascunho,
    Confirmado,
    EmProcessamento,
    Enviado,
    Entregue,
    Cancelado
}

Parece completo. Mas esse enum não responde a nenhuma pergunta relevante sobre comportamento:

• Quais status permitem cancelamento?
• Em quais status o pedido pode ser editado?
• Quais status geram notificação ao cliente?
• Quais transições de status são válidas?

Essas respostas estão espalhadas pelo código. E cada desenvolvedor que precisa dessa informação faz a mesma jornada: abre o repositório, busca por StatusPedido, lê dezenas de arquivos, monta mentalmente o mapa de comportamentos, e torce para não ter esquecido nenhum caso.

Quando um status novo precisa ser adicionado — digamos, AguardandoRetirada — o desenvolvedor adiciona o valor no enum e… começa a caçada. Cada switch precisa ser revisado. Cada if que compara com StatusPedido.Enviado pode precisar incluir o novo status. E se algum for esquecido, o bug não aparece na compilação. Aparece em produção.

Isso viola frontalmente o Open/Closed Principle: o sistema deveria ser aberto para extensão e fechado para modificação. Adicionar um novo tipo ou status não deveria exigir alteração de código existente. Mas com enums, cada novo valor é uma cirurgia em toda a base de código.

Alternativa: Discriminadores de Comportamento

A solução não é complexa. É uma mudança de perspectiva na modelagem: em vez de tratar status e tipos como constantes opacas, modelamos como entidades que declaram seus próprios comportamentos.

Em vez disso:

Tabela: Pedidos
- Id
- StatusPedidoId (int, FK → ?)
- ...

Enum no código: StatusPedido { Rascunho = 1, Confirmado = 2, ... }

Fazemos isso:

CREATE TABLE StatusPedido (
    Id INT PRIMARY KEY,
    Nome VARCHAR(50) NOT NULL,
    PermiteCancelamento BIT NOT NULL DEFAULT 0,
    PermiteEdicao BIT NOT NULL DEFAULT 0,
    NotificaCliente BIT NOT NULL DEFAULT 0,
    ExigeAprovacao BIT NOT NULL DEFAULT 0,
    Ativo BIT NOT NULL DEFAULT 1
);

INSERT INTO StatusPedido (Id, Nome, PermiteCancelamento, PermiteEdicao, NotificaCliente, ExigeAprovacao)
VALUES
    (1, 'Rascunho',          1, 1, 0, 0),
    (2, 'Confirmado',        1, 0, 1, 0),
    (3, 'Em Processamento',  0, 0, 0, 0),
    (4, 'Enviado',           0, 0, 1, 0),
    (5, 'Entregue',          0, 0, 1, 0),
    (6, 'Cancelado',         0, 0, 1, 0);

Agora cada status declara explicitamente o que permite e o que não permite. Não existe dedução. Não existe interpretação. A especificação está no dado, não no código.

O mesmo princípio para tipos: flags de comportamento

Voltando ao exemplo do tipo de grupo. Em vez de perguntar “este grupo é do tipo Administrador?”, perguntamos “este tipo de grupo possui a capacidade de administração?”:

CREATE TABLE TipoGrupo (
    Id INT PRIMARY KEY,
    Nome VARCHAR(50) NOT NULL,
    Administrador BIT NOT NULL DEFAULT 0,
    PodeGerenciarUsuarios BIT NOT NULL DEFAULT 0,
    PodeAcessarRelatorios BIT NOT NULL DEFAULT 0,
    PodeAlterarConfiguracoes BIT NOT NULL DEFAULT 0
);

INSERT INTO TipoGrupo (Id, Nome, Administrador, PodeGerenciarUsuarios, PodeAcessarRelatorios, PodeAlterarConfiguracoes)
VALUES
    (1, 'Administrador', 1, 1, 1, 1),
    (2, 'Operador',      0, 0, 1, 1),
    (3, 'Visualizador',  0, 0, 1, 0),
    (4, 'Suporte',       0, 1, 1, 0);

A diferença é sutil na estrutura, mas profunda no impacto. Agora, quando o sistema precisa saber se um grupo pode gerenciar usuários, a pergunta é direta:

if (grupo.Tipo.PodeGerenciarUsuarios)
{
    // comportamento permitido
}

Não estamos mais perguntando quem o grupo é. Estamos perguntando o que o grupo pode fazer. Essa distinção elimina a necessidade de conhecer a lista de tipos para implementar lógica. O código se torna agnóstico ao tipo específico e reage às capacidades declaradas.

Quem se beneficia dessa abordagem?

Esse princípio deq ue “comportamentos não podem ser deduzidos” se aplica a qualquer entidade que carrega regras implícitas avaliadas por condicionais no código. Além de status e tipos, os candidatos mais óbvios:

Perfis e papéis (roles) — o clássico if (usuario.Role == "Admin") espalhado por dezenas de controllers. Flags como PodeAprovar, PodeExcluir, AcessaRelatorios tornam as capacidades do papel explícitas e extensíveis sem tocar em código.

Categorias de produto/serviço — quando a categoria define comportamento fiscal, logístico ou de precificação. Em vez de if (produto.Categoria == Categoria.Digital) para pular cálculo de frete, uma flag ExigeFrete na tabela de categorias.

Planos e níveis de assinatura (tiers) — if (plano == Plano.Premium) para liberar funcionalidades. Flags como PermiteExportacao, LimiteUsuarios, SuportePrioritario tornam cada plano autodescritivo.

Modalidades de pagamento — em vez de deduzir que boleto exige compensação assíncrona e cartão é síncrono, flags como CompensacaoAssincrona, PermiteEstorno, ExigeConfirmacao.

Tipos de documento/contrato — quando o tipo define fluxo de aprovação, validade, necessidade de assinatura digital. Flags como ExigeAssinatura, TemValidade, RequerAprovacao.

Severidades e prioridades (em sistemas de incidentes, tickets, alertas) — em vez de if (severidade == Severidade.Critica) para decidir se notifica por SMS, flags como NotificaSMS, EscalaAutomaticamente, BloqueiaDeploy.

Etapas de pipeline/workflow — qualquer sistema com fluxo de etapas onde cada etapa habilita ou bloqueia ações. Flags como PermiteRetrocesso, ExigeAnexo, GeraTarefa.

Tipos de evento em event-driven — quando o tipo do evento determina se ele exige retry, se é idempotente, se deve ir para dead letter após falha. Flags como Idempotente, RetryAutomatico, CriticoParaConsistencia.

O padrão é sempre o mesmo: se existe um if no código que avalia a identidade da entidade para deduzir um comportamento, esse comportamento deveria ser um discriminador explícito na tabela que define aquela entidade. A pergunta não é “quem é”, é “o que declara que pode fazer”.

Antes e Depois com C#

Antes: comportamento implícito, acoplado ao valor do enum

public class PedidoService
{
    public async Task CancelarAsync(Pedido pedido)
    {
        // quem decidiu que esses status permitem cancelamento?
        // onde está essa especificação?
        // se um novo status surgir, quem vai lembrar de atualizar aqui?
        if (pedido.Status != StatusPedido.Rascunho && 
            pedido.Status != StatusPedido.Confirmado)
        {
            throw new InvalidOperationException(
                "Pedido não pode ser cancelado no status atual.");
        }

        pedido.Status = StatusPedido.Cancelado;
        await _repository.AtualizarAsync(pedido);
    }

    public async Task EditarAsync(Pedido pedido, DadosPedido dados)
    {
        // mesma lógica espalhada em outro lugar
        if (pedido.Status != StatusPedido.Rascunho)
        {
            throw new InvalidOperationException(
                "Pedido não pode ser editado no status atual.");
        }

        pedido.Aplicar(dados);
        await _repository.AtualizarAsync(pedido);
    }

    public async Task NotificarClienteAsync(Pedido pedido)
    {
        // e aqui mais uma lista de status que "alguém sabe" que notifica
        if (pedido.Status == StatusPedido.Confirmado ||
            pedido.Status == StatusPedido.Enviado ||
            pedido.Status == StatusPedido.Entregue ||
            pedido.Status == StatusPedido.Cancelado)
        {
            await _notificacaoService.EnviarAsync(pedido);
        }
    }
}

Três métodos, três listas de status hardcoded, zero rastreabilidade. Se um status novo for adicionado ao enum, o compilador não reclama. O sistema simplesmente se comporta de forma errada — silenciosamente.

Depois: comportamento declarativo, dirigido por dados

public class StatusPedidoEntity
{
    public int Id { get; set; }
    public string Nome { get; set; }
    public bool PermiteCancelamento { get; set; }
    public bool PermiteEdicao { get; set; }
    public bool NotificaCliente { get; set; }
    public bool ExigeAprovacao { get; set; }
}

public class PedidoService
{
    public async Task CancelarAsync(Pedido pedido)
    {
        if (!pedido.Status.PermiteCancelamento)
        {
            throw new InvalidOperationException(
                $"Status '{pedido.Status.Nome}' não permite cancelamento.");
        }

        pedido.Status = await _statusRepository
            .ObterPorNomeAsync("Cancelado");
        await _repository.AtualizarAsync(pedido);
    }

    public async Task EditarAsync(Pedido pedido, DadosPedido dados)
    {
        if (!pedido.Status.PermiteEdicao)
        {
            throw new InvalidOperationException(
                $"Status '{pedido.Status.Nome}' não permite edição.");
        }

        pedido.Aplicar(dados);
        await _repository.AtualizarAsync(pedido);
    }

    public async Task NotificarClienteAsync(Pedido pedido)
    {
        if (pedido.Status.NotificaCliente)
        {
            await _notificacaoService.EnviarAsync(pedido);
        }
    }
}

O código encolheu, ficou mais legível e — o mais importante — parou de mentir. Não existem mais listas secretas de status que permitem ou proíbem ações. A verdade está na tabela. O código apenas pergunta.

O impacto em escala: da UI ao worker

Quando comportamentos estão declarados em dados, o benefício não se limita ao backend. Ele permeia toda a aplicação:

Na API, o endpoint que retorna um pedido pode incluir as capacidades do status atual. O frontend não precisa replicar lógica — recebe permiteCancelamento: true e renderiza ou esconde o botão.

No worker, o consumidor que processa eventos pode consultar flags do status para decidir se executa uma ação, sem carregar regras hardcoded que precisam ser sincronizadas com o backend.

Na documentação, a tabela de status com suas flags é, por si só, uma especificação funcional. Um product owner consegue ler a tabela e validar se os comportamentos estão corretos — sem ler código.

No onboarding, um desenvolvedor novo consulta uma tabela e entende imediatamente quais comportamentos cada status habilita. Não precisa fazer arqueologia em dezenas de arquivos para montar o mapa mental.

transições de status: o próximo passo natural

Se status declaram comportamentos, o passo seguinte é declarar também as transições válidas:

CREATE TABLE TransicaoStatusPedido (
    StatusOrigemId INT NOT NULL,
    StatusDestinoId INT NOT NULL,
    ExigeAprovacao BIT NOT NULL DEFAULT 0,
    PRIMARY KEY (StatusOrigemId, StatusDestinoId),
    FOREIGN KEY (StatusOrigemId) REFERENCES StatusPedido(Id),
    FOREIGN KEY (StatusDestinoId) REFERENCES StatusPedido(Id)
);

INSERT INTO TransicaoStatusPedido (StatusOrigemId, StatusDestinoId, ExigeAprovacao)
VALUES
    (1, 2, 0),  -- Rascunho → Confirmado
    (2, 3, 0),  -- Confirmado → Em Processamento
    (3, 4, 0),  -- Em Processamento → Enviado
    (4, 5, 0),  -- Enviado → Entregue
    (1, 6, 0),  -- Rascunho → Cancelado
    (2, 6, 1);  -- Confirmado → Cancelado (exige aprovação)

Agora a máquina de estados inteira é declarativa. Validar uma transição no código se reduz a uma consulta:

public async Task TransicionarAsync(Pedido pedido, int novoStatusId)
{
    var transicao = await _transicaoRepository
        .ObterAsync(pedido.Status.Id, novoStatusId);

    if (transicao is null)
    {
        throw new InvalidOperationException(
            $"Transição de '{pedido.Status.Nome}' para o status " + 
            $"destino não é permitida.");
    }

    if (transicao.ExigeAprovacao)
    {
        await _aprovacaoService.SolicitarAsync(pedido, novoStatusId);
        return;
    }

    pedido.Status = await _statusRepository.ObterAsync(novoStatusId);
    await _repository.AtualizarAsync(pedido);
}

Adicionar um novo status? Insere na tabela e define as transições. Zero alteração no código. Open/Closed honrado, não na teoria.

É para abolir o uso de Enums? Quando o enum ainda faz sentido

Seria desonesto dizer que enums não têm lugar. Eles são adequados quando o valor é genuinamente estático, sem comportamento associado e sem expectativa de extensão: dias da semana, unidades de medida, direções cardeais. Valores que são constantes universais, não regras de negócio disfarçadas.

O problema não é o enum como estrutura de dados. É o uso do enum como veículo de especificação implícita. Quando cada valor carrega consigo um conjunto de regras que só existem nos if do código, o enum deixou de ser uma constante e virou uma especificação escondida.

Checklist: como identificar enums que deveriam ser tabelas?

Se pelo menos uma das condições abaixo for verdadeira, o enum é candidato a ser promovido para tabela com flags de comportamento:

• Existe pelo menos um if ou switch no código que avalia o valor do enum para decidir um comportamento.
• Adicionar um novo valor ao enum exige alteração em mais de um arquivo.
• O significado de cada valor do enum precisa ser explicado verbalmente para novos desenvolvedores — não é autoevidente.
• O mesmo enum é avaliado em camadas diferentes da aplicação (API, serviço, worker) com lógicas que precisam estar sincronizadas.
• O product owner ou analista de negócio não consegue validar as regras associadas ao enum sem ler código.

Se três ou mais dessas condições são verdadeiras, não é uma questão de preferência. É débito técnico ativo.

Conclusão

Enums em C# são uma ferramenta de representação, não de modelagem. Quando usamos enums para carregar regras de negócio, estamos escolhendo conveniência no momento da escrita em troca de obscuridade permanente na manutenção.

Cada if (entidade.Status == Status.XPTO) é uma regra de negócio que existe apenas na memória de quem escreveu aquele código. Quando essa pessoa sai do time, a regra vira folclore. Quando o sistema cresce, o folclore vira risco operacional.

Promover status e tipos para tabelas com comportamento declarado não é overengineering. É tornar explícito o que já existe — só que escondido nos lugares errados.

A pergunta que todo arquiteto deveria fazer ao revisar um modelo de domínio é simples: se eu apagar todo o código e olhar apenas para o banco de dados, consigo entender o que o sistema permite e o que ele proíbe?

Se a resposta é não, os dados estão incompletos. E nenhuma quantidade de if no código compensa um modelo que não se explica sozinho.

A seguir, um resumo das principais novidades.

O que mudou de v1.1 para v1.6

Suporte a .NET 10

A partir da v1.6.0, o projeto passou a ter suporte nativo a três gerações do .NET simultaneamente:

• .NET 8 (LTS)
• .NET 9
• .NET 10 (adicionado na v1.6.0) Isso garante que equipes em diferentes estágios de adoção possam utilizar a biblioteca sem restrições.

Novos Padrões de Mensageria: ReplyResult e ForwardResult (Estáveis)

Introduzidos como experimentais na v1.4.0 e promovidos a estáveis na v1.6.0, esses dois novos IAmqpResult ampliam significativamente os padrões de mensageria suportados:

ReplyResult – Padrão RPC (Request-Reply)

Permite que um handler responda diretamente ao remetente da mensagem, habilitando o padrão RPC de forma nativa:

app.MapQueue("rpc-queue", (MyRequest request) =>
  {
      var response = ProcessRequest(request);
      return AmqpResults.ReplyAndAck(response);
  });

• Extrai automaticamente o ReplyTo da mensagem original
• Preserva correlação via CorrelationId / MessageId
• Cria um canal dedicado para a resposta, evitando race conditions

ForwardResult – Encaminhamento de Mensagens Permite redirecionar mensagens

processadas para outros exchanges/filas:

app.MapQueue("intake-queue", (Order order) =>
  {
      var enrichedOrder = Enrich(order);
      return AmqpResults.ForwardAndAck("orders-exchange", "processed", mandatory: true, enrichedOrder);
  });

• Suporta envio para exchanges com routing key
• Flag mandatory para garantia de entrega
• Parâmetro opcional replyTo para encadeamento de replies

ComposableResult – Composição de Ações

Permite encadear múltiplas ações AMQP em um único retorno de handler:

app.MapQueue("my-queue", (MyMessage msg) =>
  {
      return AmqpResults.Compose(
          AmqpResults.Reply(response),
          AmqpResults.Forward("audit-exchange", "audit.key", false, msg),
          AmqpResults.Ack()
      );
  });

Métodos auxiliares como AmqpResults.ReplyAndAck() e AmqpResults.ForwardAndAck() simplificam os casos mais comuns.

Topology Initializer – Declaração Programática de Topologia

Adicionado na v1.5.0 (originalmente como ChannelInitializer, renomeado na v1.5.2 para maior clareza), permite declarar exchanges, filas e bindings antes do consumer começar a consumir:

  app.MapQueue("my-queue", handler)
     .WithTopology(async (channel, ct) =>
     {
         await channel.ExchangeDeclareAsync("my-exchange", "topic", cancellationToken: ct);
         await channel.QueueBindAsync("my-queue", "my-exchange", "routing.key", cancellationToken: ct);
     });

Isso elimina a necessidade de configuração externa de topologia e garante que a infraestrutura esteja pronta antes do consumo iniciar.

Otimizações de Performance: Expression Trees

A v1.6.0 trouxe duas otimizações significativas que eliminam o uso de Reflection no hot path:

Dispatcher com Expression-based Invoker

O Dispatcher substituiu DynamicInvoke (reflection) por delegates compilados via System.Linq.Expressions. O delegate é compilado uma única vez na inicialização e reutilizado para todos os dispatches de mensagem:

Antes: handler.DynamicInvoke(args) // reflection em cada mensagem
Depois: compiledInvoker(args) // delegate compilado, zero reflection

TaskOfAmqpResultResultHandler com Expression-based Extractor

A extração de Task.Result também foi migrada de PropertyInfo.GetValue para Expression Trees compiladas.

Resultado nos benchmarks: O overhead do Oragon sobre o consumer nativo do RabbitMQ.Client é de apenas ~1-5% em throughput, com ratio ~1.00 em cenários de I/O bound e ~1.02-1.07 em cenários CPU bound.

Eventos de Conexão: Shutdown, Blocked e Unblocked

Novos event handlers no QueueConsumer oferecem visibilidade sobre o estado da conexão:

• ConnectionShutdownAsync (Critical): Loga quando a conexão é perdida, indicando que o consumer não se auto-recupera
• ConnectionBlockedAsync (Warning): Detecta quando o RabbitMQ está sob pressão de recursos (memória/disco)
• ConnectionUnblockedAsync (Information): Indica que a pressão de recursos foi resolvida.

Todos utilizam o padrão de alta performance LoggerMessage.Define com event IDs estruturados.

Health Checks Integrados

Integração nativa com o sistema de Health Checks do ASP.NET Core, especialmente útil com .NET Aspire:

builder.AddRabbitMQClient("rabbitmq"); // Health check registrado automaticamente

• Registra health checks automaticamente ao configurar a conexão
• Suporte a conexões keyed e non-keyed
• Pode ser desabilitado via settings.DisableHealthChecks = true
• Degradação graciosa: se a conexão falhar durante o registro, usa um FailedHealthCheck wrapper

IAsyncDisposable e Gerenciamento de Recursos

A gestão de ciclo de vida foi modernizada:

• ConsumerServer: Removido IDisposable síncrono, mantendo apenas IAsyncDisposable
• QueueConsumer: Dispose assíncrono completo com cancelamento de tokens, desregistro de event handlers e disposal do channel
• Consumers são descartados em ordem reversa durante o shutdown
• Proteção contra double-disposal com flag disposedValue

Melhorias de Thread-Safety e Async

• Uso correto e consistente de ConfigureAwait em toda a stack
• Campo isLocked no ConsumerDescriptor tornado volatile para thread-safety
• Propagação adequada de CancellationToken em toda a cadeia assíncrona
• Criação de conexões totalmente assíncrona

Logging de Alta Performance

• Adoção do LoggerMessage.Define para alta performance
• Logging estruturado com Event IDs em todos os caminhos críticos
• Log para mensagens deserializadas como null (EventId 12)
• Informações diagnósticas detalhadas em eventos de conexão

Cobertura de Testes Ampliada

Novos testes unitários adicionados para:

• ConsumerDescriptor (+518 linhas)
• QueueConsumer (+525 linhas)
• ConsumerServer (+439 linhas)
• ForwardResult (+196 linhas)
• AsStringExtensions, NewReverseList, e mais

Nossas métricas no sonar estão bem interessantes também:

Benchmarks – A cereja do bolo

A v1.6.0 inclui um projeto de benchmarks (Oragon.RabbitMQ.Benchmarks) com cenários que medem:

• Throughput: Comparação direta Native vs Oragon
• Latência: Overhead por mensagem
• Alocações: Memória alocada por operação
• Escalabilidade de Concorrência: Comportamento com diferentes níveis de prefetch e dispatch concurrency
• RPC: Performance do padrão request-reply Os resultados confirmam que o Oragon mantém performance virtualmente idêntica ao consumer nativo em cenários I/O bound (ratio ~1.00).

Cronologia

O mais importante

O mais importante acompanhando projetos usando o Oragon.RabbitMQ é a capacidade de entregar um fluxo padronizado e uniforme, sem precisar tocar em tão baixo nível no AMQP/RabbitMQ.Client, permitindo consumir filas como se fossem minimal API’s.

Ao eliminar o boilerplate, adotando uma política rígida de ack, nack e reject que não suje nem mascare a realidade no dashboard e métricas do RabbitMQ, torna a vida mais fácil, mais simples.

Nem tudo são flores

Um erro grave no fluxo de inicialização dos consumidores, produzia um fire and forget no start do consumer, mascarando erros que fossem desse início da jornada. Cenário não tão comum, mas fácil de acontecer quando você está “mudando tudo” (exchanges, binds, filas etc) que era um dos cenários de cliente.

Novas demandas

Nesse momento, tenho uma demanda exótica que consiste em uma fila de controle usada para receber nomes de filas que precisam ser atendidas por uma janela limitada de tempo, como uma fila de atenção, uma implementação similar à que sistema operacional usa para que seu processador consiga atender mais processos e threads do que cores disponíveis.

Para o Oragon.RabbitMQ a demanda é permitir subir e parar dinamicamente o consumo de uma fila, trocar a fila alvo e continuar o ciclo.

https://github.com/luizcarlosfaria/Oragon.RabbitMQ

Separar seu núcleo de negócio das camadas tecnológicas não é sobre a adoção de DDD, embora possa tirar proveito de…

É sobre clareza, fluidez e inteligência de arquitetura. Ao isolar o core da aplicação — e uso “core” propositalmente para não usar o termo “domínio” — você está tomando uma decisão consciente de reduzir acoplamento, minimizar a carga cognitiva e facilitar a evolução do sistema.

Hexagonal não é sobre a possibilidade de trocar tecnologias como banco de dados ou frameworks web. É sobre não misturar alhos com bugalhos.

Quando se mantém o coração da aplicação alheio às tecnologias de entrada e saída, cria-se um terreno sólido para sustentação e adaptação futuras. Embora não pareça intuitivo, reduz a complexidade.

Não é sobre DDD, é sobre boas práticas fundamentais

Um equívoco recorrente é presumir que a adoção de uma arquitetura hexagonal ou de serviços agnósticos exige obrigatoriamente a implementação de DDD (Domain-Driven Design). Embora DDD e Hexagonal compartilhem ideais como separação de responsabilidades e foco no domínio de negócio, não há dependência entre eles. A arquitetura hexagonal pode (e deve) ser usada em qualquer cenário que exija organização, desacoplamento e manutenibilidade, independentemente da complexidade ou da presença de um domínio rico.

É totalmente possível — e frequentemente desejável — aplicar uma arquitetura limpa e desacoplada mesmo em sistemas com domínio simples ou centrados em orquestração. Você não precisa de agregados, entidades ricas ou repositórios complexos para justificar a escolha por Port and Adapters ou Agnostic Services.

Basta querer:

• evoluir com liberdade
• testar com confiança
• manter com tranquilidade.

Ser manutenível exige esforço

Projetos que começam simples, com APIs REST sincrônicas, muitas vezes evoluem para demandas mais sofisticadas: cache, filas, streams, resiliência, escalabilidade. A transição natural de um fluxo sincrônico para um modelo assíncrono acontece muito antes de se atingir milhões de requisições por segundo. A necessidade de resiliência surge cedo, independente do tamanho do projeto. E é comum que nesses cenários, projetos fortemente acoplados e dependentes da camada web se tornem verdadeiros gargalos para evolução. Refatorar controladores que fazem tudo, reorganizar lógicas de negócio espalhadas entre middlewares, services e endpoints passa a ser uma tarefa onerosa e arriscada, dificultando a introdução de novas portas de entrada como filas ou streams.

E é justamente aqui que a arquitetura mostra mais uma vez seu valor. Se o seu core está amarrado diretamente à camada web, a introdução de novos mecanismos de comunicação exige refatoração pesada, arriscada e cara. Agora, se esse core for agnóstico — desacoplado, limpo e bem definido — novas portas podem ser conectadas com mínimo atrito, com o mínimo esforço.

Projetos bem pensados não são sobre previsão do futuro, mas sobre preparação inteligente para o inesperado. Como uma bicicleta com rodas encaixadas, não soldadas: você não sabe se vai precisar trocá-las, mas se precisar, não precisa descartar a bicicleta inteira.

E se você acha que esse é o argumento central, calma! O melhor está por vir.

Arquitetura não é luxo, é inteligência

Existe um preconceito comum contra a arquitetura hexagonal, como se fosse um “enlatado complexo” reservado a sistemas elitizados.

Antes de rejeitar uma abordagem por parecer sofisticada demais, reflita:

• quantas horas você ou seu time gastam para adaptar o sistema a uma nova necessidade?
• Quantos efeitos colaterais emergem de mudanças aparentemente simples?

E se a solução não for mais complexidade, mas mais organização e inteligência na separação de responsabilidades?

Agnostic Services criou uma nova era na forma como modelo software

Desde 2006, utilizo o conceito de Agnostic Services como base para construção de sistemas e posso afirmar, sem exageros, que essa decisão transformou profundamente minha maneira como enxergo, desenvolvo e entrego software.

A ideia central é simples: construir serviços que não conhecem o meio de entrada e não dependem da camada de transporte. São componentes de negócio autocontidos, testáveis, reaproveitáveis, que podem ser invocados por qualquer “porta”: seja uma API REST, uma fila RabbitMQ, um worker em background, uma requisição gRPC ou um job schedulado. Esse modelo traz uma liberdade arquitetural imensa e elimina a fricção para expansão.

Ao adotar Agnostic Services, passei a pensar e evoluir sistemas de forma mais estratégica. A entrega de novas features tornou-se mais fluida, e a capacidade de reagir às demandas se multiplicou, além de reduzir drasticamente a quantidade de bugs introduzidos por mudanças estruturais. Os times com quem trabalhei reclamaram muito, e reclamam até hoje, mas conseguiram escalar (aumentar quantidade de features) de suas soluções com menos dor e mais confiança.

Essa escolha, feita há quase duas décadas, moldou toda a minha abordagem profissional. E se hoje consigo construir soluções resilientes, adaptáveis e sustentáveis, muito disso se deve a essa base: serviços agnósticos e foco em separação real de responsabilidades.

Hexagonal e Agnostic Services: convergência de princípios

Ao observar com atenção, percebemos que a arquitetura Hexagonal e os Agnostic Services compartilham a mesma essência: manter o núcleo de negócio isolado das preocupações externas. Ambas as abordagens valorizam a independência do core em relação às tecnologias de transporte, infraestrutura ou comunicação.

A principal diferença está na perspectiva e na abrangência de suas propostas.

A arquitetura Hexagonal define uma estrutura arquitetural clara, e se aprofunda nos conceitos de portas e adaptadores delimitando as interações entre o mundo externo e o sistema. Enquanto Agnostic Services refere-se a serviços projetados para serem completamente independentes do meio de transporte, infraestrutura ou plataforma.

Enquanto Hexagonal fala de todo o isolamento completo do core, Agnostic Services se limita à preocupação em não contaminar os serviços com especificidades de tecnologias de exposição e seus protocolos, como Web API, HTTP, REST, gRPC, AMQP, RESP. O transporte é tratado como um detalhe de configuração externa.

Se por um lado a arquitetura Hexagonal define os limites do sistema, tanto em portas, quanto em adapters e como as integrações se conectam a ele, os Agnostic Services se preocupam apenas com as portas e a pureza e coesão das unidades internas.

Portanto, se você já adota arquitetura hexagonal, é provável que já faça uso de Agnostic Services, mas caso não, pode ser um passo menor, e talvez o próximo passo natural. E se você já pratica Agnostic Services, a arquitetura Hexagonal oferece um arcabouço que amplifica ainda mais seus benefícios.

Mas por que citar Agnostic Services em uma publicação cujo foco é Hexagonal e DDD?

A similaridade entre ambas as abordagens é enorme, partem dos mesmos princípios e são formas mais simples ou mais complexas de lidar com o mesmo problema: acoplamento entre chamada de negócio e tecnologias diversas. Esse acoplamento torna, muitas vezes, o negócio imperceptível dentro de fluxos basicamente tecnológicos.

A mistura entre regras de negócio a burocracia de componentes tecnológicos multiplicam a complexidade, dificultando a manutenção e aumenta principalmente a probabilidade de surgirem erros durante manutenções.

E aqui está meu ponto sobre o assunto: Embora tenha praticado pouco Hexagonal, pratico Agnostic Services há ao menos 18 anos, e suas semelhanças me permitem transplantar ideias de um universo para o outro, obviamente mantendo-me atento às diferenças.

Uma escolha que define o futuro

Arquiteturas que separam o [CORE, DOMÍNIO, NEGÓCIO] de tecnologias específicas, simplificam a evolução e geram diferencial na hora de manter, seja para mudar ou evoluir.

Você encontrará essas pistas em todos os meus projetos desde 2006, e o que ganhei com essa abordagem:

• Desafetos
• Stress
• Perda de Cabelo
• mas também:
  • Projetos mais bem delimitados.
  • Errar feio, é algo burocrático (precisa fazer bastante força).
  • Decisões difíceis, que demandariam muito esforço, passam a ser triviais.

Evoluções e restruturações de projetos sempre foi desafiador para clientes e consultores, entretanto em todos os casos, segui abordagens minimalistas que visavam consumir o mínimo de infraestrutura, para entregar profissionalismo aos projetos restruturados.

Meu PlayBook de refatoração conta com:

• observabilidade (comecei com ELK Stack, mas hoje privilegio LGTM)
• Cache (redis)
• Filas (rabbitmq)

esses elementos estão no topo das primeiras necessidades de todos os projetos que já fui chamado para restruturar. E não tenho históricos de fracassos ou grandes desafios em projetos de restruturação com esse PlayBook.

Mas o grande problema é que, na maior parte das vezes, aplicações centradas na web, em especial em Web Apis ou Web Apps, sem um core agnóstico, demandam muita reescrita e muita rearquitetura para permitir a adoção de filas, ou o uso de outros protocolos. O acoplamento cobra um preço muito alto.

Quando escolhi promover Agnostic Services à parte da baseline de arquitetura para meus projetos, (ou seja, exceto caso seja algo muito exótico (ainda não aconteceu), ele estará presente na arquitetura de qualquer projeto meu), ganhei projetos que ofereciam maior clareza, cada coisa no seu devido lugar.

A capacidade de reagir às necessidades cotidianas aumentou, e agora lidar com incertezas deixou de ser um grande problema estrutural. Mover fluxos que precisam de mais resiliência do que o oferecido pelo HTTP, saiu de uma escala de semanas ou meses, para uma escala de horas ou dias. Tudo porque ficou mais simples.

A separação rígida melhorou a testabilidade, aumentou o reaproveitamento de componentes, o que fortalece DRY, e reduziu a dificuldade de manter os projetos.

Mas o maior benefício, do ponto de vista de arquitetura, está em não precisar fazer falsas suposições hipotéticas. Não precisar chutar números com base em predições mediúnicas geradas a partir de números inventados.

Agora eu posso dizer um belo e singelo: Não sei e não me importa.
Porque agora eu posso dizer: Independente do que venha, reagimos rápido e antes que se torne um problema de fato!

Essa abordagem me permite reduzir a importância da decisão sobre filas ou http síncrono. No final das contas, “tanto faz” e, portanto, entrega a flexibilidade que eu preciso para não precisar tomar essa decisão e morrer abraçado a ela.

Muitas vezes só queremos não correr muito risco, e não precisar tomar decisões das quais não temos informações suficientes para uma previsão informada, só suposições com alta margem de erro.

Agnostic Services tem sido meu “seguro” contra incertezas, previsões erradas e suposições equivocadas. E Hexagonal Architecture/Ports and Adapters, pode herdar o mesmo status nos seus projetos, independente da adoção de DDD ou não.

É comum pensarmos em filas como recursos estáticos que fazem parte dos requisitos de funcionamento da aplicação, nascendo quando a aplicação é implantada em produção pela primeira vez e somente deixando de existir somente quando a aplicação é desativada ou substituída.

Hoje vamos abordar filas que possuem um ciclo de vida diferente, um ciclo de vida absolutamente curto, filas que podem durar de poucos milissegundos e semanas, e eventualmente até meses ou anos.

Não adianta torcer o nariz. Muitos aplicativos que estão no teu celular hoje fazem uso desse recurso em seus backends.

Desde 2013 usando e falando de RabbitMQ, ainda percebo certo incômodo quando falamos de filas não tradicionais.

Antes de avançarmos no ponto central do texto, preciso pontuar os tipos de filas, para entendermos exatamente do que estamos falando.

Tipos de Filas

No RabbitMQ temos 3 tipos de filas:

• Classic Queues
• Quorum Queues
• Streams*

Stream não é exatamente um tipo de fila, mas é apresentada no RabbitMQ como se fosse.
Seria um preciosismo desnecessário isolar streams, mas é importante entender que não são filas.

Classic queues

Classic queues são o tipo tradicional do RabbitMQ, compatíveis com todo o ecossistema (exchanges, DLX, TTL, plugins) e otimizadas para latência baixa e compatibilidade com clientes .NET (RabbitMQ.Client). Elas suportam filas duráveis e mirrors (federation/HA policies), mas o modelo de espelhamento clássico pode causar reordenação e penalidades em failover; são ideais para workloads gerais, baixa complexidade operacional e onde throughput moderado e integração imediata com features existentes são prioritários.

Quorum queues

Quorum queues são filas replicadas no cluster baseadas em Raft projetadas para alta disponibilidade e consistência forte, substituindo as mirrored queues para cargas críticas: tolerância a falhas mais previsível, menor risco de perda de mensagens e comportamento de eleição determinístico. Elas sacrificam um pouco de latência/throughput em comparação às classic queues em prol de durabilidade e segurança de dados — recomendadas para mensagens de missão crítica, billing, comandos financeiros ou onde a ordem e a persistência são requisitos firmes; funcionam bem com clientes .NET e suportam DLX/TTL, mas dimensionamento e tuning são necessários.

Streams

RabbitMQ Streams oferece um modelo baseado em log de alta performance e retenção longa, pensado para grandes volumes, leitura sequencial e replay (sem a limitação de consumo único por fila), aproximando-se de sistemas estilo Kafka. Streams garantem alto throughput, ordenação de partição e offset-based consumption, sendo ideais quando você precisa de retenção histórica, replay/consumer-groups e processamento de eventos em larga escala; possuem cliente diferenciado, mas podem usar a mesma estrutura de consumo AMQP existente e demandam arquitetura e operações diferentes (storage/retention tuning), por isso são a escolha certa quando ordenação, replay e escala são primordiais.

RabbitMQ Streams é uma estrutura de dados replicada persistente que pode realizar as mesmas tarefas que as filas: elas armazenam em buffer mensagens de produtores que são lidas por consumidores. No entanto, os fluxos diferem das filas em dois aspectos importantes:

• Como as mensagens são armazenadas
• Como as mensagens são consumidas.

Filas de Longa duração – O ciclo de vida padrão

O ciclo de vida mais comum adotado para filas no RabbitMQ é o de longa duração, que consiste em filas que existem durante toda a vida da aplicação.

Esse é o tipo de fila mais usado, mais comum, e é o que você precisa conhecer primeiro.
Os demais ciclos de vida são secundários.

Esse tipo de ciclo de vida das filas é típico em sistemas de todos os tipos, não há demérito nem perdas em sua utilização. Ele é o mais usado, pois atende aos mais vastos casos de uso, além de ser o ciclo de vida mais simples, mais fácil de ser implementado e o primeiro a ser ensinado.

Filas efêmeras

Filas de longa duração são ótimas para a maioria dos workloads. Entretanto, uma fila com múltiplos consumidores não permite determinar/forçar o envio para um consumidor específico. Não temos a capacidade de determinar para qual consumidor uma mensagem deve ser entregue.

E há um número substancial de casos de uso em que se faz necessário fazer esse roteamento avançado.

IoT

Em um cenário de IoT o dispositivo geralmente envia mensagens para uma fila de longa duração, entretanto, para receber mensagens, o dispositivo precisa ter uma fila própria.

Essa fila pode durar enquanto o dispositivo existir, sobrevivendo aos restarts do dispositivo, ou pode durar apenas enquanto o dispositivo estiver conectado ao RabbitMQ.

Ambas as abordagens são válidas e possuem prós e contras.

RPC

Em um fluxo RPC (Request / Response) que use filas, temos a demanda de criação de uma fila a cada request. Quem recebe esse request, em geral, são filas de longa duração, mas o Response é entregue em uma fila que foi criada dinamicamente e essa fila dura apenas alguns milissegundos, poucos segundos ou poucos minutos.

Para implementar RPC você precisa seguir regras estritas e rígidas, aqui exemplifico o server dessa relação:

1. Uma fila de longa duração é previamente criada.
2. Um ou múltiplos consumidores começam a consumir essa fila para atender os requests que chegarem.
3. Esses consumidores são implementados de forma que, além do body, também farão a leitura dos cabeçalhos AMQP da mensagem em busca do cabeçalho ReplyTo. Esse cabeçalho informa para o consumidor, qual o endereço AMQP para envio do Response.
4. Cada Request recebido, o consumidor processará a mensagem e, ao final, enviará o Response para o endereço AMQP contido na propriedade ReplyTo do Request.

Para esse fluxo ganhar vida o client dessa relação tem obrigações também:

1. Antes de enviar o Request, o client deve solicitar ao RabbitMQ uma fila anônima que será responsável por receber o Response.
2. O RabbitMQ deve retornar uma fila com um nome.
3. Antes de publicar a mensagem na fila do server, o cliente deve adicionar um cabeçalho ReplyTo na mensagem, informando qual o endereço AMQP da fila de resposta.
4. O cliente precisa parar a thread em que está em execução e aguardar o Response na fila anônima, consumindo essa fila.
5. Após um timeout ou a chegada da resposta, a fila anônima deve ser apagada, e o processamento que estava parado deve continuar com a resposta recebida.

Eu já abordei RPC aqui em “RPC sob AMQP seduz enquanto mata… sua implantação de mensageria”

RPC sob AMQP seduz enquanto mata… sua implantação de mensageria

RPC vs Two Way Async

A obrigatoriedade de aguardar a resposta para prosseguir com o processamento, bloqueando a thread, é característico do fluxo RPC, tornando-o semelhante a um Request HTTP, só que obviamente sob AMQP, usando filas.

O motivo para um Request HTTP não ser resiliente, independente de termos ou não a capacidade de retentativa, se dá por conta de não conseguirmos tolerar um downtime significativo. Em um fluxo que faça um Request HTTP temos um estado de memória, em uma thread, e em caso de falha nesse processo, temos algum tempo para recuperar a operação, mas esse tempo não é indefinido.

Uma desconexão de um usuário, um crash do processo, uma falha de rede, qualquer coisa que faça a thread morrer, leva consigo aquele request. Uma queda de luz, um simples deploy, uma reorganização de instâncias da aplicação são tarefas capazes de tombar a thread que originou o Request que estava em andamento, fazendo-o se perder.

Aliás, um dos meios de entregar resiliência para esse
fluxo consiste em englobá-lo em um consumo de fila.

O ponto é que o fluxo RPC não é resiliente porque precisa do Response na mesma thread que fez o Request, e eventualmente essa thread pode não existir mais, perdendo o estado anterior e talvez sequer recebendo a resposta.

Da mesma forma que um Request HTTP não é resiliente, por conta da necessidade de aguardar uma resposta síncrona, o fluxo de RPC AMQP também não é resiliente pelo mesmo motivo.

Então, sempre que possível, evite RPC.

Em muitos cenários não precisamos realmente aguardar essa resposta na mesma thread que originou o Request. Podemos, inclusive, quebrar o fluxo em duas etapas:

• na primeira, o processo termina com o envio do pedido
• na segunda, ele é retomado apenas quando a resposta chega.

Nesse modelo, em vez de um fluxo Request/Response, temos dois Requests independentes, que se conectam de forma assíncrona.

Esse é um fluxo resiliente!

Esse fluxo é baseado em 2 filas de longa duração, o que o torna mais fácil, mais eficiente e de quebra: Resiliente.

É importante evitar a adoção de RPC, porque fluxos RPC não são resilientes.

RPC só ganha resiliência, com a adoção de um garantidor que possa englobar a operação toda, como a adoção de filas.

Dê preferência para Two Way Async, com filas de request de longa duração.

Chat Server

Imagine que você tem um servidor de chat, são múltiplas instâncias do servidor. Cada cliente se conecta a uma instância do seu servidor via WebSocket. Isso produz o cenário onde as pessoas que participam de uma sala ou grupo podem estar conectadas em instâncias diferentes. Dado o volume de usuários e o limite de conexões WebSocket seu servidor escala dinamicamente criando mais instâncias do server.

O problema é que muitas vezes múltiplas instâncias precisam receber a mesma mensagem, é aqui que uma fila só não atende, pois uma fila não tem a capacidade de entregar a mesma mensagem para múltiplos consumidores.

Ao mesmo tempo, há a necessidade de assegurar que as mensagens só serão encaminhadas para instâncias que possuem usuários interessados, caso contrário será necessário publicar tudo para todas as instâncias, o que gera um flood desnecessário e ineficiente.

Nesse cenário, temos uma fila por instância do server.

Na inicialização de uma nova instância do server, sua fila de trabalho é criada e quando a instância morre, sua fila morre junto.

Não se preocupe com perda de mensagens, há tratamento adequado, porém chato, que usa desativação de binding, dead letters etc para evitar que a exclusão cause perda de mensagns.

A regra de ouro

Toda vez que uma mensagem precisa ser endereçada:

• A um consumidor específico, entre muitos.
• Ou vários consumidores simultaneamente.

Temos a necessidade de uma topologia diferente do padrão, e começamos a pensar em filas por consumidor.

Entendendo Filas por Consumidor

Fila por consumidor é uma topologia onde cada consumidor presente em um determinado fluxo possui sua própria fila de trabalho, não compartilhando essa fila com outros consumidores.

Ao lidar com esse tipo de fluxo, precisamos considerar algumas coisas:

• O consumidor (e sua fila) pode não estar mais disponível no momento em que enviamos uma mensagem para ele. O par de consumidor e fila podem ter morrido.
• A morte do consumidor pode acontecer enquanto sua fila de trabalho ainda não foi inteiramente consumida.

Assim, temos de nos preocupar tanto com o roteamento para filas que não existem mais, quanto como lidar com as mensagens não processadas quando uma fila é deletada.

Esses dois novos cenários se apresentam diante desse novo fluxo e temos mecanismos sofisticados presentes na plataforma para lidar com isso.

Alternate Exchange

As exchanges possuem um atribuido “alternate-exchange”. É uma forma elegante e robusta de lidar com mensagens não roteáveis no momento da publicação.

Em vez de deixar a mensagem ser descartada quando nenhum binding corresponde ao routing key, o broker encaminha essa mensagem automaticamente para uma exchange alternativa (“fallback”) definida como argumento da exchange original. Isso oferece uma trajetória determinística para captura, auditoria ou tratamento compensatório sem depender do flag mandatory do publisher ou de lógica de client-side.

Como funciona

• É um argumento da exchange: “alternate-exchange” => “<nome-da-exchange>” no momento da declaração de uma exchange.
• Aciona-se quando uma mensagem chega a uma exchange e nenhum queue binding a essa exchange corresponde ao routing key.
• O broker repassa a mensagem para a alternate exchange preservando headers, propriedades e routing key (ou seja, a mensagem chega intacta ao fallback).
• A alternate exchange processa a mensagem como uma publicação normal: geralmente fanout, e pode ter suas próprias filas, DLX, TTL etc.
• Se a alternate exchange também não conseguir roteá-la (e não tiver outra AE), a mensagem será descartada — portanto é importante projetar a AE para garantir captura (por exemplo, um fanout para uma fila de auditoria).

Diferenças importantes vs outras estratégias

• vs mandatory + basic.return: mandatory instrui o broker a retornar a mensagem ao publisher quando não roteável; isso exige que o publisher trate o retorno e mantenha conexão síncrona. Alternate exchange remove essa obrigatoriedade do publisher e delega o fallback ao broker.
• vs dead-letter exchange (DLX): DLX trata mensagens que já entraram em uma fila e foram rejeitadas, expiraram ou atingiram max-length. Alternate exchange atua no momento da publicação, antes mesmo de qualquer fila existir.
• vs publisher confirms: confirms garantem que o broker recebeu a mensagem; não dizem nada sobre roteabilidade — AE lida especificamente com mensagens não roteáveis.

Com Alternate Exchange conseguimos fazer com que, caso um consumidor não exista, a mensagem possa ser encaminhada para uma fila de controle e possa ser reprocessada por outro mecanismo, ou ainda possa seguir outro fluxo.

Dead Letter

Dead-lettering é o mecanismo padrão para capturar mensagens que não puderam ser processadas normalmente dentro de uma fila — seja por rejeição explícita, expiração ou limites de tamanho ou até PELA EXCLUSÃO DA FILA. O padrão permite redirecionar essas mensagens para uma exchange de tratamento (dead-letter exchange, DLX) e, tipicamente, para uma dead-letter queue (DLQ) onde serão inspeccionadas, reprocessadas ou descartadas de forma controlada.

Como funciona

• Configuração: você declara uma fila com argumentos: x-dead-letter-exchange = “<nome-dlx>” e opcionalmente x-dead-letter-routing-key = “<rk>”.
• Gatilhos de dead-letter:
  • consumer chama basic.reject/basic.nack com requeue=false;
  • mensagem expira por TTL (x-message-ttl em fila ou header expiration);
  • fila atinge max-length/max-length-bytes (mensagens que excederem são dead-lettered).
  • fila é deletada
• Quando dead-lettered, o broker publica a mensagem na DLX como uma nova publicação. RabbitMQ acrescenta/atualiza o header x-death (contendo contagem, motivo, queue original, exchange original, timestamp) para rastrear histórico de rejeições.

Conectando os pontos

Essas abordagens fazem uso não somente das operações QueueDeclareAsync e QueueBindAsync, mas também fazem uso de parâmetros pouco discutidos das filas. Esses casos de uso nos fazem começar a pensar nas flags:

• durable: Essa fila deve sobreviver à reinicialização do broker?
• exclusive: O uso desta fila deve ser limitado à conexão declarada? Essa fila será excluída quando a conexão declarada for encerrada.
• autoDelete: Essa fila deve ser excluída automaticamente quando seu último consumidor (se houver) cancelar a assinatura?

Esses parâmetros começam a ganhar vida e fazer sentido com esses tipos de caso de uso e abordagem.

De um lado, eliminando esforço manual de manutenção (exclusão) de filas quando elas não são mais úteis. Por outro asseguram que o consumo físico por múltiplos consumidores de diferentes conexões não será permitido, eliminando a necessidade de controle adicional.

Quem deve criar filas, exchanges e binds?

É super comum encontrar times discutindo de quem é a responsabilidade de criar filas, exchanges e binds, ou seja, a topologia de objetos do RabbitMQ.

É por conta dessa segunda camada de complexidade, quando nos deparamos com casos de uso mais complexos, que não há uma decisão que seja universalmente correta.

A depender das estratégias, temos demandas diferentes que precisam de abordagens diferentes.

A topologia no RabbitMQ é decisão de arquitetura, a depender da estratégia, essa criação pode, sim, ser uma tarefa de Infra ou Ops, ou DevOps, mas há casos de uso em que claramente é o código da aplicação quem tem de fazê-lo. E, em alguns casos, por operação, como descrito no case de RPC.

Assim, é importante entender que o correto a ser adotado é aquilo que traga a menor carga cognitiva, menor demanda por operação e manutenção e esforço diário.

Sem entender quais padrões serão adotados, não é possível determinar de quem é a responsabilidade, portanto, qualquer tentativa de atribuir um responsável, sem que saibamos quais padrões usaremos, seria inútil.

A distância entre o overview e o mundo real é muito grande, e por isso é importante aprofundar no entendimento dos padrões ao redor de Mensageria em especial do RabbitMQ, pois geralmente muitas das respostas simplesmente aparecem ao entender o comportamento.

Acredito que fazer provas de conceito seja uma forma muito eficiente de estudar, mesmo que você não tenha demanda para esse tipo de topologia.

Nos últimos 3 anos me deparei pela primeira vez com demandas que endereçaram um tipo específico de topologia que havia estudado há quase 10 anos e que ficaram engavetados esse tempo todo.

Somente conhecendo, mesmo que não implementando de fato, foi possível adotá-los anos mais tarde, mas porque o conceito estava devidamente absorvido, e muitas vezes isso demanda tempo.

Acima mostro algumas configurações necessárias para lidar com ordenação determinística em filas efêmeras. Essa quantidade de flags é uma demonstração de que quando saímos do overview, o básico feijão com arroz já não atende mais. E para conseguir entregar esses cenários avançados, é preciso ir mais fundo.

Esse é um tema recorrente quando o assunto é microsserviços e não há resposta satisfatória.
A resposta para essa pergunta sempre será uma pedra no calcanhar.

Ao primeiro olhar, parece exagero, um tipo de purismo desnecessário. Principalmente por inviabilizar algumas facilidades presentes em monolitos que compartilham seus objetos (tabelas e views) de banco e fazem integração entre serviços via esses objetos.

Sim, esse é um tema espinhoso, difícil de engolir e por isso vamos abordá-lo hoje.

No nosso discord privado do Cloud Native .NET e Mensageria .NET temos um fórum para os alunos e eventualmente surgem algumas perguntas memoráveis.

Essa foi uma delas do Rodrigo:

Rodrigo Alves de Oliveira

Então, vamos à resposta:

A gente não pode olhar para essa demanda de isolamento sem entender seu motivo. O argumento central ou os argumentos centrais que produzem essa demanda.

Sem isso, podemos sabotar a estratégia.

O isolamento dos objetos de banco de um microsserviço se dá para que, somente o próprio microsserviço produza dependência com esses objetos. Ou seja, somente o próprio microsserviço sabe quais são as tabelas, colunas e relacionamentos.

O motivo para isso, é assegurar que o microsserviço poderá MUDAR essas estruturas para atender novas demandas. Sem gerar impacto a ninguém. Basta manter o contrato nas API’s lá na camada mais alta, que todo mundo que depende dele, não saberá e não precisará saber se e caso uma coluna nova for adicionada, ou uma coluna virar uma tabela inteira nova.

Quando movemos o nível da dependência para a API, temos a chance de fazer mudanças internas. Como fragmentar o banco em um banco relacional com dados complementares e históricos em bancos não relacionais.

Tudo se torna possível, e o mais importante é, antes de mais nada, evitar os puxadinhos que miram em “não fazer o que precisava ser feito para não impactar outros serviços que dependem das minhas tabelas.“

Sabe a tal independência do Microsserviço?
A capacidade de ter um roadmap próprio, sem afetar outros microsserviços?
A capacidade de reestruturar para atender novas demandas sem impactar suas dependências?
É sobre isso! É sobre o alicerce, sobre o pilar central da necessidade de microsserviços:
Entrega de negócio rápida independente dos demais serviços.
Se você entender isso, aceitar isso, pode rasgar uma pá de livros e deletar dos favoritos mais de 90% dos conteúdos em texto e vídeo sobre microsserviços.

Agora, com esse isolamento, você tem a chance de fazer o certo.

Aí você pode dizer: mas fulano depende desse dado, nessa estrutura. Ok, crie uma API compatível com o formato antigo. Dificilmente o dado deixou de existir, ele geralmente muda de estrutura interna de armazenamento. Mas não se perde.

Esse isolamento permite que quem estiver evoluindo o microsserviço possa pensar em fazer o correto e necessário em vez de fazer o que dá para ser feito, dada as dependências de baixo nível.

Em última análise, tem relação com evitar fazer gambiarra. Evitar mudanças difíceis, só porque alguém depende de algo que é interno ao meu microsserviço.

Dito isso, não importa como você faça:

• Desde que sejam connectionstrings diferentes, uma para cada microsserviço.
• Desde que seja fisicamente impossível (no ambiente de desenvolvimento local) criar um simples join entre tabelas de 2 microsserviços,
• Desde que seja impossível fazer uma única transação que englobe operações em 2 microsserviços.

Se você consegue usar um só database, com um só schema, mas consegue via usuários e permissões de banco, não deixar o dev fazer sequer um JOIN que ultrapasse os limites do próprio microsserviço, já atende!

Eu particularmente não gosto dessa abordagem e desaconselho uma abordagem tão frágil.

Considero essa abordagem algo como amarrar cachorro com linguiça. Na máquina do dev, com poderes ilimitados, se o dev for minimamente descolado, se ele pode, ele vai criar um terceiro usuário na máquina dele, só para poder fazer esse join, só para ficar mais fácil.

Porque, na cabeça dele, é “incoerente” não poder fazer esse join se as tabelas que ele precisa estiverem lado-a-lado, no mesmo schema, ou no mesmo database.

Então, minha estratégia se pauta em ISOLAR no mínimo por database (na mesma instância de servidor) em DEV. Isso me assegura que esses joins não sejam sequer possíveis tecnicamente (no postgres) https://wiki.postgresql.org/wiki/FAQ#How_do_I_perform_queries_using_multiple_databases.3FFAQ.

Assim, se eu consigo assegurar que em dev, ele respeitou esse isolamento, eu tenho todos os patterns disponíveis em produção e usar qualquer um deles vira uma decisão de deploy, de infra.

Se ele respeitar essa premissa de isolamento,

Podemos usar 1 só database com 1 só schema, (desde que não haja conflito).
Assim como podemos usar um schema por microsserviço.
Ou podemos usar databases por microsserviço.
e, em última análise, até instâncias de servidor por microsserviço.
E essa decisão vira uma decisão de infra.

Agora vamos falar de gosto. Na escala temos:

• Mesmo Server / Mesmo Database/ Mesmo Schema
• Mesmo Server / Mesmo Database/ Schema diferente
• Mesmo Server / Database Diferente
• Server Diferente

Olhando para o postgres, sql server e mysql tendo a optar por Database-per-service.

Um único servidor postgres com vários databases, onde cada database tem um único dono, pertence a um único microsserviço. E malandramente, com usuários de banco diferentes com senhas diferentes para produzir connectionstrings diferentes, de forma que não seja possível ferir o isolamento.

Sigo a regra de que: O certo tem de ser fácil, e o errado tem de ser fisicamente impossível.

B) A pergunta que você precisa se fazer para saber se tem um microsserviço mesmo é:

Se mantivermos os contratos das API’s (endpoints e estruturas de dados, eventos e comandos) ainda assim consigo evoluir meu microsserviço (criando novas tabelas e mudando as anteriores) sem quebrar ninguém?

Porque no final do dia é isso que importa.

Assegurar que se uma gambiarra for feita, se um puxadinho for feito visando não atrapalhar as dependências é por um erro individual e pessoal de uma pessoa e não por uma situação mais ampla em que a arquitetura empurrou o dev. No final do dia é sobre fazer o que precisa ser feito, em vez de fazer o que dá porque há dependências.

Todas as estratégias que isolem essas mudanças pelo aspecto funcional são válidas.

Mas tem questões práticas que precisamos nos atentar.

Se você usa migrations, lembre-se que Migrations possui a necessidade de uma tabela de controle de versão. Portanto, Private-tables-per-service vai exigir configuração adicional para criar múltiplas tabelas de controle no mesmo schema de banco, uma para cada microsserviço.

Private-tables-per-service inevitavelmente fisicamente permite que faça um join que atravesse múltiplos microsserviços. Aqui temos um problema adicional. Se você implementar uma política de dogfooding onde os devs partilham do dia-a-dia de produção provando da própria comida de cachorro, se ele usa esse tipo de JOIN para validações, ele vai atrasar o máximo possível para realizar uma eventual fragmentação em múltiplos data stores diferentes.

Só quando for impossível lidar com essas estruturas em um só banco, ele vai cogitar essa mudança. Enquanto isso, será o cara que defenderá com unhas e dentes que a abordagem é desnecessária. Principalmente por tirar dele a simplicidade do troubleshooting simplificado.

Ou seja, se você deixar que alguém possa se acomodar com um viés monolítico, esse comodismo pode custar caro.

Então eu nunca deixaria uma oportunidade de fazer esse JOIN fisicamente, porque quando você está distraído, quando as coisas estão funcionando de boa. Quando você está confortável e feliz com o resultado, é quando você baixa a guarda e reduz a tensão, e é quando tudo desmorona porque alguém tomou uma decisão estúpida. Eu tomaria necessariamente a decisão mais barata que inviabilizasse esse acoplamento.

Então, eu tendo a usar database dentro do mesmo servidor. Essa é a opção que me permite mover com facilidade em caso de crescimento. E gera independência para inclusive ter parâmetros diferentes de database para database. O que me permite ter um controle bem interessante. Mesmo que use um mesmo database server.

Respondido?

(fiz algumas adaptações na escrita)

Nesse contexto, a capacidade de simular gargalos de I/O torna-se uma ferramenta poderosa para validar a resiliência, eficiência e tolerância a falhas da sua aplicação. Felizmente, o Docker oferece mecanismos para isso, permitindo configurar limites finos de I/O em containers.

Não é todo dia que você é exposto a esse tipo de necessidade, como fui recentemente. Entretanto, a capacidade de ter à mão, algo tão simples quanto poderoso, permite validar e experimentar problemas previsíveis, muito antes de sequer contratar uma infra em produção.

É mais do que validar um setup, é sobre entregar previsibilidade arquietural.

Vamos explorar como isso pode ser feito, por que é útil e quais problemas essa abordagem ajuda a evitar.

Por que simular limitações de I/O?

Sistemas modernos frequentemente dependem de bancos de dados, message brokers, object storage e sistemas de arquivos em rede. Em ambientes de produção, esses recursos estão sujeitos a:

• Sobrecarga de IOPS (Input/Output Operations per Second);
• Baixa largura de banda de leitura/escrita;
• Latência provocada por armazenamento remoto ou compartilhado;
• Comportamentos erráticos em períodos de alta concorrência.

Existe um fenômeno que não é isolado nem tão raro, em que certos tipos de ambiente/empresa onde os notebooks e/ou desktops dos desenvolvedores podem ter vezes mais capacidade de I/O, CPU e memória do que um servidor de produção.

Me recordo de uma compra de 2023 onde fiz compra de SSD para o meu desktop de desenvolvimento, focando quase que exclusivamente em throughput.

Por mais que o desktop possa estar sub um sistema operacional “pesado”, com várias instâncias de visual studio abertas, e vários npm installs dragando I/O preenchendo node_modules com toda a internet, ainda consigo ter uma máquina responsiva para fazer isso tudo enquanto gravo uma aula, um vídeo para o YouTube ou algo assim.

Esse é o meu caso de uso.

Outros compram hardware eficiente por puro prazer, satisfação, ou mesmo para jogar, já que alguns usam o mesmo equipamento para essa finalidade.

Há muitos motivos para existir essa discrepância entre o desktop/notebook do desenvolvedor e o ambiente de produção e, portanto, precisamos tomar algum cuidado se não estivermos atentos ao quanto de hardware estamos entregando para os nossos servidores produtivos.

Por isso, simular restrições é importante.

Ao simular essas restrições longe do ambiente produtivo conseguimos:

• Avaliar comportamento da aplicação sob stress realista;
• Validar estratégias de retry, timeout e fallback;
• Identificar gargalos arquiteturais ocultos;
• Prevenir falhas críticas antes que elas atinjam produção.

Mas como docker pode nos ajudar com isso?

Docker e controle de I/O: os parâmetros que importam

O Docker permite impor limites de I/O por container usando parâmetros específicos no momento de execução. São eles:

--device-read-bps="<dispositivo>:<limite>"

Limita a taxa de leitura (em bytes por segundo) de um determinado dispositivo.

Exemplo:

#!/bin/sh

docker run --device-read-bps /dev/sda:10mb ubuntu

Este comando limita o container a ler no máximo 10 MB/s do dispositivo /dev/sda.

--device-write-bps="<dispositivo>:<limite>"

Controla o throughput de escrita no dispositivo.

Exemplo:

#!/bin/sh

docker run --device-write-bps /dev/sda:5mb ubuntu

Limita a escrita a 5 MB/s, útil para simular discos lentos ou saturados.

--device-read-iops="<dispositivo>:<limite>"

Impõe limite ao número de operações de leitura por segundo (IOPS).

Exemplo:

#!/bin/sh

docker run --device-read-iops /dev/sda:100 ubuntu

Aqui, o container poderá fazer no máximo 100 operações de leitura por segundo.

--device-write-iops="<dispositivo>:<limite>"

Faz o mesmo para escrita, restringindo a IOPS de gravação.

Exemplo:

#!/bin/sh

docker run --device-write-iops /dev/sda:50 ubuntu

Casos de uso reais em ambientes .NET

1. Testes com EF Core sob disco lento

Simule um ambiente de banco de dados em disco mecânico para validar o comportamento de consultas N+1, migrações e cenários onde o DbContext.SaveChanges() leva segundos para concluir.

2. Simulação de message brokers com I/O degradado

Ao limitar o throughput do volume onde o RabbitMQ ou Kafka armazena os logs de mensagens, é possível validar o comportamento do seu sistema sob latência, inclusive testando dead-letter queues e redelivery policies.

2. Simulação de serviços de armazenamento baseados em Lucene

ElasticSearch ou Solr podem ser gravemente afetados pela falta de I/O do disco, podendo causar até, em última análise, perdas financeiras, quando mal provisionados. Já presenciei uma gravação consumir 1 segundo inteiro em uma chamada de API.

3. Serviços que realizam processamento em lote

Serviços de ETL ou processamento batch que dependem de grandes volumes de leitura e escrita podem ser testados quanto à degradação de performance — inclusive validando alertas de observabilidade com Prometheus e Grafana.

Benefícios: o que essa abordagem evita

• Falhas em produção causadas por ambientes otimizados de desenvolvimento (SSD local vs. disco remoto);
• Code paths não exercitados, como retry policies, circuit breakers e timeouts mal configurados;
• Impressão falsa de performance por testes realizados apenas em condições ideais;
• Problemas de throughput que só aparecem com carga real e concorrência.

O que é possível validar antes de chegar à produção

Ambientes controlados permitem medir:

• Tempo médio de resposta em cenários com I/O degradado;
• Eficiência do uso de cache (Redis, MemoryCache, etc);
• Resiliência do sistema a falhas intermitentes de armazenamento;
• Capacidade de fallback ou uso de circuit breakers (ex: Polly no .NET);
• Alertas reais de latência e disponibilidade (observabilidade realista).

Até que ponto vale a pena?

A tabela abaixo foi gerada pelo chatGPT (mas temos a doc aqui).

Esses números podem servir de base para testes alinhados a ambientes produtivos. Caso eles não digam muita coisa, entenda o custo de cada um, estamos falando de uma variação muito significativa.

Se compararmos a um bom SSD, não tão incomum em um desktop de desenvolvimento, vemos o valor absurdo pago a depender do cloud provider.

Entregar na cloud, números comparáveis com esses custa muito caro, portanto, testar seus recursos e aplicações com base nesses números permite entender o que funciona, o que não funciona e qual o risco.

Conclusão: simular é prevenir

Testar sob limitações de I/O é uma prática essencial para aplicações críticas, especialmente em sistemas distribuídos. Com Docker, é possível incorporar essa etapa à sua esteira de qualidade sem depender de hardware específico.

Essa abordagem vai além do “testa que funciona”: ela antecipa o imprevisível e prepara o sistema para o pior cenário possível.

Use os parâmetros de limitação de I/O do Docker como parte do seu arsenal de testes — porque em produção, o inesperado não perdoa.

PS: Não dá para simular algo que seu hardware sequer entrega.

O óbvio precisa ser dito.

Se seu desktop não tem hardware suficiente para esse teste, se não tem um hardware mais eficiente que o servidor na cloud. Então não há muito a ser feito.

Ainda não validei, mas um teste futuro que quero fazer é sob o tmpfs, criando um volume que em vez de usar disco, utiliza memória RAM.

Dessa forma seria possível entregar um file system mais rápido do que qualquer um dos seus discos ou ssd’s.

E conexões de longa duração merecem muito mais respeito.

O erro de subestimar o gRPC

Quantos projetos gRPC já fracassaram por partir da premissa equivocada de que, por usar HTTP/2, gRPC é apenas uma evolução natural do REST? A diferença fundamental é que o HTTP/2 habilita conexões multiplexadas e persistentes, o que muda drasticamente a forma como devemos gerenciar recursos, lidar com timeouts e projetar a resiliência do sistema.

Tratar gRPC como um simples request/response stateless é ignorar toda a complexidade (e o poder) de um canal persistente. Isso leva a falhas silenciosas, gargalos e uma gestão de recursos ineficiente.

Websockets e a armadilha do heartbeat

A história se repete com Websockets. Quantas aplicações mantêm milhares de conexões quase inativas, sustentadas apenas por heartbeats? Cada conexão viva consome memória, sockets e ciclos de CPU, mesmo que esteja ociosa. O resultado? Uma necessidade artificial de escalar horizontalmente, adicionando dúzias de máquinas apenas para manter um pool de conexões abertas.

O custo oculto das conexões long-lived mal gerenciadas é real e afeta diretamente a escalabilidade e a sustentabilidade financeira da solução.

Alternância dinâmica entre WebSocket e polling

Uma abordagem possível e adotada por sistemas modernos é a capacidade de alternar dinamicamente entre WebSocket e HTTP polling, de acordo com a demanda do sistema. Em cenários de baixa atividade ou inatividade temporária, adotar polling com intervalos inteligentes permite liberar recursos do servidor sem comprometer a funcionalidade. Esse mecanismo de fallback reduz drasticamente o consumo de memória, threads e sockets, especialmente quando milhares de clientes mantêm conexões que transmitem dados com pouca ou nenhuma frequência.

Por outro lado, quando o tráfego se intensifica ou a aplicação exige interações em tempo real — como notificações instantâneas, atualizações de dashboards ou interações colaborativas — a migração para WebSockets pode ser feita sob demanda, reestabelecendo o canal persistente de forma transparente para o usuário. Asssim a aplicação só volta a consumir conexões stateful quando realmente necessário.

Como dizia Milton Friedman, não existe almoço grátis! Não mesmo!

Essa transição inteligente exige um bom design no cliente e no servidor, além de métricas claras para guiar a troca entre os modos. Mais que uma otimização, esse tipo de adaptabilidade pode ser a chave para escalar com eficiência e previsibilidade em ambientes com picos e vales de uso.

Conexões stateful exigem testes integrados

Diferente de uma chamada stateless que é aberta e fechada em milissegundos, uma conexão stateful permanece viva, muitas vezes por minutos ou horas. Isso exige um entendimento profundo do ciclo de vida da conexão: como ela é aberta, mantida, recuperada após falhas e finalmente encerrada.

Testes integrados em cenários reais (incluindo falhas de rede, interrupções abruptas e reconexões) são essenciais para garantir que seu sistema não entre em estados inconsistentes ou consuma recursos indefinidamente.

TestContainers podem ajudar nessa jornada, tenho usado com sucesso para a implementação de testes integrados com Postgres e RabbitMQ, por exemplo.

A armadilha do consumo invisível de recursos

Conexões stateful consomem recursos continuamente: file descriptors, memória, CPU e slots de thread ou evento. Recursos limitado que, quando chegam ao seu limite produzem negação de serviço. Ou seja, demandam escala para que isso não ocorra. Se você não tem mecanismos de timeout, controle de conexões inativas, trocad e protocolo ou desconexão ativa, seu sistema inevitavelmente demandará escala precipitada, ou entrará em colapso sob carga.

Ao contrário do modelo stateless, onde cada interação é curta e previsível, as conexões persistentes criam um estado implícito no servidor. Isso limita drasticamente sua capacidade de escalar.

A complexidade da reconexão e do roteamento em ambientes orquestrados

Em ambientes baseados em containers, como Docker e Kubernetes, a expectativa de alta disponibilidade esconde frequentemente a complexidade envolvida na reconexão de clientes após falhas. Quando um pod morre ou um container é reiniciado, qualquer conexão stateful é perdida, exigindo que o cliente detecte a queda, implemente lógica de reconexão e restabeleça o estado — tudo isso sem afetar a experiência do usuário.

Além disso, mesmo com load balancers e service meshes sofisticados, como os baseados em Envoy, não há garantias de que o cliente será reconectado à mesma instância anterior, até porque ela pode nem existir mais. Para aplicações que mantêm estado local, como sessões em memória ou buffers de streaming, isso pode ser peculiarmente desafiador, gerando inconsistência, perda de dados ou necessidade de reprocessamento.

Projetar para esse cenário exige estratégia:

• adoção de stores distribuídos para estado (redis é uma solução possível)
• uso de sticky sessions (com moderação)
• e principalmente, preparar o cliente para falhas inevitáveis no ciclo de vida dos pods e containers.

A certeza que podemos ter é a de que falhará, portanto, precisamos tratar adequadamente esse comportamento esperado, previsível e natural de uma conexão stateful.

Conclusão

Conexões de longa duração oferecem vantagens significativas: baixa latência, bidirecionalidade e eficiência. Mas elas também trazem riscos sûtis, que se manifestam tardiamente em produção.

Ao lidar com sistemas distribuídos e de alto desempenho, precisamos projetar com consciência. Cada conexão é uma promessa de recursos alocados. E promessas não cumpridas, cedo ou tarde, cobram seu preço.

Esse post foi baseado em experiências recentes
em algumas das maiores instituições financeiras do país.

Mas como todo dado isolado, os benchmarks contam apenas parte da história. Os números são reais, mas o contexto em que esses números são obtidos está longe da realidade da maioria dos sistemas em produção. E é justamente aí que mora o problema.

Quando o assunto é desenvolvimento, em muitos desses testes, o cenário se resume a algo extremamente simplificado: processar uma string, retornar um JSON estático, ou calcular algo em memória — tudo isso sem envolver banco de dados, sem serialização real, sem cache, sem autenticação, sem concorrência real.

Esses benchmarks não refletem o mundo real.

O que acontece no mundo real?

No mundo real, um request HTTP passa por diversas camadas:

• Autenticação e autorização (muitas vezes com JWTs, que exigem criptografia)
• Desserialização do payload recebido
• Regras de negócio, que frequentemente acessam banco de dados ou serviços externos
• Escrita em cache ou leitura de cache (Redis, por exemplo)
• Log, tracing, métricas e demais elementos de observabilidade
• Processamento concorrente, locks e contenção

Tudo isso consome tempo — e não são microssegundos. Estamos falando de milissegundos, muitas vezes dezenas deles. Um simples acesso ao banco pode levar 5, 10, 20ms. Um serviço externo pode adicionar 100ms ou mais de latência.

Decidir adoção ou migração de uma tecnologia baseando-se em menchmarks sintéticos é como escolher um carro pela velocidade de abertura da porta do carona.

Os percentuais escondem os valores reais…

Se um framework A responde uma requisição simples em 400 microssegundos e o framework B em 800 microssegundos, isso pode parecer uma diferença substancial, afinal um é 100% mais lento que o outro, ou talvez você prefira pensar que um deles é 2 vezes mais rápido, certo?

Mas se a requisição real do seu sistema leva 120ms para ser processada por conta de chamadas externas, então a diferença entre A e B representa menos de 0,5% do tempo total. Ou seja, menos da metade de 1%.

Em uma relação desse tipo temos:

Uma substituição, em nome do desempenho, pode parecer justificável ao olhar desatento, mas seria como otimizar o tempo de abrir a porta do carro para ganhar desempenho em uma corrida de 10 horas. Sim, pode fazer diferença em cenários extremos e altamente otimizados. Mas para 99.9% dos sistemas em produção, isso é irrelevante.

Aqui nos deparamos com o dilema da relevância de tal mudança. Um ganho tão pequeno não justifica, de forma consistente, decisão alguma na maioria absoluta dos casos. Estamos diante de um ganho irrisório, marginal, ínfimo.

Então por isso não devemos mudar?

Você pode encontrar diversos outros argumentos válidos, faça o exercício de buscá-los. É possível e provável que encontre argumentos mais atraentes e que justifiquem uma mudança.

Respondendo à pergunta original, “Então por isso não devemos mudar?”, onde “isso” é um ganho de desempenho de menos de 0.5%, a resposta é simples: Não há plausibilidade em realizar mudanças quando o ganho é tão marginal.

O que realmente importa?

Sob a ótica de uma empresa com fins lucrativos, o que importa é o lucro.

E isso pode ser obtido otimizando e maximizando o consumo de recursos com mais eficiência, mas também com a redução de custo. Ou trazendo mais receita, algo que contribua na margem final.

Portanto:

• Latência total da requisição
  • Aumento da eficiência.
  • Aumento da percepção do seu usuário.
  • Redução de custos.
• Capacidade de escalar horizontalmente
  • Aumento da eficiência
  • Capacidade de atender mais clientes com custo otimizado para a demanda.
• Facilidade de observabilidade
  • Menor tempo até a descoberta de bugs
  • Menor tempo reprodução e de resolução de bugs.
  • Melhoria na percepção do usuário final
  • Permite ser proativo na correção de bugs
• Custo de manutenção
  • Redução de tempo para entregar novas features
  • Redução de tempo para corrigir bugs
  • Redução dos skills de contratação
• Confiabilidade e estabilidade
  • Redução do esforço de operações para suportar a aplicação.
  • Redução das interrupções nos times de desenvolvimento para correção de bugs.
  • Redução da frustração do cliente.
  • Aumento da percepção de qualidade pelo cliente.

Quando falamos de benefícios técnicos, precisamos ter em mente que queremos:

• Mais clientes.
• Por mais tempo.
• Pagando mais durante toda a vida dele no seu software.
• Gastando menos para produzir e manter o software e infraestrutura.

E muitas vezes, para que esses objetivos sejam alcançados, empresas fazem um zilhão de coisas para criar um ambiente legal para os devs, para contratar, para reter talentos e também seus clientes.

Entenda a regra do jogo, para entender quais são os melhores argumentos.

Conclusão

Benchmarks sintéticos servem para comparar aspectos específicos, mas não devem guiar decisões arquiteturais sem contexto.

No mundo real, a performance relevante é medida de ponta a ponta, em cenários reais, sob carga real.

Antes de trocar de framework por uma diferença de microssegundos ou nanosegundos, pergunte-se: qual será o ganho real? E o que vai realmente mover o ponteiro da performance no meu sistema?

Será que não há outros argumentos mais interessantes que foram ignorados?

No fim das contas, escolher um framework apenas por benchmarks é como escolher um carro olhando apenas o velocímetro, ignorando conforto, segurança, consumo e confiabilidade.

A performance importa, mas no contexto certo.

Sempre que podemos evitar, evitamos seu uso, mas e quando não podemos? Como podemos tratar ou mitigar esses prejuízos em desempenho?

Hoje vou apresentar uma abordagem que usei recentemente em um projeto recente.

Reflection e seus custos

O impacto do uso de Reflection no desempenho pode ser atribuído a diversos fatores, sendo os principais:

1. Sobrecarga Computacional e Latência: O uso de Reflection exige buscas dinâmicas por metadados no assembly, além de processos de validação de acesso e resolução dinâmica de métodos. Esse mecanismo pode ser entre 10 e 100 vezes mais lento do que chamadas diretas a métodos, o que pode impactar a responsividade da aplicação em cenários de alta concorrência.
2. Alocação Excessiva de Memória: Reflection frequentemente induz a criação de objetos temporários, principalmente ao utilizar Activator.CreateInstance para instanciar dinamicamente classes, o que resulta em maior pressão sobre o garbage collector e consequente degradação de desempenho.
3. Impedimentos à Otimização Just-In-Time (JIT): Métodos invocados via Reflection não são otimizados pelo compilador JIT, pois a inferência estática é impossibilitada. Como resultado, essas chamadas não aproveitam otimizações como inlining e caching de código compilado.
4. Redução da Capacidade de Diagnóstico e Debugging: Reflection pode tornar o código menos previsível, dificultando a rastreabilidade e depuração de erros, uma vez que falhas podem ocorrer apenas em tempo de execução e não serem capturadas pelo compilador.
5. Impacto na Segurança e Manutenção do Código: O uso excessivo de Reflection pode dificultar a manutenção do código, especialmente em equipes grandes, pois oculta dependências explícitas e torna a lógica de negócio mais difícil de compreender e auditar.

Se é tão ruim, por que não abolimos o uso de reflection?

Abolir é um termo muito duro para o problema, mas sim evitar o uso de reflection é uma estratégia que começou a ser adotada por volta de 2005 e é utilizada até hoje.

Evitamos reflection sempre que possível, como no caso que trago hoje para o exemplo:

As versões pré-lançamento do Oragon.RabbitMQ eram baseadas em lambdas com assinaturas pré-definidas, de forma que não precisava de reflection em momento algum. Forçar uma assinatura única, para evitar o uso de reflection, não era meu desejo, mas era o que dava para fazer para evitar reflection.

Somente em dezembro de 2024, em uma mentoria (não me lembro se foi com os alunos do Cloud Native .NET ou do Mensageria .NET) que, durante uma explicação, resolvi olhar a implementação de Minimal API’s do ASP .NET com o ILSpy, e entender por baixo do capô como Minimal API’s faziam, que me toquei de que não tinha como evitar o uso de reflection.

E de fato, em certos tipos de cenário, não dá para evitar reflection.

Situações em que Reflection é inevitável

Há casos em que simplesmente não é possível adotar outra abordagem, e seu emprego é indispensável e, em alguns poucos casos, reflection é a única solução viável:

• Serialização/Desserialização Dinâmica: Frameworks de serialização, como Newtonsoft.Json e System.Text.Json, utilizam Reflection para inspecionar propriedades de classes e converter dados entre diferentes formatos.
• Injeção de Dependência e Configuração de Serviços: Contêineres de injeção de dependência, como Autofac e o próprio IServiceProvider do ASP.NET Core, utilizam Reflection para resolver instâncias de serviços e gerar fábricas dinamicamente.
• Execução de Código Dinâmico: Aplicações que requerem carregamento dinâmico de assemblies e execução de código em tempo de execução, como sistemas de plugins e motores de scripts, dependem da capacidade introspectiva da Reflection.
• Automação e Ferramentas de Análise Estática: Ferramentas de análise de código, geração de proxies dinâmicos e introspecção de assemblies fazem uso extensivo de Reflection para examinar a estrutura interna de classes e métodos.

Source Generator é uma saída elegante

Lançado em 2020 com o .NET 5, Source Generator um novo recurso do compilador C# que permite que desenvolvedores C# inspecionem o código do usuário e gerem novos arquivos de origem C# que podem ser adicionados a uma compilação.. Source Generator não é bala de prata e não substitui completamente Reflection em todos os cenários, mas há uma parte significativa dos cenários de uso de reflection, em que é possível trazer toda a introspecção e dinamismo, que seria executada em runtime, para o momento do build.

Muitas vezes reflection é utilizada para simplificar e facilitar a codificação. Por exemplo, quando você constrói uma Action (Método) em uma Controller ou define uma expressão em uma Minimal API você está usando essa simplificação. O intuito é reduzir a quantidade de código protocolar e deixar para a infraestrutura do ASP.NET realizar todo o bind entre o model, o mecanismo de injeção de dependência e seu método.

Mas concorda que cada controller ou minimal API terá uma única mesma assinatura durante o ciclo de vida da instância da aplicação? A assinatura não é dinâmica, é estática. Para mudar uma assinatura do método, demanda um build, deploy etc.

Então, por que usar reflection em tempo de execução se podemos fazer isso apenas durante o build?

Essa é uma pergunta para a qual Source Generator é a resposta.

Assim, é perfeitamente possível ter source generators que convertam minimal api’s e actions de controllers em métodos mais burocráticos, removendo toda necessidade de reflection, trazendo todo o custo para a build. Essa abordagem antecipa a introspecção para o momento do build, assegurando que não precisaremos de introspecção durante a execução da aplicação (runtime).

Enquanto na Microsoft a busca por AOT faz a adoção de Source Generators estar aceleradíssima e abrangente, na comunidade e para os produtores de bibliotecas essa ainda não é uma realidade.

Bibliotecas como:

• MassTransit
• EasyNetQ
• Oragon.RabbitMQ

Ainda não adotaram Source Generators e é possível que outras bibliotecas sequer façam algum dia, sendo incompatíveis com AOT.

Mas afinal que custo é esse?

Quando trabalhamos com Middlewares, somos forçados a implementar uma assinatura específica, assim evitamos a utilização de reflection, mas quando lidamos com Controllers, Actions e Minimal API’s, há certa liberdade na assinatura e reflection se faz necessário.

Quando você implementa uma Minimal API ou uma Controller, um mecanismo do ASP.NET precisa mapear uma rota (em geral, informada via atributo) para um método escrito pelo desenvolvedor, do qual o ASP.NET não reconhece a assinatura. Esse método, ou seja, o código que você escreveu, pode ter praticamente qualquer assinatura.

Assim, o ASP.NET precisa transformar um request HTTP em parâmetros para que consiga chamar o seu código (da Action, por exemplo), e para isso ele vai pesquisar todos os argumentos do método, de todos os métodos públicos, de todas as suas controllers e minimal API’s em busca das assinaturas de cada método. Uma vez de posse dessa lista de assinaturas, é possível determinar os ModelBinders para cada Action e realizar algumas validações em busca de coerência e consistência.

Dessa forma, o ASP.NET consegue dinamicamente chamar seu método, passando Body, Http Headers, forms, serviços configurados na injeção de dependência e tudo mais que seu método precisa.

Sempre que precisamos perguntar para um tipo quais são suas características, pagamos um preço alto. Se queremos descobrir quais são as propriedades de um tipo, quais são os parâmetros de um método, ou coisas similares, temos de usar reflection para isso.

Esse não é o único cenário de reflection, é um exemplo.

Então a solução não seria abolir?

De um lado, reflection nos permite a injeção de dependência como conhecemos hoje, actions e controllers, minimal API’s e abstrações de consumo de filas como MassTransit, EasyNetQ e Oragon.RabbitMQ, da mesma forma que nos permite a adoção de MediatR e outras muitas tecnologias, inclusive de ORM.

Então, conviver com .NET sem reflection tornaria a plataforma irreconhecível, muito mais burocrática, tediosa e complexa.

As alternativas são:

• De um lado, adotar source generators sempre que possível e viável.
• E, de outro lado, otimizar o uso de reflection, evitando introspecções desnecessárias.

Otimizando Reflection em runtime com cache

Uma das demandas para o Oragon.RabbitMQ é a adoção de Source Generators para podermos eliminar o uso de reflection em runtime. Mas assim como outras bibliotecas desse gênero, essa solução ainda não está pronta.

Não busquei no roadmap das demais,
apenas busquei implementações
de source generators e reflection
na data desse post

Então, como minimizar o impacto de reflection em meu código?

A primeira pergunta a ser realizada antes de pensarmos em otimização é:
Quantas vezes serão realizadas essas introspecções?

A forma mais comum de implementação desse tipo de introspecção é realizar a cada chamada dinâmica.
Essa é a forma mais fácil e também a mais ineficiente.

A solução mais eficiente seria não adotar reflection, mas uma vez necessária, a solução mais eficiente é produzir um cache otimizado, reduzindo drasticamente o custo e pagando esse preço apenas uma vez, deixando de executar a introspecção a toda chamada dinâmica para pagar esse preço apenas uma única vez, necessariamente na subida da aplicação.

Temos como solução:

• A redução da quantidade de introspecção.
• Movemos todo o custo para a inicialização da aplicação.
• Cada chamada dinâmica não precisa mais de introspecção.
• Mover para a inicialização da aplicação evita custo exorbitante na primeira execução, como seria natural caso precisasse da primeira chamada para ativar esse cache.

Assim, evitamos buscas repetitivas por métodos, propriedades, parâmetros e atributos, e é possível armazenar esses resultados em estruturas de cache eficientes que duram por todo o ciclo de vida da instância da aplicação.

Essa estratégia reduz significativamente o tempo gasto na recuperação de metadados, melhorando a eficiência global.

Mas como implementar?

Ao invés de, ao receber cada mensagem, descobrir como chamar o método dinamicamente, optamos por uma estratégia em que, na subida da aplicação validamos tudo que foi registrado.

E talvez você não tenha percebido que ao chamar app.MapPost, você está registrando um handler na infra do ASP.NET Minimal API.

Assim quando você chama:

• No caso do ASP.NET minimal API:
  • MapGet
  • MaoPost
  • MapGet
  • MapPatch
  • MapPut
  • MapDelete
  • …
• Ou no caso do Oragon.RabbitMQ:
  • MapQueue

Você está registrando listeners, e parte do que você registra é essa expressão, que durante a compilação é encarada como um método.

...
app.MapPost("/http-example", ([FromServices] EmailService svc, [FromBody] DoSomethingCommand cmd)
=> {
    ...
    return Results.Ok();
});
...

...
app.MapQueue("amqp-example", ([FromServices] EmailService svc, [FromBody] DoSomethingCommand cmd)
=> {
    ...
    return AmqpResults.Ack();
})
...

Nem ASP.NET Minimal API, nem o Oragon.RabbitMQ precisamos ler o assembly inteiro buscando itens de interesse. Nós já recebemos essas informações gratuitamente quando no program.cs as chamadas ao MapPost (e seus irmãos) e MapQueue são executadas para registrar esses handlers. Então, ainda durante o processo de configuração da aplicação, já recebemos tudo que precisamos para fazer todas as análises.

...

public static ConsumerParameters MapQueue(this IHost host, string queueName, Delegate handler)
{
	return host.Services.MapQueue(queueName, handler);
}

...

public static ConsumerDescriptor MapQueue(this IServiceProvider serviceProvider, string queueName, Delegate handler)
{
	var consumerDescriptor = new ConsumerDescriptor(serviceProvider, queueName, handler);

	ConsumerServer consumerServer = serviceProvider.GetRequiredService<ConsumerServer>();

	consumerServer.AddConsumerDescriptor(consumerDescriptor);

	return consumerDescriptor;
}

...

Após a configuração, temos a subida da aplicação, e é aí que fazemos uso dessas configurações para de fato produzir análises com base em tudo que foi registrado.

Na hora de subir o consumidor, é hora de varrer os metadados internos, que temos com a assinatura de cada endpoint e buscar todos os parâmetros.

Com base na lista de parâmetros de entrada e saída, constrói-se o model binder com a lista de binders que preencherão os argumentos daquele método.

Pronto, agora a cada execução você não precisa descobrir quais são os argumentos do método dinâmico, você apenas obtém o model binder correspondente, itera produzindo a lista de argumentos e produz essa chamada.

Benefícios

A implementação das técnicas acima proporciona uma série de vantagens:

1. Melhoria no Tempo de Resolução de Métodos: A redução do número de chamadas de Reflection permite ganhos significativos de tempo de execução.
2. Eficiência na Utilização de Memória: O uso de caches reduz a alocação desnecessária de objetos intermediários.
3. Escalabilidade Aprimorada: Aplicações de alta carga se beneficiam da redução da latência de chamadas dinâmicas, tornando-se mais responsivas e eficientes.
4. Maior Clareza e Manutenção do Código: Reduzindo a dependência de Reflection, o código se torna mais previsível e fácil de manter.
5. Segurança Aprimorada: Evitar Reflection excessiva reduz vulnerabilidades associadas a ataques baseados em introspecção de código e manipulação dinâmica de objetos.

Considerações Finais

Reflection, apesar de seu custo, continua sendo um recurso fundamental para determinados cenários. A aplicação de técnicas como caching de metadados e geração estática de código reduzem significativamente os impactos negativos associados ao seu uso. Portanto, em vez de evitá-la completamente, a abordagem correta é otimizar sua utilização, garantindo que a flexibilidade oferecida pela introspecção de código não comprometa a escalabilidade e o desempenho da aplicação.

Ao mesmo tempo, as discussões acaloradas transformam o debate em uma rinha onde cada qual adota uma postura que desqualifica toda e qualquer opinião contrária.

Mas afinal, quanto custa uma exception?

Este artigo não pretende fornecer respostas definitivas, mas levantar questionamentos importantes:

Será que estamos ignorando alguma peça fundamental nessa discussão? A aversão às exceptions é justificada por dados concretos ou apenas uma tendência emergente sem embasamento empírico suficiente?

Uma análise superficial pode enganar?

O principal argumento contra exceptions está no seu suposto alto custo computacional. De fato, quando uma exceção é lançada, o runtime do .NET precisa capturar o estado da pilha, criar um objeto de exceção e executar o processo de unwinding da stack até encontrar um manipulador adequado. Sem dúvida, esse overhead é significativamente maior do que o de um simples if/else.

Mas a pergunta fundamental que não estamos fazendo é:

Que custo é esse? Esse custo realmente importa? Ele é relevante dentro do contexto de aplicações modernas que precisam acessar banco de dados relacional, nosql, cache, consumir mensagens de uma infra de mensageria ou stream, ou chamar apis http/rest, ou enviar logs pela rede opentelemetry?

Benchmarks: Comparação com outras operações

Ao analisar benchmarks, observamos que lançar uma exceção é muitas vezes mais custoso do que adotar if’s. Esses comparativos estão na casa dos nanosegundos (ns) ou microssegundos (μs).

No entanto, quando comparado a operações triviais em sistemas modernos, esse impacto pode ser marginal:

• Consultas a bancos de dados (~2-5ms);
• Acessos a cache distribuído como Redis (~0.5-1ms);
• Chamadas a APIs REST (~5-50ms, dependendo da rede e latência);
• Processamento de mensagens assíncronas em filas distribuídas (~2-5ms, dependendo da carga do sistema).

Em todos os exemplos acima, optei por valores utópicos. No mundo real, dá para multiplicar esses números algumas vezes.

Dado esse cenário, será que o custo das exceptions realmente justifica evitá-las completamente?

• A Microsoft, ao projetar o novo e moderno ASP.NET Core e o próprio .NET Runtime, não as removeu. Será que deveríamos?
• Qual é o impacto real na execução das aplicações?

Talvez uma informação adicional possa nos ajudar a refletir sobre:

Em vez de analisar exceptions apenas sob a ótica da performance comparando com o custo de um simples IF, precisamos contextualizar seu uso dentro do fluxo de execução da aplicação, entendendo quando seu custo é relevante e quando não é.

Por exemplo, no vídeo do JUL/2021 – Nick Chapsas – O custo oculto das exceções no .NET que referenciei no post anterior, temos:

• Medição em nanosegundos | 1 ns = 0,000 001 ms

A ausência de latência foi algo que me chamou a atenção em todos os benchmarks. Afinal, qual a relação entre nanosegundo/microssegundo com milissegundos?

Para entender o impacto da latência na expressividade do custo das exceptions resolvi fazer testes adicionando latência. Assim, rodei o benchmark acima por 45h38m, rodando 120 benchmarks diferentes, por todo esse período.

Quando adicionamos 2 milissegundos à execução, temos números mais expressivos, números que fazem mais sentido à compreensão humana.

2 ns = 1 Nanosegundo = 0,000 000 001 seg = 0,000 001 ms

assim

2ms = 2’000’000 ns

Assim, podemos ter uma noção melhor de quanto custa uma exception em relação à execução de uma aplicação, que, por exemplo, acesse um banco de dados.

Trazer os números do teste para a escala dos milissegundos torna o resultado menos abstrato. Agora é quase como se pudéssemos tocá-los.

Ainda vou detalhar esse teste, sua metodologia, em um post dedicado ao assunto, mas por hora é possível entender que a escala faz total diferença.

Será que estamos fazendo as perguntas certas?

A questão das exceptions não pode ser reduzida a um debate simples sobre custo, precisamos separar custo de valor.

Para isso, precisamos fazer perguntas mais profundas:

• O custo computacional das exceptions é realmente significativo?
  Em quais cenários?
• Até que ponto os benchmarks que desconsideram latência são confiáveis?
  Será que eles apresentam uma visão tendenciosa do problema?
• Estamos realmente buscando otimização de milésimos ou centésimos de milissegundo enquanto ignoramos impactos na arquitetura do software?
• Quais são os trade-offs reais entre código mais legível e pequenas otimizações de desempenho?

As críticas às exceptions geralmente nascem do uso inadequado. Como uma faca, que pode ser usada tanto para o bem quanto para o mal, seu mau uso pode gerar problemas reais.

Mas será que a solução seria simplesmente evitá-las?
Ou deveríamos buscar diretrizes mais claras para seu uso eficiente?

Próximos passos

No primeiro post, você viu diversas referências em vídeos que defendem a abolição das exceptions. Neste post, você viu que há uma questão sobre esse argumento central do custo de exceptions, a escala.

A escala em nanossegundos ou microssegundos é injusta, visto que todas as nossas grandes operações acontecem na escala dos milissegundos.

Dizer que lançar exception custa 10 vezes, custa 30 vezes mais, pode ser um argumento verídico, entretanto perde força quando olhamos para a escala dos milissegundos.

Ao trocarmos de escala, a tortura estatística derrete.

Da mesma forma que grandes números são inimagináveis.

Pequenos números também são.

Por isso é tão importante trazer para a escala de milissegundos (ms) em vez de continuar em nanossegundos (ns) ou microssegundos (μs). Mas é preciso muito cuidado para não fazer parecer que não há custo. A questão é sobre qual ponto de referência estamos adotando. Se tomarmos como referência o custo de um if, a exceções são muito mais caras, mas se tomarmos como referência um request http, uma operação maior, esse custo quase desaparece, se torna imperceptível. Só reaparecendo diante de um cenário de múltiplas exceções sendo lançadas na mesma execução, mas aqui o problema não é a exception, mas o tratamento equivocado.

Para essa discussão evoluir, preciso realmente fazer considerações:

• Para que lançamos exceptions
• Quando lançamos exceptions
• Onde lançamos exceptions, onde não lançamos.
• Por que tratamos?
• Onde não devemos tratar, devemos deixar estourar.
• Como tratamos.
• Onde tratamos.
• O que é tratar, e o que fazer em cada contexto.

e todos os detalhes para assegurar que, ao apresentar o resultado do benchmark, não alimente a ideia de uso indiscriminado e ilimitado de exceptions.

Por isso, o próximo post falará sobre as boas práticas com exceptions.

Se exceptions realmente fossem um problema significativo, por que ainda são adotadas de forma unilateral, em todo lugar, principalmente nos componentes centrais do ecossistema .NET, no ASP.NET, no Entity Framework e em diversas bibliotecas e fundações da própria Microsoft?

Será que há questões que não estamos considerando?

Antes de abraçar qualquer lado, é fundamental analisar a questão de forma técnica e pragmática.

Esta série de artigos pretende fornecer respostas, e levantar questionamentos importantes.

Em 2019…

Em 2016~2019 uma onda de “ataque às exceptions” apareceu na comunidade. Posts e mais posts falando mal de exceptions.

Até então, tudo bem, se não fossem os argumentos para trocar exceptions por notificações.

Foi então que resolvi parar para escrever sobre o assunto em um dos posts que mais rendeu aqui no gaGO.io:

Notification Pattern – Estão te vendendo um conceito errado

Notification Pattern prevê uma forma permissiva que troca exceptions por notificações em um determinado contexto, no entanto embora a maioria das publicações a respeito falem em não lançar exceptions, veremos que isso não é bem assim.

De 2021 a 2025 muita coisa aconteceu:

Nesse período, parece que se intensificaram os esforços. Vamos ver alguns vídeos interessantes.

JUL/2021 – Nick Chapsas
O custo oculto das exceções no .NET

JUN/2022 – Nick Chapsas
Não lance exceções em C#. Faça isso em vez disso

ABR/2024 – Nick Chapsas
.NET 9 corrigiu exceções, mas ainda não as use

JUL/2024 – Milan Jovanović
Exceções são extremamente caras… Faça isso em vez disso

JUL/2024 – Gui Ferreira
Adeus Exceções! Olá Padrão de Resultado!

SET/2024 – Dan Patrascu
Quando lançar exceções?

DEZ/2024 – Filip Ekberg
Pare de usar exceções em C#! Aqui está o porquê e o que fazer em vez disso

Fev/2025 – No LinkedIn

No início de Fev/2025, no LinkedIn, abordei a proliferação de try-catchs desnecessários em um projeto que tive acesso, em um processo seletivo.

Durante o debate promovido nos comentários, um comentário me chamou a atenção. Embora ele tenha dito que não era a meu respeito.

Como resultado, passei o final de semana rodando benchmarks
e o resultado foi surpreendente.

Mas não poderia pecar na mesma negligência da qual luto contra. Não poderia incorrer no mesmo erro. Portanto, é preciso contextualizar antes de publicar o resultado desses testes, exatamente porque é tênue a linha que separa o desfazer de uma falácia e a criação de outra em seu lugar.

Quero cuidar da precisão dessas informações para evitar o que considero um dos maiores problemas do nosso mercado: conteúdos rasos, com contextos rasos, sem fundamentos, pautados em achismos e perspectivas não fundamentadas.

Não acaba aqui, nossos próximos passos

Este artigo é apenas o ponto de partida de uma série de investigações. As próximas publicações abordarão um estudo empírico detalhado, com benchmarks rigorosos e simulações práticas. O objetivo será quantificar com precisão se exceptions representam um gargalo de desempenho significativo ou se sua suposta ineficiência é um mito amplificado por análises superficiais.

Além disso, exploraremos:

• Casos de uso onde exceptions podem ser substituídas por abordagens alternativas sem perda de robustez;
• A relação entre exceptions e arquitetura de software, analisando impactos além da performance bruta;
• Como boas práticas podem mitigar possíveis desvantagens no uso de exceptions.

A complexidade desse tema exige uma abordagem meticulosa, baseada em evidências concretas e análises aprofundadas. Estamos apenas começando a desvendar essa questão.

Se há algo que ainda não sabemos, precisamos descobrir.

E é exatamente isso que faremos nos próximos capítulos desta série.

Entretanto, não é tão raro esbarrar projetos que utilizem exclusivamente arquivos appsettings.json (e suas variações, como appsettings.Development.json, appsettings.Production.json, etc.) e inadvertidamente não só se ignorem o uso de variáveis de ambiente, mas também impossibilitem sua utilização.

O inferno tem um lugar especial para quem faz isso intencionalmente.

Você talvez já tenha visto projetos manipulando o IConfigurationBuilder para criar instâncias de IConfiguration.

Por exemplo, ao pesquisar por “IConfigurationBuilder IConfiguration” no google esbarramos na primeira página com uma publicação que sugere o seguinte:

Nesse contexto, temos uma questão.

Essa abordagem remove o que esperamos que seja default em um projeto asp.net.
Remove o que a Microsoft entrega como ponto de partida.

O que esperamos de um projeto .NET qualquer?

Não esperamos muito, apenas o que já vem com o ASP.NET, só esperamos que ninguém sacaneie o projeto removendo as capacidades básicas de configuração.

Pois é isso que a Microsoft entrega no código do Runtime .NET :

Isso quer dizer que, qualquer um que estiver diante de um projeto .NET tem a expectativa de que:

• Possa se usar o arquivo appsettings.json
• Que o arquivo $”appsettings.{env.EnvironmentName}.json” que usa EnvironmentName como parte do nome do arquivo.
• Que em desenvolvimento, seja possível usar UserSecrets
• Que possa usar Variáveis de Ambiente.
• Que possa usar o args, enviado para o processo.

Essa exata sequência é esperada. Nessa ordem, porque a próxima fonte de configuração sobrescreve as fontes de configuração anteriores.

Mas o que você quer dizer com sobrescrever?

As fontes se somam e, assim durante o carregamento o que for comum à duas fontes, é sobrescrito pela última. Last Win.

Assim, se no appsettings.json temos um json

{ 
    "ConnectionStrings": { 
         "xpto": "exemplo1" 
    } 
} 

basta usarmos a variável de ambiente ConnectionStrings__xpto para sobrescrever o valor com algo que a aplicação reconhecerá.

A variável de ambiente não sobrescreve o arquivo, as fontes se somam em memória, essa a grande diferença desse mecanismo em relação ao que tínhamos no web.config.

Por que usar variáveis de ambiente?

1. Segurança: Em muitos cenários, preferimos não colocar senhas e credenciais em arquivos de configuração (que acabam versionados no controle de versão). É mais seguro passar estes dados via variáveis de ambiente ou via serviços de “secret management”.
2. Flexibilidade: Quando rodamos a aplicação em diferentes ambientes (desenvolvimento local, homologação, produção), nem sempre é prático ter um appsettings.json para cada pequena variação. As variáveis de ambiente permitem mudar configurações sem precisar mexer no arquivo e sem precisar fazer deploy de novos arquivos.
3. Contêineres: Em orquestradores como Docker, Kubernetes, etc., definir variáveis de ambiente nos contêineres é um padrão, simplificando a gestão de configurações externas.
4. Cloud: Muitos cloud providers possuem mecanismos de gerenciamento de de configuração que possuem mecanismos para fazer bind da configuração com variáveis de ambiente, assim é possível determinar rollouts que atualizem essas variáveis reiniciando todas as aplicações dependentes dela.

Variáveis de ambiente são best in class?

Negativo: Variáveis de ambiente são melhores do que arquivos de configuração, mas serviços como Vault, são ainda melhores e mais seguros, mas como tudo em tecnologia, não são para todos nem para todos os projetos.

Conclusão

Apesar do template padrão do .NET Core já fornecer uma configuração com suporte a variáveis de ambiente, é comum ver projetos que, por desconhecimento ou tentativa de simplificação, removem esse suporte ou simplesmente não o utilizam em desenvolvimento. Isso leva a grandes dores de cabeça na hora de colocar a aplicação em produção ou em contêineres, pois então surgem necessidades de reescrever partes do projeto para considerar variáveis de ambiente.

O melhor caminho é desde o início assumir que sua aplicação será configurada por múltiplas fontes (appsettings, variáveis de ambiente, secrets etc.), mantendo o pipeline de configuração completo e aproveitando as funcionalidades já existentes no .NET Core. Desse modo, você não ficará “preso” a arquivos JSON e terá maior flexibilidade e segurança para lidar com credenciais e demais configurações em produção.

Em algumas ocasiões, fui questionado sobre os motivos para não usar MediatR. Para muitos desenvolvedores, sua presença em um projeto é considerada um padrão inevitável, algo que não precisa de justificativa ou debate.

Neste artigo, quero explorar essa ferramenta sob uma ótica mais crítica e avaliar seu impacto real na arquitetura de software.

Por que usamos o MediatR?

Quando participo da definição de uma arquitetura, sempre faço a pergunta: Qual problema estamos tentando resolver com MediatR?

Se as justificativas se resumirem a respostas como:

• “Sempre fizemos assim” / “É assim que se faz”
• “Foi assim que aprendi“ /
• “É assim que fulano faz“ / “É assim que fazíamos na empresa XXX” (em geral, essa resposta usada como argumento de autoridade)
• “É um padrão amplamente adotado.”
• “Os templates mais comuns já incluem MediatR.”

Então, é importante ficar atento, pois há fortes indícios de que o uso da biblioteca pode estar sendo motivado mais por convenção do que por necessidade técnica.

Isso não significa que o MediatR seja uma escolha ruim por si só. Meu objetivo não é criticá-lo, mas sim incentivar uma reflexão sobre seus reais benefícios e desafios. Um dos pontos que mais me preocupa é a falsa sensação de desacoplamento que sua adoção pode criar.

MediatR e o Desacoplamento

Uma das principais razões para utilizar o MediatR é a ideia de reduzir o acoplamento entre diferentes partes do código. No entanto, na maioria dos casos, ele é usado para implementar um modelo request/response, criando apenas uma camada de indireção entre quem faz a chamada e quem a atende.

O problema é que essa dependência não desaparece, apenas fica oculta. O chamador ainda depende diretamente do manipulador da requisição, mas agora através de um intermediário, o que pode adicionar complexidade sem um benefício claro.

Essa abordagem pode dificultar a leitura e manutenção do código. Com o MediatR, um simples fluxo de execução pode se tornar mais trabalhoso de entender, exigindo que os desenvolvedores naveguem entre múltiplas classes para compreender a relação entre os componentes.

Isso pode ser insignificante em aplicações pequenas, mas à medida que a complexidade cresce, essa abstração pode se tornar um obstáculo ao invés de um benefício.

Quando o MediatR é realmente útil?

O MediatR brilha quando utilizado em propagação de notificações ou publicação de eventos. Em um cenário 1 para N, onde um componente emite uma mensagem e múltiplos receptores podem agir sobre ela sem depender de respostas diretas, ele pode ser bastante útil.

Além disso, o MediatR pode ser uma solução eficiente para evitar dependências cíclicas dentro do domínio da aplicação.

Por outro lado, se o fluxo continua sendo estritamente sequencial e cada chamada depende da resposta da outra, o benefício do MediatR se torna questionável. Nesses casos, um serviço injetado diretamente pode ser uma solução mais simples, eficiente e direta.

Impacto na Performance

Outro aspecto que raramente é considerado é o impacto na performance. Embora em aplicações pequenas isso não seja um grande problema, em sistemas maiores a indireção extra pode gerar latências desnecessárias.

Cada requisição passa por um pipeline, o que pode aumentar a sobrecarga, especialmente se houver behaviors e middlewares adicionais configurados. Isso pode resultar em maior consumo de memória e pior desempenho em comparação com uma abordagem baseada em injeção de dependência direta.

Portanto, antes de adotar o MediatR, é importante avaliar se essa complexidade adicional realmente compensa em termos de manutenção e performance.

Beleza e Simplicidade

O uso do MediatR adiciona uma camada de indireção, separando a solicitação (request) de sua execução. Essa abordagem pode parecer mais verbosa à primeira vista, mas introduz um belo padrão arquitetural.

Comparação: Implementação Direta vs MediatR em Request/Response

Ao comparar uma implementação direta com uma implementação usando MediatR no padrão request/response, podemos perceber nuances que vão além da simples organização do código. Vamos ilustrar isso com um exemplo prático.

Implementação Direta:

public class PedidoService
{
    private readonly IPagamentoService _pagamentoService;

    public PedidoService(IPagamentoService pagamentoService)
    {
        _pagamentoService = pagamentoService;
    }

    public bool ProcessarPedido(Pedido pedido)
    {
        return _pagamentoService.RealizarPagamento(pedido);
    }
}

Neste caso, temos um código simples e direto. A dependência é explicitamente declarada e facilmente rastreável, tornando o código mais legível e de fácil depuração.

Por que é belo?

A beleza da implementação direta está na sua simplicidade, clareza e ausência de dúvidas. O fluxo de execução é evidente, o que facilita o entendimento e a manutenção do código. Quando um novo desenvolvedor precisa compreender a lógica, ele não precisa navegar entre múltiplas camadas ou abstrações, tornando o processo mais eficiente.

Implementação com MediatR:

public class ProcessarPedidoCommand : IRequest<bool>
{
    public Pedido Pedido { get; }
    public ProcessarPedidoCommand(Pedido pedido) => Pedido = pedido;
}

public class ProcessarPedidoHandler : IRequestHandler<ProcessarPedidoCommand, bool>
{
    private readonly IPagamentoService _pagamentoService;
    
    public ProcessarPedidoHandler(IPagamentoService pagamentoService)
    {
        _pagamentoService = pagamentoService;
    }

    public Task<bool> Handle(ProcessarPedidoCommand request, CancellationToken cancellationToken)
    {
        return Task.FromResult(_pagamentoService.RealizarPagamento(request.Pedido));
    }
}

A beleza do MediatR reside na organização e padronização da comunicação entre componentes da aplicação.

É importante ressaltar que, caso seja necessário adicionar novos comportamentos, como logs, validações ou métricas, podemos fazê-lo por meio de behaviors, conseguimos fazer isso sem modificar diretamente os handlers.

O uso do MediatR adiciona uma camada de indireção. Essa abordagem pode parecer mais verbosa à primeira vista. Nesse contexto, ele reduz o acoplamento direto entre serviços, transformando acoplamento direto em indireto, quase oculto. E aqui mora minha ressalva.

MediatR continua sendo uma boa escolha, mas é preciso ter clareza sobre seus objetivos de uso no projeto.

Conclusão

O MediatR não deve ser adotado automaticamente, apenas porque é um padrão popular. Ele tem muitos méritos, mas deve ser aplicado de forma criteriosa, como praticamente tudo em nossos projetos. Antes de implementá-lo, vale a pena considerar:

• Qual problema ele realmente resolve no contexto do projeto?
• Ele está promovendo um desacoplamento genuíno ou apenas escondendo dependências?
• O código ficaria mais claro e simples sem essa camada adicional?
• O impacto na performance justifica a adoção dessa abordagem?

Ferramentas e padrões de design existem para resolver problemas, não para serem utilizados indiscriminadamente. O MediatR pode ser uma solução interessante, mas sua adoção precisa ser pensada para ser estratégica. Senão, se torna apenas mais um peso que aumenta a complexidade sem trazer benefícios.

E você? Como tem utilizado o MediatR em seus projetos? Tem encontrado mais benefícios ou desafios?

Hoje discutimos os desafios de equilibrar anseios contraditórios, a tensão entre requisitos funcionais e não funcionais, e como essa decisão pode ser determinante para a sustentabilidade e o desempenho dos sistemas.

Os anseios de negócio: contradições e desafios

As empresas, por natureza, buscam crescimento, expansão e resultados imediatos. Muitas vezes, a demanda é por soluções que operem de maneira “tradicional”, sem que seja necessário repensar processos ou alterar estruturas consolidadas. Essa visão, que preza por manter o status quo, entra em conflito com a realidade técnica de que atender a volumes massivos sem promover mudanças é, simplesmente, inviável.

Em muitas organizações, há uma pressão intensa para que cada nova demanda seja rapidamente absorvida, mantendo a expectativa de que o sistema seja capaz de suportar volumes crescentes sem que se precise alterar o fluxo ou os mecanismos internos. Esse ideal, contudo, entra em colisão com os limites técnicos, que exigem a aplicação de estratégias de gerenciamento de carga, otimização de processos e, em alguns casos, a adoção de mecanismos que podem modificar o comportamento tradicional do sistema.

Imagine uma empresa de seguros que deseja implementar, de forma imediata, um novo módulo para análise de riscos em tempo real. O negócio acredita que, se essa funcionalidade estiver disponível, os clientes terão uma experiência mais dinâmica e a conversão de vendas aumentará. No entanto, a equipe técnica, ao analisar os requisitos, percebe que o sistema atual não foi projetado para processar em tempo real esse volume de dados complexos, o que pode resultar em lentidão ou até falhas no processamento. Nesse caso, apesar da demanda do negócio, os arquitetos recomendam uma abordagem gradual – implementando primeiro uma versão assíncrona e monitorada – antes de migrar para o processamento em tempo real.

A Cultura do “cliente tem sempre a razão” no Brasil

No Brasil existe um hábito quase arraigado de dizer “sim” a todas as solicitações, independentemente da complexidade ou dos desafios envolvidos. Essa postura, muitas vezes, decorre de uma cultura de otimismo exagerado ou da necessidade de agradar o cliente. Entretanto, essa atitude pode levar a promessas que, na prática, não se concretizam de forma executável.

Os mecanismos de cobrança e as pressões internas contribuem para que essa cultura se perpetue, mesmo quando as condições técnicas apontam para a impossibilidade de uma implementação sem alterações significativas. Essa realidade cria um ambiente onde o diálogo entre os diferentes setores da empresa – especialmente entre os times de negócios e de tecnologia – torna-se fundamental para estabelecer expectativas realistas e construir soluções robustas.

Em uma startup de tecnologia, a liderança frequentemente solicita novas funcionalidades sem uma análise profunda da infraestrutura atual. Por exemplo, o time de negócios decidiu adicionar uma funcionalidade de chat em tempo real para suporte ao cliente durante picos de vendas, sem considerar os impactos no servidor. Os desenvolvedores, pressionados, implementaram o recurso rapidamente. Após alguns dias de uso, o sistema começa a apresentar lentidão e instabilidades, justamente porque a arquitetura não previa um volume tão alto de conexões simultâneas. Esse cenário força a equipe técnica a interromper a funcionalidade para realizar ajustes na infraestrutura, evidenciando que um “sim” precipitado pode comprometer a qualidade do serviço. Afinal, qual a experiência dos clientes durante a instabilidade?

A divergência entre requisitos funcionais e não funcionais

Uma das principais fontes de tensão em times técnicos é causada pela forma como os profissionais são cobrados:

De um lado, o desenvolvedor é avaliado com base na entrega dos requisitos funcionais – ou seja, a capacidade de implementar as funcionalidades solicitadas.
De outro, o arquiteto é responsável pelos requisitos não funcionais, como desempenho, escalabilidade, segurança e confiabilidade do sistema.

Essa divisão gera, muitas vezes, um cenário de conflito. O time de desenvolvimento foca na criação de funcionalidades que atendam às demandas do negócio, enquanto os arquitetos precisam garantir que essas soluções possam suportar um volume crescente de acessos e transações, sem comprometer a qualidade do sistema. Dizer “NÃO” para o negócio, neste contexto, significa recusar demandas que coloquem em risco a integridade dos requisitos não funcionais, mesmo que, em um primeiro momento, pareça uma recusa ao que é pedido.

Conciliar essas duas perspectivas exige um diálogo constante e transparente entre todas as áreas. A maturidade para decidir quando ceder e quando resistir a novas demandas não é apenas uma questão técnica, mas também de gestão e comunicação. É preciso construir pontes que possibilitem que ambos os lados compreendam os limites e as necessidades do outro, estabelecendo prioridades que garantam a sustentabilidade do sistema a longo prazo.

Considere um sistema de pagamentos onde o time de desenvolvimento implementou rapidamente um novo método de checkout para aumentar as conversões – atendendo ao requisito funcional de maneira exemplar. Entretanto, os arquitetos perceberam que o novo fluxo não estava preparado para suportar o volume de transações esperado durante eventos promocionais, afetando a latência e a segurança das operações. Assim, mesmo tendo uma solução funcional, é preciso “dizer NÃO” para a implementação imediata, optando por uma revisão arquitetural que incluísse, por exemplo, balanceamento de carga e mecanismos de cache, para que o sistema se tornasse sustentável sob alta demanda.

A maturidade na decisão: Quando dizer sim e quando dizer não

Decidir entre dizer “sim” ou “não” para o negócio não é uma questão de teimosia ou de negativismo; é uma prática que exige visão de longo prazo e uma compreensão profunda dos limites técnicos. A maturidade, nesse contexto, é fundamental para que a equipe técnica possa fazer análises criteriosas e oferecer alternativas que, embora possam diferir da solicitação inicial, atendam aos objetivos estratégicos sem comprometer a qualidade ou a escalabilidade do sistema.

Essa maturidade se manifesta na capacidade de apresentar dados, projeções e análises que demonstram claramente os riscos associados à implementação de uma demanda sem os ajustes necessários. Em muitos casos, a recusa ou a proposta de uma solução alternativa não é uma rejeição ao negócio, mas um passo estratégico para evitar problemas imediatos ou futuros – como falhas em momentos críticos, aumento de custos com retrabalho ou até mesmo a perda de credibilidade no mercado.

Em um projeto de modernização de um sistema legado, o time de negócios pressiona para que todas as funcionalidades antigas sejam migradas de uma só vez para uma nova plataforma, a fim de reduzir custos e acelerar o tempo de lançamento. O time de arquitetura, porém, identifica que uma migração em massa pode causar indisponibilidade e inconsistências críticas nos dados. Após realizar testes de carga e simulações, a equipe técnica propôem uma migração gradual, utilizando feature flags para ativar novas funcionalidades de forma controlada. Essa decisão, baseada em dados e análise, permitiu validar a estabilidade do sistema e, posteriormente, atender às demandas do negócio de maneira sustentável.

Exemplo Prático: O Cenário do E-commerce

Considere o caso de um e-commerce que enfrenta um volume crescente de acessos e transações. A equipe de negócios pode insistir em manter o fluxo tradicional de finalização de compra, no qual o pedido é convertido imediatamente em uma compra. Entretanto, a equipe técnica, responsável por garantir que o sistema suporte picos de acesso sem travamentos ou perdas de dados, como na Black Friday, pode identificar que esse modelo não é sustentável sem ajustes.

Nesse cenário, a abordagem técnica pode sugerir que, ao invés de converter o pedido em uma compra imediata, o sistema trate o clique do cliente como uma solicitação de compra – uma mudança que, embora contrarie a expectativa tradicional, permite o uso de mecanismos como processamento assíncrono e filas para gerenciar o volume sem sobrecarregar a infraestrutura. Aqui, dizer “NÃO” ao modelo tradicional não é um obstáculo, mas sim uma decisão necessária para assegurar que o sistema continue performando de forma confiável, mesmo em momentos de alta demanda.

Conclusão

Dizer “NÃO”, em certos momentos, é uma escolha estratégica que visa a longevidade e a robustez do sistema. A tensão entre os anseios imediatos do negócio e as necessidades estruturais da tecnologia é real e exige maturidade para que as decisões sejam tomadas com base em análises técnicas sólidas e em um diálogo transparente entre todos os envolvidos.

No Brasil, onde a cultura do “cliente tem sempre a razão” pode facilmente obscurecer os limites técnicos, é imprescindível que as equipes de arquitetura e desenvolvimento se unam para construir pontes de entendimento. Somente assim será possível conciliar os requisitos funcionais – que atendem às demandas do negócio – com os não funcionais – que garantem a sustentabilidade do sistema –, criando soluções que não apenas respondam ao presente, mas que também estejam preparadas para a longevidade.

Estamos cansados de construir, quebrar, reconstruir e falhar novamente pelos mesmos erros que já cometemos no passado.

Neste texto, vamos discutir a viabilidade de usar o .NET Aspire em projetos baseados em Docker Compose e também mostrar o processo de migração do .NET Aspire de volta para o Docker Compose.

Recapitulando

Em um post anterior, apresentei:

• Os componentes de produção e desenvolvimento.
• A relevância do dashboard do .NET Aspire, que resolve um grande problema no fluxo de trabalho de desenvolvimento.
• Como o Docker Compose e seu YAML quase não têm utilidade em produção (em cenários onde se usa Kubernetes).

O ponto alto do dashboard do .NET Aspire é o baixo consumo de recursos, o que possibilita o uso de Tracing, Log e métricas de forma integrada na experiência do desenvolvedor a um custo baixíssimo de consumo de recursos, menos de 60 megas em alguns casos.

Contudo, há um contraponto: quando trabalhamos com Kubernetes, o Docker Compose se torna menos relevante em produção. Mas e durante o desenvolvimento? E se realmente precisamos dos projetos .NET rodando em containers?

Abstraindo o uso de Containers

Um problema comum no ecossistema de desenvolvimento é a busca por abstrações que transformem o desenvolvedor em “mero digitador de código”. Em muitos casos, o dev quer:

• Ignorar Docker
• Ignorar Containers
• Ignorar Kubernetes
• Ignorar Observabilidade
• Ignorar Mensageria e a teoria de Filas/Streaming

Essa “fuga” costuma vir do desejo de “focar no negócio” e negligenciar detalhes técnicos. Embora isso, em um primeiro momento, possa deixar o cliente satisfeito, gera um cenário tende a se deteriorar no primeiro desafio.

Como os ciclos de vida dos desenvolvedores nas empresas são cada vez menores, muitos não ficam tempo suficiente para lidar com as consequências de decisões que tomaram. Acabam saindo da empresa antes e replicando as mesmas práticas ruins em novos lugares, como uma doença crônica silenciosa, que só é percebida quando já é tarde.

Quanto maior o nível de desconhecimento, maior a insegurança

É claro que precisamos nos adaptar aos novos tempos e trazer profissionais mais rapidamente para um nível sênior. Porém, experiência não se compra e, definitivamente, não se obtém com apenas seis meses de treinamento.

No Cloud Native .NET, por exemplo, já tive dificuldades ao trabalhar com desenvolvedores plenos. Eles normalmente não estão acostumados a tomar decisões arquiteturais ou a resolver problemas complexos sozinhos. Geralmente seguem soluções “enlatadas”, fornecidas pelos seniores. Essa falta de vivência real e prática pesa substancialmente.

Quando falamos de projetos baseados em containers, fazer tudo rodar em containers durante o desenvolvimento faz enorme diferença.

Aspire atrapalha ou ajuda?

TL;DR; Ajuda, mas o o orquestrador é o componente controverso.

A minha experiência com o .NET Aspire foi muito positiva. Trata-se de uma solução bem feita, entretanto cria um distanciamento perigoso entre o .NET e Containers.

🔴Orquestrador

O Orquestrador do .NET Aspire é embarcado na aplicação AppHost, que por sua vez exibe um Dashboard (que pode ser usado isolado).

Sobre o orquestrador, tenho 2 críticas:

• ou deveria substituir o Docker Compose permitindo aplicações .NET rodando em Containers com debug e toda a experiência que temos com Docker Compose no Visual Studio.
• ou ser substituído pelo Docker Compose

O que definitivamente não quero é que minhas aplicações .NET
que serão containers Linux,
sejam desenvolvidas sem containers Linux.

🔴Service Discovery

A implementação Service Discovery é útil se você estiver rodando suas aplicações .NET no Windows. Com cada API rodando em uma porta diferente no localhost, ele se faz necessário e cumpre seu papel.

Mas na experiência com containers, onde cada container tem um nome, endereçável, e o mecanismo de service discovery é baseado em DNS, uma tecnologia de 1983, compatível com absolutamente qualquer coisa, essa implementação perde relevância e importância.

Então, no universo de containers, a implementação de Service Discovery do .NET Aspire é desnecessária.

🟢Open Telemetry

As configurações de Open Telemetry presentes em componentes e integrações do .NET Aspire são indiscutivelmente úteis e muito bem feitas. Não tenho do que reclamar, inclusive é algo que trouxe para o Docker Compose, com o dashboard.

🟢Dashboard

Se você já subiu ou tentou subir qualquer stack completa de observabilidade, provavelmente percebeu que o dashboard do .NET Aspire é um quebra-galho muito bom.

Eu vi na comunidade .NET um certo número de pessoas elogiando o Dashboard do .NET Aspire, como se fosse algo maravilhoso. Calma, né?! Pera lá. Seja Kibana ou Grafana, ou similares, temos opções mais profissionais, mais completas, mais flexíveis, desenhadas para cluster e produção, stateful, e mais customizáveis.

Dizer que o Dashboard do Aspire “é o que faltava” ou é o suficiente, é ridículo, uma demonstração absoluta de desconhecimento.

A grande carta na manga do Dashboard do .NET Aspire é:

1. De um lado, ser um único componente que incorpora 4 responsabilidades (que demandariam 4 componentes):
   • OpenTelemetry Collector
   • Log
   • Tracing
   • Metrics
2. E seu verdadeiro poder está no baixíssimo consumo de recursos.

O baixo consumo de recursos é o destaque, vezes mais relevante do que a quantidade de componentes que abstrai e vezes mais relevante que a simplicidade do dashboard.

🟢Containers auxiliares

O .NET Aspire também oferece praticidade na hora de adicionar containers auxiliares que administram serviços como Postgres, Redis etc. e configurá-los de forma integrada. Isso simplifica a adoção de ferramentas como PgWeb, PgAdmin ou Redis Commander, por exemplo.

Embora também sejam ferramentas que rodam sob containers, o distanciamento aqui não é muito relevante na medida que essas ferramentas que usamos para suportar o ambiente local, em geral, não serão as mesmas de produção. Dificilmente usaremos PgWeb, PgAdmin ou Redis Commander, em produção, portanto o distanciamento dessas configurações e containers é irrelevante.

🟢 Configurações de resiliência

Outro grande avanço são as configurações de resiliência e observabilidade automáticas entregues pelos componentes/integrações. Não poderia deixar de mencionar o acerto e quão bem-vindo foi.

O peso do distanciamento

É certo que não estamos aqui para aprender tecnologia, estamos aqui para entregar negócio com tecnologia. Aprender alguma tecnologia pode ser uma necessidade para entregar mais negócio, mas não é um objetivo em si.

Só não posso fechar os olhos sobre quão disruptivo é o universo Linux, para usuários nativos do Windows. O universo Cloud Native é desafiador principalmente para um desenvolvedor .NET , perder a possibildiade de debugar aplicações .NET containerizadas no linux é um problema.

Para quem é um problema?

Para mim, que sequer aprovo candidatos que não tenham conhecimento minimamente aprofundado em containers, quanto para alguns líderes que conversaram comigo nos últimos anos* e estão nessa jornada investindo em conhecimento para que seus times deixem de ser perdidos.

* Essas conversas nasceram quando
o docker-shim foi descontinuado ( Manchete: Kubernetes abandona docker)
e quando a docker criu sua subscription (Manchete: Docker agora é pago).

A lógica é simples: Músculo que não é usado atrofia!

Então, quando me distancio e vejo meu time (ou meus alunos) se distanciarem de containers, quase que fugindo do assunto, penso: Vamos nos enfraquecer essa “musculatura”!

E de fato a experiência de portar as configs do .NET Aspire para o Docker Compose me mostraram isso.

Container é algo disruptivo o suficiente para que eu possa julgar que não faz sentido nos distanciarmos, não é o que desejo para mim e para uma parcela talvez até pequena dos Arquitetos, Líderes Técnicos e CTO’s quem converso.

Porque no final do dia com .NET Aspire, não paramos de usar containers, só paramos de tocar neles no ambiente de desenvolvimento, com o Orquestrador do .NET Aspire colocamos uma camada de simplificação, entretanto os containers vão continuar dando problema em produção e agora cada vez mais porque o dev, agora com .NET ASPIRE, tem a chance de nunca “rodar” sua aplicação .NET em Containers Linux, diferente da experiência de quem usa Docker Compose.

A experiência entregue pelo .NET Aspire é útil, e talvez até vital, para uma galera mais jovem, atendendo uma demanda por devs cloud native produtivos a qualquer custo, onde Linux e Containers criam barreiras principalmente para haters do Linux.

Mas para aqueles que sofreram o suficiente com times perdidos, perder a possibilidade de rodar nossas aplicações .NET conteinerizadas no Linux significa aceitar a perda de autonomia, a perda da capacidade de execução, significa amarrar as nossas mãos.

Por outro lado, se quiséssemos alguma customização em um yaml, conseguiríamos obter referência de toda a comunidade Tech que usa docker no mundo. Com .NET Aspire, as customizações estão restritas aos projetos .NET com C#, ou seja, uma fração do mercado. O docker-compose.yaml, que poderia ser analisado no ambiente de desenvolvimento por qualquer time com o mínimo conhecimento de containers, dá lugar a um código C# que exige conhecimento muito mais específico.

Nos distanciamos das implantações.

Nos distanciamos drasticamente do Docker Compose e perdemos milhares de YAML’s produzidos por todas as comunidades, por todos os vendors e criadores de soluções conteinerizadas.

A lógica de deployment

O .NET Aspire tem no orquestrador todas as informações para que ambientes produtivos sejam criados a partir dele. Na hora de implantar, os utilitários do .NET Aspire geram deployments do Kubernetes, e serviços gerenciados dos principais cloud providers.

Isso faz com que eu me sinta quase como um gângster, forçando toda aplicação .NET Aspire a usar ou Kubernetes ou Serviços gerenciados de Cloud como se fossem as únicas opções, ignorando uma parcela significativa que continuará usando Swarm, Docker Compose on premise em servidores físicos ou virtuais, ou em VPS’s como uma parcela significativa dos MicroSaaS embrionários.

Quais desdobramentos possíveis?

Futurologia nunca foi meu departamento, mas não é muito difícil perceber que esse movimento distanciaria .NET do universo dos containers, ou pelo menos abraçaria aqueles que nunca iriam por conta da complexidade.

Então, são 2 pontos de vista antagônicos.

Um resultado previsível de uma adoção massiva do orquestrador do .NET Aspire é:

• Desaceleração na adoção de Docker, Docker Compose, Docker Swarm,
• Forçar a galera de On Premise e VPS para adotarem serviços de cloud gerenciados (com ou sem kubernetes).
• Retorno ao desenvolvimento de aplicações .NET rodando em Win32NT no IIS.

Claro que não é um bicho de 7 cabeças criar um provider para .NET Aspire para gerar Yaml de Docker Compose e afins, mas também não vejo sentido.

Mas o fato de não rodar .NET em containers, com a mesma experiência do docker compose, é um retrocesso indigesto.

Me recordo de ter torcido o nariz na época to Project Tye, agora torço o nariz para algumas decisões deliberadas a respeito de voltar com o workload inteiro para o Windows.

A discussão 6814 dá a pista de que pode ser que seja possível em um futuro qualquer, entretanto, enquanto não chega, vou usando o máximo do .NET Aspire no Docker Compose, já temos avanços incríveis com:

• Service Defaults
  • Configurações de Telemetria.
  • Configurações de Resiliência.
  • Configurações de Service Discovery.
• Dashboard
  • Se comportando como OpenTelemetry Collector
  • Servindo Métricas
  • Servindo Logs
  • Servindo Tracing

Já é um imenso avanço.

Você pode me fazer um favor? É grátis!

Vote na issue #6814 do github

Essa issue conduz o pedido para que .NET ASPIRE suporte Containers Linux com a experiência de debug.

Essa atividade é fundamental para uma plena experiência cloud native.

Nunca te pedi nada!!