TypeStack/routing-controllers pour TypeScript : guide complet avec exemples

1. Qu'est-ce que c'est et pourquoi l'utiliser ?

TypeStack/routing-controllers est une bibliothèque TypeScript puissante qui permet de créer des applications serveur Node.js en utilisant des décorateurs. Elle offre une manière déclarative de définir les routes, les middleware, la validation et la sérialisation des données. Au lieu d'écrire manuellement des gestionnaires pour chaque requête HTTP et de les lier à Express ou Koa, il vous suffit d'annoter vos classes et méthodes avec des décorateurs, et la bibliothèque génère automatiquement toute l'infrastructure nécessaire.

Pourquoi l'utiliser ? Dans le développement web moderne avec TypeScript, la duplication de code et la complexité de maintenance des grands projets sont des problèmes courants. routing-controllers résout cela en proposant une architecture propre et modulaire, basée sur les classes et les décorateurs. Cela rend le code plus lisible, testable et évolutif. Vous pouvez facilement réutiliser des middleware, valider les données entrantes avec class-validator et générer automatiquement une documentation OpenAPI (Swagger).

La bibliothèque s'intègre étroitement avec des frameworks populaires comme Express et Koa, et fait partie de l'écosystème TypeStack, qui inclut également class-validator, class-transformer et typedi. Cela permet de construire des applications backend complètes avec injection de dépendances, validation et transformation de données prêtes à l'emploi.

2. Installation

Pour installer la bibliothèque et ses dépendances, exécutez les commandes suivantes dans le terminal de votre projet :

npm install routing-controllers reflect-metadata

Vous aurez également besoin d'installer l'un des frameworks HTTP pris en charge. Express ou Koa sont recommandés :

npm install express
npm install @types/express --save-dev

Ou pour Koa :

npm install koa
npm install @types/koa --save-dev

N'oubliez pas d'activer les décorateurs expérimentaux dans votre fichier tsconfig.json :

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES6",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  }
}

3. Démarrage rapide — exemple minimal fonctionnel

Créez un fichier app.ts avec le contenu suivant :

import 'reflect-metadata';
import { createExpressServer, Get, Controller, Res } from 'routing-controllers';
import { Response } from 'express';

@Controller()
class UserController {
    @Get('/users')
    getAll(@Res() response: Response) {
        return response.json([{ id: 1, name: 'John Doe' }]);
    }
}

const app = createExpressServer({
    controllers: [UserController],
});

app.listen(3000, () => {
    console.log('Le serveur tourne sur http://localhost:3000');
});

Lancez le serveur avec la commande npx ts-node app.ts et ouvrez http://localhost:3000/users dans votre navigateur. Vous verrez une réponse JSON contenant un tableau d'utilisateurs.

4. Méthodes/fonctions/classes principales

4.1 @Controller

Signature : @Controller(basePath?: string)

Fonction : Décorateur de classe qui marque une classe comme contrôleur. Prend un chemin de base optionnel qui sera ajouté à toutes les routes de la classe.

Exemple concret :

@Controller('/api')
class ApiController {
    @Get('/status')
    getStatus() {
        return { status: 'OK' };
    }
}
// Route : GET /api/status

4.2 @Get, @Post, @Put, @Delete, @Patch

Signature :