Conceptos básicos de HTTP en Node

Q: ¿Por qué mi servidor se cuelga después de enviar una respuesta?

Probablemente olvidaste res.end() o lo llamaste dos veces. Cada solicitud necesita exactamente una respuesta terminal. Verifica los caminos del código que no terminan sin finalizar.

Q: ¿Cuál es la diferencia entre writeHead y setHeader?

writeHead envía el estado y los encabezados inmediatamente. setHeader pone en cola los encabezados hasta la primera write o end. Mezclarlos después de que comienzan las escrituras lanza ERR_HTTP_HEADERS_SENT.

Q: ¿Cómo manejo CORS en HTTP sin procesar?

Establece Access-Control-Allow-Origin y maneja la pre-solicitud OPTIONS manualmente, o usa un middleware de framework. Consulta Middleware de seguridad.

10 ejemplos para entender HTTP en Node.js con http.createServer - 7 básicos y 3 intermedios.

Prerrequisitos

Estos ejemplos asumen Node.js 24.18.0 (LTS activa) y TypeScript 5.6+ con ESM ("type": "module" en package.json).

mkdir http-basics-spike && cd http-basics-spike
npm init -y
npm pkg set type=module
npm install -D typescript@5.6 tsx @types/node

Para patrones a nivel de framework construidos sobre esta base, consulta Patrón de Middleware y Conceptos básicos de Express.

Ejemplos básicos

1. Servidor HTTP mínimo

Todo servidor HTTP de Node comienza con http.createServer y un manejador de solicitudes.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello from Node HTTP\n");
});
 
server.listen(3000, () => {
  console.log("Escuchando en http://localhost:3000");
});

req es un IncomingMessage con method, url y headers
res es un ServerResponse: debes llamar a res.end() o el cliente esperará indefinidamente
writeHead establece el estado y los encabezados en una sola llamada; úsalo antes de la primera write

Relacionado: Enrutamiento sin frameworks - coincide rutas sin Express

2. Lectura del método y la URL de la solicitud

Enruta inspeccionando req.method y analizando req.url.

import { createServer } from "node:http";
import { parse } from "node:url";
 
const server = createServer((req, res) => {
  const { pathname } = parse(req.url ?? "/", true);
 
  if (req.method === "GET" && pathname === "/health") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ status: "ok" }));
    return;
  }
 
  res.writeHead(404, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ error: "Not found" }));
});

req.url incluye la cadena de consulta; usa URL o parse de node:url para la ruta
Retorna temprano después de enviar una respuesta para evitar escrituras dobles
Frameworks como Express ocultan este análisis detrás de req.path y req.query

3. Lectura de encabezados de solicitud

Los encabezados llegan en minúsculas en Node 24. Accede a ellos a través de req.headers.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  const contentType = req.headers["content-type"] ?? "none";
  const userAgent = req.headers["user-agent"] ?? "unknown";
 
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ contentType, userAgent }));
});

Los nombres de los encabezados se convierten automáticamente a minúsculas
Los encabezados duplicados se unen con , en un único valor de cadena
Nunca confíes en X-Forwarded-For sin configuración de proxy; consulta Conciencia de proxy inverso

4. Envío de respuestas JSON

Establece Content-Type: application/json y convierte tu carga útil a cadena.

import { createServer } from "node:http";
 
const users = [{ id: 1, name: "Ada" }];
 
const server = createServer((req, res) => {
  res.writeHead(200, {
    "Content-Type": "application/json; charset=utf-8",
  });
  res.end(JSON.stringify({ data: users }));
});

Siempre incluye charset=utf-8 para JSON con texto no ASCII
Usa JSON.stringify con un reemplazador para fechas: date.toISOString()
Los serializadores de frameworks (Fastify) compilan esquemas JSON para mayor velocidad

5. Lectura de un cuerpo de solicitud JSON

Recopila fragmentos de data del flujo de solicitud y luego analiza.

import { createServer } from "node:http";
 
async function readBody(req: import("node:http").IncomingMessage): Promise<string> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) {
    chunks.push(chunk as Buffer);
  }
  return Buffer.concat(chunks).toString("utf8");
}
 
const server = createServer(async (req, res) => {
  if (req.method !== "POST") {
    res.writeHead(405).end();
    return;
  }
 
  try {
    const body = JSON.parse(await readBody(req));
    res.writeHead(201, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ received: body }));
  } catch {
    res.writeHead(400, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "Invalid JSON" }));
  }
});

Los cuerpos de las solicitudes son flujos; léelos asincrónicamente
Establece un límite de tamaño antes de concatenar fragmentos (requisito de producción)
express.json() de Express y el analizador integrado de Fastify manejan esto con límites

6. Establecimiento de códigos de estado de respuesta

Usa códigos de estado significativos; los clientes y los balanceadores de carga dependen de ellos.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  if (req.method === "GET" && req.url === "/users/999") {
    res.writeHead(404, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "User not found" }));
    return;
  }
 
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ id: 1, name: "Ada" }));
});

Código	Significado	Cuándo usar
200	OK	GET, PUT, PATCH exitosos
201	Creado	POST exitoso que creó un recurso
400	Solicitud incorrecta	Fallo de validación, entrada mal formada
404	No encontrado	El recurso no existe
500	Error interno	Excepción no manejada (regístrala, no filtres detalles)

7. Apagado elegante del servidor

Cierra el servidor en SIGTERM para que las solicitudes en curso finalicen.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("ok\n");
});
 
server.listen(3000);
 
function shutdown() {
  console.log("Apagando...");
  server.close(() => {
    console.log("Servidor cerrado");
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 10_000).unref();
}
 
process.on("SIGTERM", shutdown);
process.on("SIGINT", shutdown);

server.close() deja de aceptar nuevas conexiones pero permite que las solicitudes activas se completen
Establece un tiempo de espera de salida forzada para que un manejador atascado no bloquee las implementaciones indefinidamente
Kubernetes envía SIGTERM antes de eliminar los pods del servicio

Ejemplos intermedios

8. Tiempos de espera del servidor

Evita que los clientes lentos mantengan las conexiones abiertas indefinidamente.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("ok\n");
});
 
server.requestTimeout = 30_000;      // 30s por solicitud
server.headersTimeout = 35_000;      // debe exceder requestTimeout
server.keepAliveTimeout = 5_000;     // tiempo de espera de socket keep-alive inactivo
server.listen(3000);

requestTimeout (Node 18+) destruye las solicitudes que exceden el límite
headersTimeout debe ser mayor que requestTimeout
Ajusta keepAliveTimeout para que coincida con tu proxy inverso; consulta Keep-Alive y límites de conexión

9. Transmisión de una respuesta de archivo

Transmite archivos grandes en lugar de leerlos en memoria.

import { createServer } from "node:http";
import { createReadStream } from "node:fs";
import { stat } from "node:fs/promises";
import { join } from "node:path";
 
const server = createServer(async (req, res) => {
  const filePath = join(process.cwd(), "public", "report.pdf");
 
  try {
    const info = await stat(filePath);
    res.writeHead(200, {
      "Content-Type": "application/pdf",
      "Content-Length": info.size,
    });
    createReadStream(filePath).pipe(res);
  } catch {
    res.writeHead(404).end();
  }
});

pipe maneja la contrapresión automáticamente
Establece Content-Length cuando se conoce para mejores indicadores de progreso del cliente
Maneja los eventos error en el flujo de lectura para evitar respuestas colgadas

10. HTTPS con `node:https`

Envuelve el mismo patrón de manejador en https.createServer con certificados TLS.

import { createServer as createHttpsServer } from "node:https";
import { readFileSync } from "node:fs";
 
const server = createHttpsServer(
  {
    key: readFileSync("certs/key.pem"),
    cert: readFileSync("certs/cert.pem"),
  },
  (req, res) => {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("HTTPS ok\n");
  }
);
 
server.listen(3443);

En producción, termina TLS en nginx, ALB o Cloudflare; Node maneja HTTP detrás del proxy
Para desarrollo local, usa mkcert o los certificados de desarrollo de tu plataforma
HTTP/2 y HTTP/3 se manejan típicamente en la capa de proxy; consulta Consideraciones de HTTP/2 y HTTP/3

Preguntas frecuentes

¿Necesito usar el módulo `http` sin procesar en producción?

Raramente para APIs de aplicaciones. Usa Express, Fastify o NestJS para enrutamiento, análisis y middleware. Conoce el módulo sin procesar para depuración, sidecars de verificación de estado y para entender lo que los frameworks abstraen.

¿Por qué mi servidor se cuelga después de enviar una respuesta?

Probablemente olvidaste res.end() o lo llamaste dos veces. Cada solicitud necesita exactamente una respuesta terminal. Verifica los caminos del código que no terminan sin finalizar.

¿Los manejadores deben ser `async`?

Sí para E/S, pero las promesas rechazadas no manejadas en los manejadores http sin procesar no se capturan automáticamente. Envuelve en try/catch o usa un framework que maneje errores asíncronos (Express 5 lo hace).

¿Cuál es la diferencia entre `writeHead` y `setHeader`?

writeHead envía el estado y los encabezados inmediatamente. setHeader pone en cola los encabezados hasta la primera write o end. Mezclarlos después de que comienzan las escrituras lanza ERR_HTTP_HEADERS_SENT.

¿Cómo manejo CORS en HTTP sin procesar?

Establece Access-Control-Allow-Origin y maneja la pre-solicitud OPTIONS manualmente, o usa un middleware de framework. Consulta Middleware de seguridad.

Relacionado

Enrutamiento sin frameworks - Coincidencia de URL sin Express
Patrón de Middleware - Pipelines de solicitud componibles
Keep-Alive y límites de conexión - Ajuste de conexión
Conceptos básicos de Express - La capa de framework más común
Mejores prácticas de fundamentos HTTP - 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

Estos ejemplos asumen Node.js 24.18.0 (LTS activa) y TypeScript 5.6+ con ESM ("type": "module" en package.json).

mkdir http-basics-spike && cd http-basics-spike
npm init -y
npm pkg set type=module
npm install -D typescript@5.6 tsx @types/node

Para patrones a nivel de framework construidos sobre esta base, consulta Patrón de Middleware y Conceptos básicos de Express.

Ejemplos básicos

1. Servidor HTTP mínimo

Todo servidor HTTP de Node comienza con http.createServer y un manejador de solicitudes.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello from Node HTTP\n");
});
 
server.listen(3000, () => {
  console.log("Escuchando en http://localhost:3000");
});

req es un IncomingMessage con method, url y headers
res es un ServerResponse: debes llamar a res.end() o el cliente esperará indefinidamente
writeHead establece el estado y los encabezados en una sola llamada; úsalo antes de la primera write

Relacionado: Enrutamiento sin frameworks - coincide rutas sin Express

2. Lectura del método y la URL de la solicitud

Enruta inspeccionando req.method y analizando req.url.

import { createServer } from "node:http";
import { parse } from "node:url";
 
const server = createServer((req, res) => {
  const { pathname } = parse(req.url ?? "/", true);
 
  if (req.method === "GET" && pathname === "/health") {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ status: "ok" }));
    return;
  }
 
  res.writeHead(404, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ error: "Not found" }));
});

req.url incluye la cadena de consulta; usa URL o parse de node:url para la ruta
Retorna temprano después de enviar una respuesta para evitar escrituras dobles
Frameworks como Express ocultan este análisis detrás de req.path y req.query

3. Lectura de encabezados de solicitud

Los encabezados llegan en minúsculas en Node 24. Accede a ellos a través de req.headers.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  const contentType = req.headers["content-type"] ?? "none";
  const userAgent = req.headers["user-agent"] ?? "unknown";
 
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ contentType, userAgent }));
});

Los nombres de los encabezados se convierten automáticamente a minúsculas
Los encabezados duplicados se unen con , en un único valor de cadena
Nunca confíes en X-Forwarded-For sin configuración de proxy; consulta Conciencia de proxy inverso

4. Envío de respuestas JSON

Establece Content-Type: application/json y convierte tu carga útil a cadena.

import { createServer } from "node:http";
 
const users = [{ id: 1, name: "Ada" }];
 
const server = createServer((req, res) => {
  res.writeHead(200, {
    "Content-Type": "application/json; charset=utf-8",
  });
  res.end(JSON.stringify({ data: users }));
});

Siempre incluye charset=utf-8 para JSON con texto no ASCII
Usa JSON.stringify con un reemplazador para fechas: date.toISOString()
Los serializadores de frameworks (Fastify) compilan esquemas JSON para mayor velocidad

5. Lectura de un cuerpo de solicitud JSON

Recopila fragmentos de data del flujo de solicitud y luego analiza.

import { createServer } from "node:http";
 
async function readBody(req: import("node:http").IncomingMessage): Promise<string> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) {
    chunks.push(chunk as Buffer);
  }
  return Buffer.concat(chunks).toString("utf8");
}
 
const server = createServer(async (req, res) => {
  if (req.method !== "POST") {
    res.writeHead(405).end();
    return;
  }
 
  try {
    const body = JSON.parse(await readBody(req));
    res.writeHead(201, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ received: body }));
  } catch {
    res.writeHead(400, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "Invalid JSON" }));
  }
});

Los cuerpos de las solicitudes son flujos; léelos asincrónicamente
Establece un límite de tamaño antes de concatenar fragmentos (requisito de producción)
express.json() de Express y el analizador integrado de Fastify manejan esto con límites

6. Establecimiento de códigos de estado de respuesta

Usa códigos de estado significativos; los clientes y los balanceadores de carga dependen de ellos.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  if (req.method === "GET" && req.url === "/users/999") {
    res.writeHead(404, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ error: "User not found" }));
    return;
  }
 
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ id: 1, name: "Ada" }));
});

Código	Significado	Cuándo usar
200	OK	GET, PUT, PATCH exitosos
201	Creado	POST exitoso que creó un recurso
400	Solicitud incorrecta	Fallo de validación, entrada mal formada
404	No encontrado	El recurso no existe
500	Error interno	Excepción no manejada (regístrala, no filtres detalles)

7. Apagado elegante del servidor

Cierra el servidor en SIGTERM para que las solicitudes en curso finalicen.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("ok\n");
});
 
server.listen(3000);
 
function shutdown() {
  console.log("Apagando...");
  server.close(() => {
    console.log("Servidor cerrado");
    process.exit(0);
  });
  setTimeout(() => process.exit(1), 10_000).unref();
}
 
process.on("SIGTERM", shutdown);
process.on("SIGINT", shutdown);

server.close() deja de aceptar nuevas conexiones pero permite que las solicitudes activas se completen
Establece un tiempo de espera de salida forzada para que un manejador atascado no bloquee las implementaciones indefinidamente
Kubernetes envía SIGTERM antes de eliminar los pods del servicio

Ejemplos intermedios

8. Tiempos de espera del servidor

Evita que los clientes lentos mantengan las conexiones abiertas indefinidamente.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("ok\n");
});
 
server.requestTimeout = 30_000;      // 30s por solicitud
server.headersTimeout = 35_000;      // debe exceder requestTimeout
server.keepAliveTimeout = 5_000;     // tiempo de espera de socket keep-alive inactivo
server.listen(3000);

requestTimeout (Node 18+) destruye las solicitudes que exceden el límite
headersTimeout debe ser mayor que requestTimeout
Ajusta keepAliveTimeout para que coincida con tu proxy inverso; consulta Keep-Alive y límites de conexión

9. Transmisión de una respuesta de archivo

Transmite archivos grandes en lugar de leerlos en memoria.

import { createServer } from "node:http";
import { createReadStream } from "node:fs";
import { stat } from "node:fs/promises";
import { join } from "node:path";
 
const server = createServer(async (req, res) => {
  const filePath = join(process.cwd(), "public", "report.pdf");
 
  try {
    const info = await stat(filePath);
    res.writeHead(200, {
      "Content-Type": "application/pdf",
      "Content-Length": info.size,
    });
    createReadStream(filePath).pipe(res);
  } catch {
    res.writeHead(404).end();
  }
});

pipe maneja la contrapresión automáticamente
Establece Content-Length cuando se conoce para mejores indicadores de progreso del cliente
Maneja los eventos error en el flujo de lectura para evitar respuestas colgadas

10. HTTPS con `node:https`

Envuelve el mismo patrón de manejador en https.createServer con certificados TLS.

import { createServer as createHttpsServer } from "node:https";
import { readFileSync } from "node:fs";
 
const server = createHttpsServer(
  {
    key: readFileSync("certs/key.pem"),
    cert: readFileSync("certs/cert.pem"),
  },
  (req, res) => {
    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("HTTPS ok\n");
  }
);
 
server.listen(3443);

En producción, termina TLS en nginx, ALB o Cloudflare; Node maneja HTTP detrás del proxy
Para desarrollo local, usa mkcert o los certificados de desarrollo de tu plataforma
HTTP/2 y HTTP/3 se manejan típicamente en la capa de proxy; consulta Consideraciones de HTTP/2 y HTTP/3

Preguntas frecuentes

¿Necesito usar el módulo `http` sin procesar en producción?

¿Por qué mi servidor se cuelga después de enviar una respuesta?

Probablemente olvidaste res.end() o lo llamaste dos veces. Cada solicitud necesita exactamente una respuesta terminal. Verifica los caminos del código que no terminan sin finalizar.

¿Los manejadores deben ser `async`?

¿Cuál es la diferencia entre `writeHead` y `setHeader`?

¿Cómo manejo CORS en HTTP sin procesar?

Establece Access-Control-Allow-Origin y maneja la pre-solicitud OPTIONS manualmente, o usa un middleware de framework. Consulta Middleware de seguridad.

Relacionado

Enrutamiento sin frameworks - Coincidencia de URL sin Express
Patrón de Middleware - Pipelines de solicitud componibles
Keep-Alive y límites de conexión - Ajuste de conexión
Conceptos básicos de Express - La capa de framework más común
Mejores prácticas de fundamentos HTTP - 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 HTTP en Node

Buscar en la documentación

Conceptos básicos de HTTP en Node