Habilidad de Andamiaje de API

Q: ¿Fastify o Nest para cada nuevo servicio?

Fastify para APIs pequeñas con uso intensivo de E/S. Nest cuando el equipo necesita DI, módulos y guardias de GraphQL desde el primer día. Sigue el ADR de la organización; la habilidad no decide por sí sola.

Bootstrap de Fastify/Nest con pruebas y Dockerfile - una Habilidad de Agente para nuevos servicios Node.js 24 TypeScript.

Qué Hace Esta Habilidad

Produce una lista de verificación de andamiaje ejecutable: diseño de carpetas, scripts de package.json, endpoint de salud, registro estructurado, apagado elegante, Dockerfile y un stub de trabajo de GitHub Actions alineado con el CI del equipo.

Cuándo Invocarla

Nuevo microservicio en un monorepo o repositorio independiente
Reemplazar un prototipo solo de script con una API desplegable
Dividir un contexto delimitado de un monolito en su propio servicio
Estandarizar un repositorio de hackathon antes de la producción

Entradas

Entrada	Por qué
Nombre del servicio	Nombre del paquete, campo `service` del log, etiqueta de imagen Docker
ADR del framework	Fastify 5 vs NestJS 11 vs Express 5
Puerto por defecto	`3000` o convención de la plataforma
Dependencias de datos	Postgres, Redis, ninguna el primer día
Ruta del monorepo	`services/orders-api` vs repositorio raíz

Salidas

Árbol de directorios con src/, test/, Dockerfile
Scripts de package.json: dev, build, start, typecheck, test
Rutas /health y /ready (ready comprueba la DB si está configurada)
.env.example con stub de módulo de entorno validado por Zod
Extracto de .github/workflows/pr-checks.yml usando los mismos scripts
Bloque de comandos de verificación

Barandales

"type": "module" a menos que el ADR exija CommonJS.
No hay secretos en los archivos generados - solo marcadores de posición en .env.example.
Ruta de salud antes de las rutas de dominio - los balanceadores de carga la necesitan el primer día.
Registro JSON de Pino - no console.log en rutas de producción.
Apagado elegante - SIGTERM cierra el servidor y el pool de la DB.
No añadir ORM hasta que el ADR lo especifique - la interfaz de repositorio stub está bien.
engines.node fijado a 24.18.0.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Después de la salida de la habilidad - secuencia de verificación
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

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

Ejemplo de Trabajo (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 de NestJS

Cuando el ADR selecciona NestJS 11:

Usar el andamiaje de @nestjs/cli con TS estricto
Incluir main.ts con enableShutdownHooks()
Añadir el módulo de salud @nestjs/terminus
Los mismos comandos de verificación; cambiar inject por supertest contra INestApplication

Consulta Conceptos básicos de NestJS para una explicación más detallada.

Ejemplos de Prompts

Usa la Habilidad de Andamiaje de API para el servicio "inventory-api":
- Fastify 5, puerto 3001
- Postgres vía DATABASE_URL en .env.example
- Ruta del monorepo: services/inventory-api
- Incluir GitHub Actions: npm ci, typecheck, test, audit

Preguntas Frecuentes

¿Fastify o Nest para cada nuevo servicio?

Fastify para APIs pequeñas con uso intensivo de E/S. Nest cuando el equipo necesita DI, módulos y guardias de GraphQL desde el primer día. Sigue el ADR de la organización; la habilidad no decide por sí sola.

¿Incluir Prisma en el andamiaje?

Solo cuando la entrada indique que se aceptó el ADR de ORM. De lo contrario, crea una interfaz UserRepository stub y añade el ORM en un PR de seguimiento.

Relacionado

Conceptos básicos de las habilidades de agente - anatomía de la habilidad
Conceptos básicos de Fastify - conceptos del framework
Prueba de aplicaciones Fastify - pruebas de inyección
Validación con Zod y env-schema - módulo de entorno

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Qué Hace Esta Habilidad

Cuándo Invocarla

Nuevo microservicio en un monorepo o repositorio independiente
Reemplazar un prototipo solo de script con una API desplegable
Dividir un contexto delimitado de un monolito en su propio servicio
Estandarizar un repositorio de hackathon antes de la producción

Entradas

Entrada	Por qué
Nombre del servicio	Nombre del paquete, campo `service` del log, etiqueta de imagen Docker
ADR del framework	Fastify 5 vs NestJS 11 vs Express 5
Puerto por defecto	`3000` o convención de la plataforma
Dependencias de datos	Postgres, Redis, ninguna el primer día
Ruta del monorepo	`services/orders-api` vs repositorio raíz

Salidas

Árbol de directorios con src/, test/, Dockerfile
Scripts de package.json: dev, build, start, typecheck, test
Rutas /health y /ready (ready comprueba la DB si está configurada)
.env.example con stub de módulo de entorno validado por Zod
Extracto de .github/workflows/pr-checks.yml usando los mismos scripts
Bloque de comandos de verificación

Barandales

"type": "module" a menos que el ADR exija CommonJS.
No hay secretos en los archivos generados - solo marcadores de posición en .env.example.
Ruta de salud antes de las rutas de dominio - los balanceadores de carga la necesitan el primer día.
Registro JSON de Pino - no console.log en rutas de producción.
Apagado elegante - SIGTERM cierra el servidor y el pool de la DB.
No añadir ORM hasta que el ADR lo especifique - la interfaz de repositorio stub está bien.
engines.node fijado a 24.18.0.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

# Después de la salida de la habilidad - secuencia de verificación
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

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

Ejemplo de Trabajo (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 de NestJS

Cuando el ADR selecciona NestJS 11:

Usar el andamiaje de @nestjs/cli con TS estricto
Incluir main.ts con enableShutdownHooks()
Añadir el módulo de salud @nestjs/terminus
Los mismos comandos de verificación; cambiar inject por supertest contra INestApplication

Consulta Conceptos básicos de NestJS para una explicación más detallada.

Ejemplos de Prompts

Usa la Habilidad de Andamiaje de API para el servicio "inventory-api":
- Fastify 5, puerto 3001
- Postgres vía DATABASE_URL en .env.example
- Ruta del monorepo: services/inventory-api
- Incluir GitHub Actions: npm ci, typecheck, test, audit

Preguntas Frecuentes

¿Fastify o Nest para cada nuevo servicio?

¿Incluir Prisma en el andamiaje?

Solo cuando la entrada indique que se aceptó el ADR de ORM. De lo contrario, crea una interfaz UserRepository stub y añade el ORM en un PR de seguimiento.

Relacionado

Conceptos básicos de las habilidades de agente - anatomía de la habilidad
Conceptos básicos de Fastify - conceptos del framework
Prueba de aplicaciones Fastify - pruebas de inyección
Validación con Zod y env-schema - módulo de entorno

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Habilidad de Andamiaje de API

Buscar en la documentación

Habilidad de Andamiaje de API