Servidor HTTP en Node.js: http.createServer con ejemplos

http.createServer() crea un servidor web a partir de una función, el request handler, que Node llama en cada petición entrante con dos objetos: req (el método, la URL y los headers que envió el cliente) y res (lo que devuelves). Pon un status code y headers en res, y luego llama a res.end() con el body. server.listen(3000) empieza a aceptar conexiones en el puerto 3000.

const http = require('http');

const server = http.createServer((req, res) => {
    console.log(req.method, req.url);
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain');
    res.end(`You asked for ${req.method} ${req.url}`);
});

// GET /hello?name=Ada
server.listen(3000, () => {
    console.log('Listening on port 3000');
});

La primera petición responde You asked for GET /hello?name=Ada, y la Console registra el mismo método y la misma URL. Envía DELETE /anything desde la barra de petición: responde el mismo handler, porque un servidor http a pelo no tiene rutas. Todas las peticiones pasan por esa única función.

Enviar JSON y definir el status code

res.writeHead(status, headers) define el status code y los headers en una sola llamada. Para JSON, pon Content-Type: application/json y envía el resultado de JSON.stringify(); res.end() solo acepta un string o un Buffer.

const http = require('http');

const users = [
    { id: 1, name: 'Ada' },
    { id: 2, name: 'Linus' },
];

function sendJson(res, status, data) {
    res.writeHead(status, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(data));
}

const server = http.createServer((req, res) => {
    const url = new URL(req.url, 'http://localhost');
    const limit = Number(url.searchParams.get('limit')) || users.length;

    if (req.method === 'GET' && url.pathname === '/users') {
        return sendJson(res, 200, users.slice(0, limit));
    }
    sendJson(res, 404, { error: 'Not found' });
});

// GET /users?limit=1
server.listen(3000);

GET /users?limit=1 devuelve [{"id":1,"name":"Ada"}]. req.url es la ruta más el query string, así que new URL(req.url, 'http://localhost') lo separa en pathname y searchParams (la base solo está ahí porque URL necesita una dirección absoluta). Envía GET /nothing y el status pasa a 404.

Enrutar peticiones con un switch

Una API pequeña no necesita más que un switch sobre el método y la ruta. Construye una clave como 'GET /users' y dale a cada ruta su propio case:

const http = require('http');

const users = [{ id: 1, name: 'Ada' }];

function sendJson(res, status, data) {
    res.writeHead(status, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify(data));
}

function readBody(req) {
    return new Promise((resolve, reject) => {
        let data = '';
        req.on('data', (chunk) => {
            data += chunk;
        });
        req.on('end', () => resolve(data));
        req.on('error', reject);
    });
}

const server = http.createServer(async (req, res) => {
    const { pathname } = new URL(req.url, 'http://localhost');

    switch (`${req.method} ${pathname}`) {
        case 'GET /users':
            return sendJson(res, 200, users);

        case 'POST /users': {
            let body;
            try {
                body = JSON.parse(await readBody(req));
            } catch {
                return sendJson(res, 400, { error: 'Body must be JSON' });
            }
            const user = { id: users.length + 1, name: body.name };
            users.push(user);
            return sendJson(res, 201, user);
        }

        default:
            sendJson(res, 404, { error: `No route for ${req.method} ${pathname}` });
    }
});

// GET /users
server.listen(3000);

Envía POST /users con el body {"name": "Grace"}: la respuesta es 201 con {"id":2,"name":"Grace"}, y GET /users ahora lista los dos usuarios. Envía el mismo POST con el body hello y obtienes 400 con {"error":"Body must be JSON"}.

Leer el body de un POST

Node no parsea el body por ti. req es un stream de lectura, y el body llega por trozos mediante eventos data, y después se dispara end cuando está completo. readBody() de arriba junta los trozos en un string y devuelve una promesa, para que el handler pueda hacer await. Como req es iterable de forma asíncrona, este bucle hace el mismo trabajo:

let data = '';
for await (const chunk of req) data += chunk;
const body = JSON.parse(data);

Un servidor real además limita el tamaño (deja de leer y responde 413 cuando data.length pasa de un límite) y comprueba req.headers['content-type'] antes de llamar a JSON.parse.

Errores comunes

Olvidar res.end(). Una rama que define un status pero nunca termina la respuesta deja al cliente esperando hasta que se agota el tiempo.

Definir un header después del body. Cuando ya se ha ejecutado res.end() o el primer res.write(), los headers se han enviado, y res.setHeader() lanza ERR_HTTP_HEADERS_SENT. Usa return cuando envíes una respuesta antes de tiempo, como hacen los ejemplos.

Comparar req.url con una ruta. req.url incluye el query string, así que req.url === '/users' es false para /users?limit=1. Compara pathname.

Cuándo usar Express

El módulo http basta para un health check, un receptor de webhooks o para aprender cómo funciona HTTP. En cuanto necesitas parámetros de ruta como /users/:id, parseo del body JSON, middleware y manejo de errores, acabas escribiendo tu propio framework pequeño. Express es ese framework, construido sobre los mismos objetos req y res; el routing en Express muestra la misma API con app.get() y app.post().