Server HTTP in Node.js: http.createServer con esempi

http.createServer() crea un web server a partire da una funzione, il request handler, che Node chiama per ogni richiesta in arrivo con due oggetti: req (metodo, URL e header inviati dal client) e res (quello che rimandi indietro). Imposta uno status code e degli header su res, poi chiama res.end() con il body. server.listen(3000) inizia ad accettare connessioni sulla porta 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 prima richiesta risponde You asked for GET /hello?name=Ada, e la Console mostra lo stesso metodo e lo stesso URL. Invia DELETE /anything dalla barra della richiesta: risponde lo stesso handler, perché un server http semplice non ha route. Ogni richiesta passa per quell'unica funzione.

Inviare JSON e impostare lo status code

res.writeHead(status, headers) imposta status code e header in una sola chiamata. Per il JSON imposta Content-Type: application/json e invia il risultato di JSON.stringify(); res.end() accetta solo una stringa 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 restituisce [{"id":1,"name":"Ada"}]. req.url è il path più la query string, quindi new URL(req.url, 'http://localhost') lo divide in pathname e searchParams (la base c'è solo perché URL ha bisogno di un indirizzo assoluto). Invia GET /nothing e lo status diventa 404.

Instradare le richieste con uno switch

A una piccola API basta uno switch su metodo e path. Costruisci una chiave come 'GET /users' e dai a ogni route il suo 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);

Invia POST /users con il body {"name": "Grace"}: la risposta è 201 con {"id":2,"name":"Grace"}, e ora GET /users elenca entrambi gli utenti. Invia la stessa POST con il body hello e ottieni 400 con {"error":"Body must be JSON"}.

Leggere un body POST

Node non fa il parsing del body al posto tuo. req è uno stream leggibile, e il body arriva a pezzi tramite gli eventi data, poi scatta end quando è completo. readBody() qui sopra raccoglie i pezzi in una stringa e restituisce una promise, così l'handler può fare await. Dato che req è un async iterable, questo ciclo fa lo stesso lavoro:

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

Un server vero limita anche la dimensione (smette di leggere e risponde 413 appena data.length supera un limite) e controlla req.headers['content-type'] prima di chiamare JSON.parse.

Errori comuni

Dimenticare res.end(). Un ramo che imposta uno status ma non chiude mai la risposta lascia il client in attesa fino al timeout.

Impostare un header dopo il body. Quando res.end() o il primo res.write() sono stati eseguiti, gli header sono già partiti, e res.setHeader() lancia ERR_HTTP_HEADERS_SENT. Usa return quando invii una risposta in anticipo, come negli esempi.

Confrontare req.url con un path. req.url include la query string, quindi req.url === '/users' è falso per /users?limit=1. Confronta pathname.

Quando usare Express

Il modulo http basta per un health check, un ricevitore di webhook o per capire come funziona HTTP. Quando ti servono parametri di route come /users/:id, parsing del body JSON, middleware e gestione degli errori, finisci per scrivere un tuo piccolo framework. Express è quel framework, costruito sugli stessi oggetti req e res; il routing di Express mostra la stessa API con app.get() e app.post().