nextjs-healthcheck

Habilidade de Health Check e Observabilidade para Next.js (nextjs-healthcheck)

Um fluxo de trabalho modular e pronto para produção para criar e manter endpoints de health check (/api/health), sondas de saúde Docker Compose sem dependências externas e métricas de runtime do Node.js em aplicações Next.js App Router.

---

Visão Geral do Fluxo de Trabalho

flowchart TD
    A["1. Escanear Projeto<br/>(Banco de Dados & Docker Compose)"] --> B["2. Gerar /api/health<br/>(Modelos com Métricas)"]
    B --> C["3. Injetar Sondas Docker<br/>(docker-compose.yml)"]
    C --> D["4. Verificar & Validar<br/>(curl & docker compose ps)"]

---

Manual de Execução Passo a Passo

Siga esta lista de verificação sequencialmente para implementar e verificar o monitoramento de saúde da aplicação:

1. Descoberta do Projeto e Inspeção de Dependências

• Localizar Caminho do Manipulador de Rota: Determine se o projeto usa app/ ou src/app/ (alvo: app/api/health/route.ts ou src/app/api/health/route.ts).
• Detectar Banco de Dados / Armazenamentos Externos: Escaneie package.json em busca de ORMs e clientes (Prisma, Drizzle, Supabase, Mongoose, PostgreSQL, Redis). Consulte database-probes.md.
• Localizar Arquivos Docker Compose: Descubra docker-compose.yml, docker-compose.prod.yml ou outras stacks do compose. Consulte docker-compose-probes.md.

2. Implementar Manipulador de Rota de Health Check

• Selecionar Modelo de Rota:
  • Se Sem Banco de Dados: Implante route-no-db.ts.template.
  • Se Com Banco de Dados: Implante route-with-db.ts.template e conecte o cliente de BD específico do projeto com um limite de tempo estrito de 2 segundos.
• Forçar Execução Dinâmica: Garanta que export const dynamic = "force-dynamic"; e cabeçalhos Cache-Control: no-store, no-cache, must-revalidate estejam presentes.
• Configurar Métricas Não Bloqueantes: Colete saturação do heap V8, atraso do loop de eventos (lag $p99$ via perf_hooks) e tempo de atividade do processo. Consulte status-and-metrics.md.
• Aplicar Disciplina de Código de Status HTTP: Retorne 200 OK para healthy/degraded e 503 Service Unavailable para unhealthy.

3. Configurar Sondas de Saúde Docker Compose

• Identificar Serviços Next.js: Inspecione arquivos compose detectados em busca de blocos de serviço Next.js (nextjs-app, web, app).
• Injetar Bloco de Healthcheck: Adicione a sonda de saúde Node.js fetch sem dependências externas de docker-compose.healthcheck.template.yml.

4. Verificação e Testes

• Teste de API Local:

  curl -i http://localhost:3000/api/health
  

  Verifique a resposta HTTP 200 com payload JSON válido (status, timestamp, uptimeSeconds, checks).
• Verificação de Status de Saúde do Compose:

  docker compose ps
  

  Verifique se o estado do serviço transita para (healthy) após o período inicial de inicialização.

---

Casos Extremos e Armadilhas Conhecidas de IA

[!WARNING]

• force-dynamic Ausente: O Next.js App Router pode avaliar estaticamente ou armazenar em cache respostas de rota se export const dynamic = "force-dynamic" for omitido, causando timestamps desatualizados e métricas de tempo de atividade congeladas.
• Conexões de Banco de Dados Penduradas: Nunca consulte bancos de dados externos sem um limite de tempo de espera (máx. 2000ms). A latência de rede não tratada pode causar exaustão do pool de requisições.
• Dependências de Ferramentas Externas em Containers: Não confie em curl ou wget em health checks Docker; imagens mínimas de produção (ex.: node:alpine ou distroless) frequentemente não as possuem. Use o fetch nativo do Node.js via node -e.
• Vazamento de Segredos: Nunca imprima URLs de conexão de banco de dados, senhas ou rastros de erro interno brutos no payload de resposta pública de /api/health.

---

Esquema de Resumo de Saída

Ao concluir a configuração do health check, forneça um relatório de resumo conciso:

### Configuração de Monitoramento de Saúde Concluída

- **Manipulador de Rota**: `[app/api/health/route.ts](file:///...)`
- **Sondas de Banco de Dados**: [Configurado: Prisma / Drizzle / Nenhum] (Timeout: 2000ms)
- **Métricas de Runtime**: Saturação do Heap V8 e Atraso do Loop de Eventos (p99)
- **Stacks Docker Compose Atualizados**: `docker-compose.yml`, `docker-compose.prod.yml`
- **Status de Verificação**: APROVADO (HTTP 200 / Container Saudável)

---

Guias de Referência e Modelos

• Referência de Códigos de Status e Métricas — Matriz de status arquitetural, fórmulas de memória e limites de atraso.
• Referência de Sondas de Banco de Dados — Lista de verificação de detecção, encapsulamento de timeout e padrões de sonda ORM.
• Referência de Sondas Docker Compose — Regras de correspondência de serviços e definições de fetch sem dependências externas.
• Modelo de Rota (Sem BD) — Manipulador de rota completo para aplicações sem estado.
• Modelo de Rota (Com BD) — Manipulador de rota completo com sondas de dependência.
• Modelo de Healthcheck Docker Compose — Trecho de compose reutilizável.