Serveur HTTP Node.js : http.createServer avec exemples

http.createServer() crée un serveur web à partir d'une fonction, le handler de requêtes, que Node appelle à chaque requête entrante avec deux objets : req (la méthode, l'URL et les en-têtes envoyés par le client) et res (ce que vous renvoyez). Définissez un code de statut et des en-têtes sur res, puis appelez res.end() avec le corps. server.listen(3000) commence à accepter les connexions sur le port 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 première requête répond You asked for GET /hello?name=Ada, et la Console affiche la même méthode et la même URL. Envoyez DELETE /anything depuis la barre de requête : le même handler y répond, car un serveur http simple n'a pas de routes. Toutes les requêtes passent par cette unique fonction.

Envoyer du JSON et définir le code de statut

res.writeHead(status, headers) définit le code de statut et les en-têtes en un seul appel. Pour du JSON, définissez Content-Type: application/json et envoyez le résultat de JSON.stringify() ; res.end() n'accepte qu'une chaîne ou 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 renvoie [{"id":1,"name":"Ada"}]. req.url contient le chemin plus la query string, donc new URL(req.url, 'http://localhost') le sépare en pathname et searchParams (la base n'est là que parce que URL a besoin d'une adresse absolue). Envoyez GET /nothing et le statut passe à 404.

Router les requêtes avec un switch

Une petite API n'a besoin de rien de plus qu'un switch sur la méthode et le chemin. Construisez une clé comme 'GET /users' et donnez à chaque route son propre 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);

Envoyez POST /users avec le corps {"name": "Grace"} : la réponse est 201 avec {"id":2,"name":"Grace"}, et GET /users liste maintenant les deux utilisateurs. Envoyez le même POST avec le corps hello et vous obtenez 400 avec {"error":"Body must be JSON"}.

Lire un corps POST

Node ne parse pas le corps pour vous. req est un stream lisible, et le corps arrive par morceaux via les événements data, puis end se déclenche quand il est complet. readBody() ci-dessus rassemble les morceaux dans une chaîne et renvoie une promesse, pour que le handler puisse l'attendre avec await. Comme req est un itérable asynchrone, cette boucle fait le même travail :

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

Un vrai serveur limite aussi la taille (arrêter la lecture et répondre 413 dès que data.length dépasse une limite) et vérifie req.headers['content-type'] avant d'appeler JSON.parse.

Erreurs fréquentes

Oublier res.end(). Une branche qui définit un statut sans jamais terminer la réponse laisse le client attendre jusqu'au timeout.

Définir un en-tête après le corps. Une fois que res.end() ou le premier res.write() s'est exécuté, les en-têtes sont envoyés, et res.setHeader() lève ERR_HTTP_HEADERS_SENT. Utilisez return quand vous envoyez une réponse plus tôt, comme dans les exemples.

Comparer req.url avec un chemin. req.url contient la query string, donc req.url === '/users' est faux pour /users?limit=1. Comparez pathname.

Quand utiliser Express à la place

Le module http suffit pour un health check, un récepteur de webhooks ou pour comprendre comment fonctionne HTTP. Dès que vous avez besoin de paramètres de route comme /users/:id, du parsing de corps JSON, de middlewares et de gestion des erreurs, vous finissez par écrire votre propre petit framework. Express est ce framework, construit sur les mêmes objets req et res ; le routing Express montre la même API avec app.get() et app.post().