Engenharia
Como projetar controles de integridade para APIs criadas por IA
A IA pode gerar uma API rapidamente, mas a plataforma ainda precisa de um endpoint de integridade que reflita a situação real antes de enviar tráfego de produção.
O controle de integridade mais fácil sempre retorna 200. O controle útil identifica quando uma API criada por IA deve ser retirada do roteamento.
Separe atividade de disponibilidade
O controle de atividade verifica se o processo ainda funciona o suficiente para se recuperar sem reinício. O de disponibilidade verifica se pode atender ao tráfego com segurança agora. Unir ambos em um endpoint de alto custo pode transformar uma dependência lenta em um ciclo de reinícios.
Mantenha o controle de atividade local e de baixo custo. Use o controle de disponibilidade para as poucas dependências que impedem atender às solicitações quando falham. Um serviço de análise em segundo plano raramente pertence a esse conjunto; uma conexão obrigatória ao banco costuma pertencer.
- —Atividade: o loop de eventos ou processo responde; não exige chamadas externas.
- —Disponibilidade: dependências necessárias para atender às solicitações respondem dentro de um prazo fixo.
- —Inicialização: a inicialização e as migrações terminam antes de o controle de disponibilidade passar.
Limite o tempo para detectar a falha
Uma sonda que espera indefinidamente não cumpre seu papel. Defina um timeout curto, evite tentativas ilimitadas no handler e retorne uma falha clara quando a aplicação não conseguir comprovar disponibilidade a tempo. A plataforma pode então parar de encaminhar novo tráfego enquanto o processo se recupera ou uma substituição inicia.
O endpoint também deve evitar alterar dados. Controles de integridade são executados com frequência, de vários locais e em condições já degradadas. Uma consulta somente leitura ou uma verificação leve de dependência é mais segura do que uma escrita usada apenas para comprovar o acesso.
export async function GET() {
const ready = await dependenciesReady({ timeoutMs: 500 });
return Response.json(
{ status: ready ? "ready" : "not_ready" },
{ status: ready ? 200 : 503 },
);
}Teste os cenários de falha
Uma rota de integridade só testada quando todas as dependências funcionam está incompleta. Pare o banco, esgote um pool de conexões, faça um serviço upstream obrigatório exceder seu timeout e confirme que o controle de disponibilidade falha antes de as solicitações normais se acumularem.
Em seguida, restaure a dependência e verifique se o processo retorna à rota sem intervenção manual. O caminho de recuperação também faz parte do contrato.
- —Bloqueie conexões ao banco e verifique se o controle de disponibilidade passa a retornar 503.
- —Atrase um serviço upstream obrigatório além do prazo da sonda.
- —Envie SIGTERM e confirme que o controle de disponibilidade falha antes do início do encerramento.
- —Restabeleça as dependências e confirme que a réplica volta à rotação quando estiver estável.
Evite incidentes causados pelas sondas
A frequência das sondas se multiplica rapidamente entre réplicas e locais de monitoramento. Dez réplicas verificadas a cada segundo podem acrescentar centenas de consultas às dependências por minuto. Mantenha a consulta de baixo custo, use cache apenas quando não puder esconder uma indisponibilidade real e acrescente variação nos intervalos se todas as réplicas fariam a verificação ao mesmo tempo.
Gere alertas para perda persistente de disponibilidade e para o número de réplicas que funcionam, não para cada falha isolada de verificação. Um timeout transitório é uma evidência; a redução do conjunto de réplicas que atendem é um incidente.