Habilidade de Scaffold de API

Bootstrap Fastify/Nest com testes e Dockerfile - uma Habilidade de Agente para novos serviços Node.js 24 TypeScript.

O Que Esta Habilidade Faz

Produz uma checklist de scaffold executável: layout de pasta, scripts package.json, endpoint de saúde, logging estruturado, desligamento gracioso, Dockerfile e stub de job do GitHub Actions alinhado com o CI da equipe.

Quando Invocar

• Novo microsserviço em um monorepo ou repositório independente
• Substituição de um protótipo apenas com scripts por uma API implantável
• Divisão de um contexto delimitador de monólito em seu próprio serviço
• Padronização de um repositório de hackathon antes do endurecimento para produção

Entradas

Saídas

• Árvore de diretórios com src/, test/, Dockerfile
• Scripts package.json: dev, build, start, typecheck, test
• Rotas /health e /ready (ready verifica o DB se configurado)
• .env.example com stub de módulo de ambiente validado por Zod
• Trecho de .github/workflows/pr-checks.yml usando os mesmos scripts
• Bloco de comando de verificação

Barreiras de Proteção

1. "type": "module" a menos que o ADR exija CommonJS.
2. Sem segredos nos arquivos gerados - apenas placeholders em .env.example.
3. Rota de saúde antes das rotas de domínio - balanceadores de carga precisam dela desde o primeiro dia.
4. Logging JSON do Pino - sem console.log em caminhos de produção.
5. Desligamento gracioso - SIGTERM fecha o servidor e o pool do DB.
6. Não adicionar ORM até que o ADR especifique - stub da interface do repositório é aceitável.
7. engines.node fixado em 24.18.0.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Após a saída da habilidade - sequência de verificação
cd services/billing-api
npm ci
npm run typecheck
npm test
npm run build
docker build -t billing-api:local .
docker run --rm -p 3000:3000 --env-file .env.example billing-api:local &
curl -sf http://localhost:3000/health
curl -sf http://localhost:3000/ready

# Árvore esperada (Fastify 5)
billing-api/
├── src/
│   ├── app.ts          # factory buildApp()
│   ├── server.ts       # listen + shutdown
│   ├── env.ts          # process.env do Zod parse
│   └── routes/
│       └── health.ts
├── test/
│   └── health.test.ts  # node:test + inject
├── Dockerfile
├── package.json
├── tsconfig.json
└── .env.example

Exemplo de Trabalho (Fastify 5)

// src/app.ts
import Fastify from "fastify";
import { healthRoutes } from "./routes/health.js";
 
export async function buildApp() {
  const app = Fastify({
    logger: { level: process.env.LOG_LEVEL ?? "info" },
  });
  await app.register(healthRoutes);
  return app;
}

// src/server.ts
import { buildApp } from "./app.js";
import { env } from "./env.js";
 
const app = await buildApp();
 
const close = async () => {
  app.log.info({ event: "shutdown" });
  await app.close();
  process.exit(0);
};
 
process.on("SIGTERM", close);
process.on("SIGINT", close);
 
await app.listen({ port: env.PORT, host: "0.0.0.0" });

# Dockerfile
FROM node:24.18.0-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
FROM node:24.18.0-alpine
WORKDIR /app
ENV NODE_ENV=production
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Variante NestJS

Quando o ADR selecionar NestJS 11:

• Usar scaffold do @nestjs/cli com TS estrito
• Incluir main.ts com enableShutdownHooks()
• Adicionar módulo de saúde @nestjs/terminus
• Mesmos comandos de verificação; trocar inject por supertest contra INestApplication

Veja Conceitos Básicos do NestJS para profundidade legível.

Exemplos de Prompts

Use a Habilidade de Scaffold de API para o serviço "inventory-api":
- Fastify 5, porta 3001
- Postgres via DATABASE_URL em .env.example
- Caminho do monorepo: services/inventory-api
- Incluir GitHub Actions: npm ci, typecheck, test, audit

FAQs

Relacionados

• Conceitos Básicos de Habilidades de Agente - anatomia da habilidade
• Conceitos Básicos do Fastify - conceitos do framework
• Testando Aplicações Fastify - testes de injeção
• Validação Zod & env-schema - módulo de ambiente

Versões de Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.