Desempenho e Escala
Visão Geral
Desempenho é uma funcionalidade com orçamento. Meça-o, limite-o e respeite que os comportamentos de hoje se tornam os contratos de amanhã. Sistemas raramente falham na taxa de transferência para a qual foram projetados — eles falham na consulta que você não indexou e na lista que você não paginou.
Os Princípios
- Defina orçamentos e meça contra eles. Metas de latência (vinculadas aos SLOs de
observability-and-slos) e orçamentos do cliente (ex.: tamanho do bundle). Uma regressão além do orçamento é um bug. - Meça antes de otimizar. Encontre o gargalo real com dados — perfis, planos de consulta, rastreamentos — antes de alterar o código. Nenhuma otimização especulativa.
- Paginação por padrão. Qualquer lista que possa crescer é paginada com um tamanho de página limitado. Conjuntos de resultados ilimitados são um risco de latência e negação de serviço.
- Cuidado com padrões de acesso N+1. Dados buscados em um loop são a falha de escalabilidade mais comum; em lote ou junte-se a eles. (Nesta stack: use a camada de look-ahead/DataLoader do GraphQL em vez de resolução por linha.)
- A Lei de Hyrum é real: todo comportamento observável de uma interface se torna um contrato do qual alguém depende quando tem consumidores suficientes — incluindo comportamentos que você nunca intencionou (ordenação, nulabilidade, formas de erro, tempo). Trate interfaces públicas (a API/esquema especialmente) como contratos: adicione e deprecie, não altere silenciosamente. Os testes de contrato de
graphql-contract-testingfixam os comportamentos que você escolheu; a disciplina protege aqueles que você não escolheu.
Referência Rápida
| Problema | Solução |
|---|---|
| Consulta dentro de um loop | Em lote ou junte; use look-ahead |
| Endpoint de lista sem limite | Adicione paginação limitada |
| "Deixe-me otimizar isso" sem medição | Perfile primeiro; encontre o gargalo real |
| Alterar o tipo/nulabilidade/ordem de um campo | É uma mudança de contrato — adicione novo, deprecie o antigo |
| Sem alvo de latência ou bundle | Defina um orçamento; trate regressões como bugs |
Aplicação: orçamentos verificados no CI quando mecanizáveis (limites de tamanho de bundle, limites de custo de consulta); paginação e prevenção de N+1 são de julgamento do revisor, apoiados por testes de carga e revisão de plano de consulta.
Racional completo: Artigo XI da constituição, agrupado em engineering-constitution/references/engineering-constitution.md.