Padrões de Engenharia de Software & Design de Sistemas

Um guia operacional rigoroso e testado em batalha para excelência em engenharia de software, arquitetura de sistemas, design de baixo nível e sistemas distribuídos.

1. Princípios Operacionais Centrais

Trocas ao Invés de Dogmas: Não existem "melhores práticas" universais, apenas trocas. Cada escolha arquitetural compra um conjunto de benefícios pagando um custo específico (latência, consistência, complexidade operacional ou sobrecarga cognitiva). Sempre declare o que está sendo sacrificado.
Reversibilidade Primeiro: Priorize decisões de porta dupla (reversíveis) em vez de decisões de porta única (irreversíveis). Evite acoplamento prematuro a fornecedores, frameworks ou topologias distribuídas específicas.
Sem Astronáutica de Arquitetura: Toda abstração, interface e camada deve justificar seu peso com base em requisitos concretos existentes, não em necessidades futuras especulativas (YAGNI).
Design Baseado em Evidências: Fundamente decisões em perfis concretos, medições, planos de consulta (EXPLAIN ANALYZE) e limites de capacidade, em vez de suposições.
Limites Explícitos com Falha Rápida: Limites entre subsistemas, domínios ou saltos de rede devem ter contratos explícitos e fortemente tipados, validação, timeouts, circuit breakers e garantias de idempotência.

2. Fluxo de Trabalho de Design de Alto Nível (HLD) e Arquitetura

Ao projetar um sistema, avaliar uma arquitetura ou refatorar um subsistema importante, execute este framework de 6 etapas:

flowchart TD
    Step1["1. Esclarecer Requisitos e Escopo<br>(Funcionais, Não Funcionais, Latência, Disponibilidade, Consistência)"]
    Step2["2. Estimativa de Capacidade e Escala<br>(DAU, QPS, Throughput, Largura de Banda de Rede, Armazenamento, RAM de Cache)"]
    Step3["3. Arquitetura de Alto Nível (C4 L1/L2)<br>(Limites de Serviço, Seleção de Armazenamento, Entrada, Cache)"]
    Step4["4. Modelo de Dados e Contratos de Interface<br>(Entidades, Esquemas, Chaves Primárias, Índices, APIs REST/gRPC)"]
    Step5["5. Análises Aprofundadas e Isolamento de Gargalos<br>(Replicação, Sharding, Concorrência, Patologias de Cache, Hotspots)"]
    Step6["6. Estratégia de Resiliência e SRE<br>(SLOs, Circuit Breakers, Retentativas com Jitter, Idempotência, DLQs)"]

    Step1 --> Step2 --> Step3 --> Step4 --> Step5 --> Step6

Referência Detalhada de HLD

Para teoremas de sistemas distribuídos (CAP, PACELC), hierarquias de consistência, consenso (Raft/Paxos), sharding, replicação, padrão Saga e padrão Transactional Outbox, consulte: 👉 Referência de Design de Sistemas de Alto Nível e Sistemas Distribuídos

3. Padrões de Design de Baixo Nível (LLD) e Código Limpo

Ao escrever, revisar ou refatorar código, siga estes padrões:

3.1 As Regras SOLID

SRP (Responsabilidade Única): Um módulo responde a um único ator/interessado. Extraia persistência, serialização HTTP e lógica de negócios em preocupações separadas.
OCP (Aberto/Fechado): Prefira polimorfismo, padrões Strategy ou Visitor em vez de declarações extensas de switch/if-else baseadas em tipo.
LSP (Substituição de Liskov): Subtipos devem satisfazer todos os invariantes comportamentais da classe pai. Sobrescrever métodos para lançar NotImplementedException viola LSP.
ISP (Segregação de Interface): Prefira interfaces de função pequenas e específicas para o cliente em vez de interfaces amplas do tipo "Deus".
DIP (Inversão de Dependência): As regras de negócio principais dependem apenas de abstrações (Portas), nunca diretamente de bibliotecas de banco de dados externas, frameworks de interface de usuário ou drivers de rede.

3.2 Encapsulamento Modular (Parnas & Connascence)

Segredos do Módulo: Um módulo deve ocultar completamente seu segredo principal (algoritmos/estruturas de dados internos) e seu segredo secundário (ambientes externos/formatos de arquivo).
Connascence: Minimize a connascence dinâmica (Ordem de execução, Tempo, Restrições de valor) e reduza o acoplamento a acordos de nome/tipo estáticos.

Referência Detalhada de LLD

Para guias de padrões de design GoF (Gang of Four), blocos de construção táticos de Domain-Driven Design (DDD) (Entidades, Objetos de Valor, Agregados, Eventos de Domínio) e técnicas de refatoração, consulte: 👉 Referência de Design de Baixo Nível e Código Limpo

4. Padrões de API e Persistência de Dados

APIs RESTful:
- Siga estritamente a semântica dos métodos HTTP (GET é seguro e idempotente; PUT/DELETE são idempotentes; POST cria).
- Use RFC 7807 (Problem Details) para respostas de erro estruturadas.
- Para coleções de alto volume, use paginação por Keyset/Cursor em vez de paginação por Offset/Limit.
Indexação de Banco de Dados (Regra E-R-S):
- Ordenação de colunas em índices compostos: [Colunas de Igualdade] $ o$ [Colunas de Intervalo] $ o$ [Colunas de Ordenação].
- Use Índices de Cobertura (Varreduras Apenas de Índice) e Índices Parciais para eliminar buscas em páginas de disco para consultas frequentes.
- Sempre verifique consultas com EXPLAIN QUERY PLAN ou EXPLAIN ANALYZE.
Mensageria e Eventos Assíncronos:
- Garanta processamento efetivamente único combinando entrega pelo menos uma vez do broker com idempotência do consumidor (IDs de mensagem únicos desduplicados no armazenamento).
- Encaminhe mensagens não processáveis (poison pills) para Dead Letter Queues (DLQs) para evitar travamento de partição.

Referência Detalhada de API e Dados

👉 Padrões de Design de API e Persistência de Dados

5. Engenharia de Desempenho, Capacidade e Confiabilidade

Estimativa de Ponta de Lápis:
- $1 ext{ dia} uildrel\text{aprox}\over{=} 10^5 ext{ segundos}$ ($86.400 ext{ s}$). $1 ext{M requisições/dia} uildrel\text{aprox}\over{=} 12 ext{ RPS}$.
- Pico de QPS = QPS Médio $ imes$ $3 imes$.
- RAM de Cache = $20% imes ( ext{Volume de Leitura Diário} imes ext{Tamanho do Item})$ (regra 80/20 de Pareto).
- Lei de Little: $L = \lambda W$ (Concorrência em voo = Taxa de chegada $ imes$ Latência).
Disciplina de Cache:
- Nunca defina TTLs arbitrários não medidos em memória que expiram durante janelas operacionais normais.
- Invalide com base em versão/fingerprint de dados ou timestamps de sessão.
- Defenda-se contra Cache Stampede (use mutexes/locks distribuídos), Cache Penetration (filtros Bloom) e Cache Avalanche (jitter de TTL).
Engenharia de Confiabilidade de Site (SRE):
- Imponha SLOs explícitos e orçamentos de latência ($p50$, $p95$, $p99$).
- Implemente Circuit Breakers, Bulkheads e Exponential Backoff com Full Jitter.

Referência Detalhada de Confiabilidade e Desempenho

👉 Referência de Confiabilidade, Desempenho e Engenharia de Capacidade

6. Registros de Decisão de Arquitetura (ADRs)

Documente escolhas técnicas não triviais usando o formato padrão de ADR:

Contexto e Direcionadores: O problema, restrições operacionais e metas de latência/escala.
Opções Consideradas: Alternativas estruturais e suas trocas.
Decisão e Resultado: Justificativa concreta relacionada aos direcionadores da decisão.
Consequências: Benefícios positivos explícitos E custos negativos aceitos.

Referência e Template Detalhado de ADR

👉 Referência de Registros de Decisão de Arquitetura e Modelo C4

axewhyzed/agentic-skills

O que é agentic-skills?

Perguntar na sua IA favorita

Documentação