Conceptos básicos de Fastify

Q: ¿Es Fastify compatible con el middleware de Express?

A través de @fastify/express o middie, pero prefiere los plugins nativos de Fastify. El middleware de Express pierde los beneficios de la validación de esquemas.

Q: ¿Fastify soporta ESM?

Sí. Fastify 5 es ESM-first. Usa import Fastify from "fastify".

Q: ¿Cómo manejo los tipos de TypeScript para los esquemas?

Usa fastify-type-provider-zod o @fastify/type-provider-typebox para tipos inferidos de esquemas.

Q: ¿Puede NestJS usar Fastify?

Sí. NestFactory.create(AppModule, new FastifyAdapter()). Consulta Conceptos básicos de NestJS.

10 ejemplos para construir tu primera API de Fastify 5 - 7 básicos y 3 intermedios.

Prerrequisitos

mkdir fastify-api && cd fastify-api
npm init -y
npm pkg set type=module
npm install fastify@5
npm install -D typescript@5.6 tsx

Para la validación de esquemas y patrones de plugins, consulta Validación de esquemas JSON y Plugins de Fastify.

Ejemplos básicos

1. Servidor "Hola Mundo"

import Fastify from "fastify";
 
const app = Fastify({ logger: true });
 
app.get("/", async () => {
  return { message: "Hello from Fastify 5" };
});
 
await app.listen({ port: 3000, host: "0.0.0.0" });

Devuelve objetos de los manejadores; Fastify los serializa a JSON automáticamente
logger: true habilita Pino con valores predeterminados sensatos
Usa await app.listen() (escucha asíncrona de Fastify 5)

2. Ruta con esquema

import Fastify from "fastify";
 
const app = Fastify();
 
app.get("/users/:id", {
  schema: {
    params: {
      type: "object",
      properties: { id: { type: "string", format: "uuid" } },
      required: ["id"],
    },
    response: {
      200: {
        type: "object",
        properties: { id: { type: "string" }, name: { type: "string" } },
      },
    },
  },
}, async (req) => {
  return { id: req.params.id, name: "Ada Lovelace" };
});

El esquema valida la solicitud y compila la serialización de la respuesta
Las solicitudes no válidas devuelven 400 automáticamente
Consulta Validación de esquemas JSON para más detalles

3. POST con esquema de cuerpo

import Fastify from "fastify";
 
const app = Fastify();
 
app.post("/users", {
  schema: {
    body: {
      type: "object",
      required: ["name", "email"],
      properties: {
        name: { type: "string", minLength: 1 },
        email: { type: "string", format: "email" },
      },
    },
  },
}, async (req, reply) => {
  const { name, email } = req.body as { name: string; email: string };
  return reply.status(201).send({ id: "1", name, email });
});

reply.status(201).send() para códigos de estado explícitos
El cuerpo se valida antes de que se ejecute el manejador
TypeScript: usa herramientas de esquema a tipo o aserción en el límite

4. Encapsulamiento de plugins

import Fastify from "fastify";
 
const app = Fastify();
 
app.register(async function userRoutes(fastify) {
  fastify.get("/", async () => [{ id: 1, name: "Ada" }]);
  fastify.get("/:id", async (req) => ({ id: (req.params as { id: string }).id }));
}, { prefix: "/users" });

register crea un ámbito encapsulado
Los decoradores y hooks dentro de un plugin no se filtran a los hermanos
prefix monta todas las rutas bajo /users

5. Hooks de ciclo de vida

import Fastify from "fastify";
 
const app = Fastify({ logger: true });
 
app.addHook("onRequest", async (req) => {
  req.headers["x-request-start"] = String(Date.now());
});
 
app.addHook("onResponse", async (req, reply) => {
  const start = Number(req.headers["x-request-start"]);
  req.log.info({ duration: Date.now() - start, status: reply.statusCode });
});
 
app.get("/health", async () => ({ ok: true }));

Los hooks se ejecutan en etapas definidas del ciclo de vida
onRequest se ejecuta antes del enrutamiento; preHandler se ejecuta antes del manejador
Usa hooks para registro, autenticación y temporización

6. Manejo de errores

import Fastify from "fastify";
 
const app = Fastify();
 
app.setErrorHandler((err, _req, reply) => {
  const status = err.statusCode ?? 500;
  reply.status(status).send({
    error: status === 500 ? "Internal server error" : err.message,
  });
});
 
app.get("/fail", async () => {
  throw Object.assign(new Error("Not found"), { statusCode: 404 });
});

setErrorHandler es el manejador de errores centralizado
Adjunta statusCode a los errores para errores operacionales
Los errores de validación de los esquemas tienen statusCode: 400

7. Registro con Pino

import Fastify from "fastify";
 
const app = Fastify({
  logger: {
    level: process.env.LOG_LEVEL ?? "info",
    transport: process.env.NODE_ENV === "development"
      ? { target: "pino-pretty" }
      : undefined,
  },
});
 
app.get("/users", async (req) => {
  req.log.info({ action: "list_users" });
  return [];
});

req.log es un logger hijo con contexto de solicitud
Producción: logs JSON a stdout; envía a tu agregador de logs
Consulta Registro con Pino

Ejemplos intermedios

8. Rompiendo el encapsulamiento con fastify-plugin

import Fastify from "fastify";
import fp from "fastify-plugin";
 
const authPlugin = fp(async (fastify) => {
  fastify.decorate("authenticate", async (req: { headers: { authorization?: string } }) => {
    if (!req.headers.authorization) throw Object.assign(new Error("Unauthorized"), { statusCode: 401 });
  });
});
 
const app = Fastify();
await app.register(authPlugin);
// authenticate está disponible en todos los ámbitos

Sin fastify-plugin, los decoradores tienen un ámbito limitado al plugin que los registra
Usa fp para autenticación compartida, conexiones a bases de datos y configuración

9. Pruebas con inject()

import Fastify from "fastify";
import { test } from "node:test";
import assert from "node:assert/strict";
 
const app = Fastify();
app.get("/health", async () => ({ ok: true }));
 
test("GET /health", async () => {
  const res = await app.inject({ method: "GET", url: "/health" });
  assert.equal(res.statusCode, 200);
  assert.deepEqual(res.json(), { ok: true });
});

inject() simula HTTP sin E/S de red
Órdenes de magnitud más rápido que supertest con enlace de puerto
Consulta Pruebas de aplicaciones Fastify

10. Ajuste del tiempo de espera del servidor

import Fastify from "fastify";
 
const app = Fastify();
 
await app.listen({ port: 3000 });
 
const server = app.server;
server.keepAliveTimeout = 65_000;
server.headersTimeout = 66_000;
server.requestTimeout = 30_000;

Accede al servidor Node subyacente a través de app.server después de escuchar
Alinea con los tiempos de espera del proxy inverso
Consulta Keep-Alive y límites de conexión

Preguntas frecuentes

¿Es Fastify compatible con el middleware de Express?

A través de @fastify/express o middie, pero prefiere los plugins nativos de Fastify. El middleware de Express pierde los beneficios de la validación de esquemas.

¿Fastify vs Express para nuevos proyectos?

Fastify para rendimiento y APIs schema-first. Express para máximo ecosistema y familiaridad del equipo. Consulta Fastify vs Express ADR.

¿Fastify soporta ESM?

Sí. Fastify 5 es ESM-first. Usa import Fastify from "fastify".

¿Cómo manejo los tipos de TypeScript para los esquemas?

Usa fastify-type-provider-zod o @fastify/type-provider-typebox para tipos inferidos de esquemas.

¿Puede NestJS usar Fastify?

Sí. NestFactory.create(AppModule, new FastifyAdapter()). Consulta Conceptos básicos de NestJS.

Relacionado

Validación de esquemas JSON - esquemas de solicitud/respuesta
Plugins de Fastify - autocarga y encapsulamiento
Registro con Pino - registro estructurado
Conceptos básicos de Express - framework alternativo
Mejores prácticas de Fastify - lista de verificación de la sección

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.

Prerrequisitos

mkdir fastify-api && cd fastify-api
npm init -y
npm pkg set type=module
npm install fastify@5
npm install -D typescript@5.6 tsx

Para la validación de esquemas y patrones de plugins, consulta Validación de esquemas JSON y Plugins de Fastify.

Ejemplos básicos

1. Servidor "Hola Mundo"

import Fastify from "fastify";
 
const app = Fastify({ logger: true });
 
app.get("/", async () => {
  return { message: "Hello from Fastify 5" };
});
 
await app.listen({ port: 3000, host: "0.0.0.0" });

Devuelve objetos de los manejadores; Fastify los serializa a JSON automáticamente
logger: true habilita Pino con valores predeterminados sensatos
Usa await app.listen() (escucha asíncrona de Fastify 5)

2. Ruta con esquema

import Fastify from "fastify";
 
const app = Fastify();
 
app.get("/users/:id", {
  schema: {
    params: {
      type: "object",
      properties: { id: { type: "string", format: "uuid" } },
      required: ["id"],
    },
    response: {
      200: {
        type: "object",
        properties: { id: { type: "string" }, name: { type: "string" } },
      },
    },
  },
}, async (req) => {
  return { id: req.params.id, name: "Ada Lovelace" };
});

El esquema valida la solicitud y compila la serialización de la respuesta
Las solicitudes no válidas devuelven 400 automáticamente
Consulta Validación de esquemas JSON para más detalles

3. POST con esquema de cuerpo

import Fastify from "fastify";
 
const app = Fastify();
 
app.post("/users", {
  schema: {
    body: {
      type: "object",
      required: ["name", "email"],
      properties: {
        name: { type: "string", minLength: 1 },
        email: { type: "string", format: "email" },
      },
    },
  },
}, async (req, reply) => {
  const { name, email } = req.body as { name: string; email: string };
  return reply.status(201).send({ id: "1", name, email });
});

reply.status(201).send() para códigos de estado explícitos
El cuerpo se valida antes de que se ejecute el manejador
TypeScript: usa herramientas de esquema a tipo o aserción en el límite

4. Encapsulamiento de plugins

import Fastify from "fastify";
 
const app = Fastify();
 
app.register(async function userRoutes(fastify) {
  fastify.get("/", async () => [{ id: 1, name: "Ada" }]);
  fastify.get("/:id", async (req) => ({ id: (req.params as { id: string }).id }));
}, { prefix: "/users" });

register crea un ámbito encapsulado
Los decoradores y hooks dentro de un plugin no se filtran a los hermanos
prefix monta todas las rutas bajo /users

5. Hooks de ciclo de vida

import Fastify from "fastify";
 
const app = Fastify({ logger: true });
 
app.addHook("onRequest", async (req) => {
  req.headers["x-request-start"] = String(Date.now());
});
 
app.addHook("onResponse", async (req, reply) => {
  const start = Number(req.headers["x-request-start"]);
  req.log.info({ duration: Date.now() - start, status: reply.statusCode });
});
 
app.get("/health", async () => ({ ok: true }));

Los hooks se ejecutan en etapas definidas del ciclo de vida
onRequest se ejecuta antes del enrutamiento; preHandler se ejecuta antes del manejador
Usa hooks para registro, autenticación y temporización

6. Manejo de errores

import Fastify from "fastify";
 
const app = Fastify();
 
app.setErrorHandler((err, _req, reply) => {
  const status = err.statusCode ?? 500;
  reply.status(status).send({
    error: status === 500 ? "Internal server error" : err.message,
  });
});
 
app.get("/fail", async () => {
  throw Object.assign(new Error("Not found"), { statusCode: 404 });
});

setErrorHandler es el manejador de errores centralizado
Adjunta statusCode a los errores para errores operacionales
Los errores de validación de los esquemas tienen statusCode: 400

7. Registro con Pino

import Fastify from "fastify";
 
const app = Fastify({
  logger: {
    level: process.env.LOG_LEVEL ?? "info",
    transport: process.env.NODE_ENV === "development"
      ? { target: "pino-pretty" }
      : undefined,
  },
});
 
app.get("/users", async (req) => {
  req.log.info({ action: "list_users" });
  return [];
});

req.log es un logger hijo con contexto de solicitud
Producción: logs JSON a stdout; envía a tu agregador de logs
Consulta Registro con Pino

Ejemplos intermedios

8. Rompiendo el encapsulamiento con fastify-plugin

import Fastify from "fastify";
import fp from "fastify-plugin";
 
const authPlugin = fp(async (fastify) => {
  fastify.decorate("authenticate", async (req: { headers: { authorization?: string } }) => {
    if (!req.headers.authorization) throw Object.assign(new Error("Unauthorized"), { statusCode: 401 });
  });
});
 
const app = Fastify();
await app.register(authPlugin);
// authenticate está disponible en todos los ámbitos

Sin fastify-plugin, los decoradores tienen un ámbito limitado al plugin que los registra
Usa fp para autenticación compartida, conexiones a bases de datos y configuración

9. Pruebas con inject()

import Fastify from "fastify";
import { test } from "node:test";
import assert from "node:assert/strict";
 
const app = Fastify();
app.get("/health", async () => ({ ok: true }));
 
test("GET /health", async () => {
  const res = await app.inject({ method: "GET", url: "/health" });
  assert.equal(res.statusCode, 200);
  assert.deepEqual(res.json(), { ok: true });
});

inject() simula HTTP sin E/S de red
Órdenes de magnitud más rápido que supertest con enlace de puerto
Consulta Pruebas de aplicaciones Fastify

10. Ajuste del tiempo de espera del servidor

import Fastify from "fastify";
 
const app = Fastify();
 
await app.listen({ port: 3000 });
 
const server = app.server;
server.keepAliveTimeout = 65_000;
server.headersTimeout = 66_000;
server.requestTimeout = 30_000;

Accede al servidor Node subyacente a través de app.server después de escuchar
Alinea con los tiempos de espera del proxy inverso
Consulta Keep-Alive y límites de conexión

Preguntas frecuentes

¿Es Fastify compatible con el middleware de Express?

A través de @fastify/express o middie, pero prefiere los plugins nativos de Fastify. El middleware de Express pierde los beneficios de la validación de esquemas.

¿Fastify vs Express para nuevos proyectos?

Fastify para rendimiento y APIs schema-first. Express para máximo ecosistema y familiaridad del equipo. Consulta Fastify vs Express ADR.

¿Fastify soporta ESM?

Sí. Fastify 5 es ESM-first. Usa import Fastify from "fastify".

¿Cómo manejo los tipos de TypeScript para los esquemas?

Usa fastify-type-provider-zod o @fastify/type-provider-typebox para tipos inferidos de esquemas.

¿Puede NestJS usar Fastify?

Sí. NestFactory.create(AppModule, new FastifyAdapter()). Consulta Conceptos básicos de NestJS.

Relacionado

Validación de esquemas JSON - esquemas de solicitud/respuesta
Plugins de Fastify - autocarga y encapsulamiento
Registro con Pino - registro estructurado
Conceptos básicos de Express - framework alternativo
Mejores prácticas de Fastify - lista de verificación de la sección

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.

Conceptos básicos de Fastify

Buscar en la documentación

Conceptos básicos de Fastify