Introduction
Koa.js est un framework Node.js minimaliste créé par l'équipe derrière Express. Il mise sur les générateurs et async/await pour un code plus propre et lisible. Contrairement à Express, Koa ne vient pas avec un routeur intégré ni de gestion d'erreurs par défaut, ce qui vous laisse une totale liberté. Ce tutoriel intermédiaire vous guide dans la création d'une API REST complète : du serveur de base jusqu'à la gestion avancée des erreurs et middlewares. Vous apprendrez à structurer un projet professionnel tout en évitant les pièges classiques des applications asynchrones.
Prérequis
- Node.js 20+
- Connaissances de base en JavaScript moderne et async/await
- npm ou yarn installé
- Un éditeur de code (VS Code recommandé)
Initialisation du projet
mkdir koa-api-2026 && cd koa-api-2026
npm init -y
npm install koa koa-router @koa/cors dotenv
npm install --save-dev nodemonOn initialise le projet et installe Koa avec son routeur officiel, le middleware CORS et dotenv pour les variables d'environnement. Nodemon facilite le développement en redémarrant automatiquement le serveur.
Création du serveur de base
import Koa from 'koa';
import dotenv from 'dotenv';
dotenv.config();
const app = new Koa();
const PORT = process.env.PORT || 3000;
app.use(async (ctx) => {
ctx.body = { message: 'API Koa opérationnelle' };
});
app.listen(PORT, () => {
console.log(`Serveur démarré sur le port ${PORT}`);
});Ce fichier crée une instance Koa minimale. Le middleware par défaut répond à toutes les requêtes. Nous utiliserons des fichiers séparés pour le routage dans les étapes suivantes.
Configuration du routage
import Router from 'koa-router';
const router = new Router({ prefix: '/api/users' });
router.get('/', async (ctx) => {
ctx.body = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
});
router.get('/:id', async (ctx) => {
ctx.body = { id: ctx.params.id, name: 'Utilisateur ' + ctx.params.id };
});
export default router;Nous créons un routeur avec un préfixe et deux routes GET. ctx.params permet de récupérer les paramètres d'URL de façon simple et lisible.
Intégration des middlewares
import Koa from 'koa';
import Router from 'koa-router';
import cors from '@koa/cors';
import usersRouter from './routes/users.js';
const app = new Koa();
const router = new Router();
app.use(cors());
app.use(async (ctx, next) => {
const start = Date.now();
await next();
const ms = Date.now() - start;
ctx.set('X-Response-Time', `${ms}ms`);
});
router.use(usersRouter.routes());
app.use(router.routes());
app.use(router.allowedMethods());
export default app;Les middlewares sont exécutés dans l'ordre d'ajout. Le middleware de timing mesure la durée de chaque requête. Nous branchons ensuite les routes utilisateurs.
Gestion centralisée des erreurs
export default async function errorHandler(ctx, next) {
try {
await next();
} catch (err) {
ctx.status = err.status || 500;
ctx.body = {
success: false,
message: err.message || 'Erreur interne du serveur'
};
ctx.app.emit('error', err, ctx);
}
}Ce middleware intercepte toutes les erreurs, renvoie une réponse JSON cohérente et émet l'événement d'erreur pour un logging centralisé.
Bonnes pratiques
- Toujours placer le middleware de gestion d'erreurs en premier
- Utiliser des préfixes de route pour organiser l'API
- Valider les données d'entrée avec un schéma (ex: Joi ou Zod)
- Séparer les routes, middlewares et contrôleurs dans des fichiers distincts
- Logger les erreurs avec un outil structuré comme Winston ou Pino
Erreurs courantes à éviter
- Oublier d'appeler await next() dans un middleware (bloque la chaîne)
- Ne pas gérer les erreurs asynchrones (promesses rejetées non capturées)
- Utiliser ctx.throw sans statut HTTP approprié
- Installer trop de middlewares globaux qui ralentissent toutes les requêtes
Pour aller plus loin
Découvrez nos formations avancées sur les frameworks Node.js modernes et les architectures d'API : https://learni-group.com/formations