Les contrôleurs NestJS

Le rôle d'un contrôleur

Un contrôleur est le guichet HTTP d'une ressource. Il reçoit les requêtes qui la concernent (/formations, /stagiaires…), en extrait les données utiles (paramètres, corps, en-têtes), appelle le service approprié et renvoie le résultat. NestJS se charge du reste : choisir la bonne méthode selon l'URL et le verbe HTTP, convertir le résultat en JSON, fixer le code de statut, transformer les exceptions en réponses d'erreur.

Préfixe, service injecté, décorateur de route, paramètre et valeur renvoyée.

Créer un contrôleur

nest g co formations            # crée src/formations/formations.controller.ts (+ .spec.ts)
nest g co formations --no-spec  # sans fichier de test
nest g co formations --flat     # directement dans src/, sans sous-dossier

La CLI crée la classe et l'ajoute automatiquement au tableau controllers du module le plus proche (formations.module.ts s'il existe, sinon app.module.ts). Un contrôleur qui n'est déclaré dans aucun module n'existe pas pour NestJS : ses routes renvoient 404.

// formations.controller.ts (généré)
import { Controller } from '@nestjs/common';

@Controller('formations')
export class FormationsController {}

// formations.module.ts
@Module({
  controllers: [FormationsController],   // ← indispensable
  providers: [FormationsService],
})
export class FormationsModule {}

Le décorateur @Controller

Par convention, le préfixe est le nom de la ressource au pluriel, en minuscules et en kebab-case (groupes-formation), et la classe porte le même nom suivi de Controller.

Ce que NestJS fait de la valeur renvoyée

Contrairement à Express, on n'écrit pas res.json(…): on renvoie une valeur, et NestJS construit la réponse. Démonstration avec un contrôleur qui renvoie toutes sortes de valeurs :

📄 src/demo.controller.ts

import { Controller, Get } from '@nestjs/common';
import { Observable, of } from 'rxjs';

@Controller('demo')
export class DemoController {
  @Get('texte')
  texte(): string {
    return 'Bonjour depuis NestJS';                 // chaîne → envoyée telle quelle
  }

  @Get('objet')
  objet() {
    return { formation: 'NestJS', heures: 120 };    // objet → JSON
  }

  @Get('tableau')
  tableau() {
    return ['DEV101', 'DEV102'];                    // tableau → JSON
  }

  @Get('nombre')
  nombre(): number {
    return 42;                                      // nombre → JSON
  }

  @Get('promesse')
  async promesse() {
    await new Promise((r) => setTimeout(r, 50));    // NestJS attend la promesse
    return { charge: true };
  }

  @Get('observable')
  observable(): Observable<string[]> {
    return of(['a', 'b']);                          // NestJS s'abonne à l'Observable
  }

  @Get('rien')
  rien(): void {}                                   // pas de valeur → réponse vide
}

Requêtes envoyées et réponses réellement obtenues :

GET /api/demo/texte → 200 Bonjour depuis NestJS  [content-type: text/html; charset=utf-8]
GET /api/demo/objet → 200 {"formation":"NestJS","heures":120}  [content-type: application/json; charset=utf-8]
GET /api/demo/tableau → 200 ["DEV101","DEV102"]  [content-type: application/json; charset=utf-8]
GET /api/demo/nombre → 200 42  [content-type: text/html; charset=utf-8]
GET /api/demo/promesse → 200 {"charge":true}  [content-type: application/json; charset=utf-8]
GET /api/demo/observable → 200 ["a","b"]  [content-type: application/json; charset=utf-8]
GET /api/demo/rien → 200  [content-type: null]

• Objets et tableaux sont convertis en JSON, avec l'en-tête Content-Type: application/json.
• Chaînes et nombres sont envoyés tels quels : le type de contenu est alors text/html. Pour une API, préférez renvoyer un objet ({ message: '…' }) : le client saura toujours qu'il reçoit du JSON.
• Une promesse (méthode async) est attendue ; un Observable RxJS est écouté jusqu'à sa dernière valeur.
• Une méthode qui ne renvoie rien produit une réponse vide avec le statut 200 (204 serait plus juste : leçon 6.5).
• Le statut est 200 par défaut, 201 pour @Post().

Et si j'ai besoin de l'objet réponse d'Express ?

On peut injecter l'objet réponse d'Express avec @Res(). Mais NestJS considère alors que vous gérez la réponse : la valeur renvoyée est ignorée, et les intercepteurs ne s'appliquent plus. Pour simplement ajouter un en-tête tout en laissant NestJS envoyer la réponse, utilisez l'option passthrough:

import type { Response } from 'express';

@Get()
findAll(@Res({ passthrough: true }) res: Response) {
  res.setHeader('X-Total-Count', '42');   // on complète la réponse…
  return this.formationsService.findAll(); // …et NestJS l'envoie normalement
}

Un contrôleur mince

Au chapitre 05, nous avons vu qu'un contrôleur ne contient ni calcul ni règle métier. Chaque méthode suit le même schéma en trois temps :

1. lire les données de la requête (décorateurs de paramètre) ;
2. appeler une méthode du service ;
3. renvoyer son résultat.

@Controller('formations')
export class FormationsController {
  constructor(private readonly formationsService: FormationsService) {}

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {     // 1. lire
    return this.formationsService.findOne(id);          // 2. appeler + 3. renvoyer
  }
}

Un module peut contenir plusieurs contrôleurs (par exemple FormationsController et FormationsAdminController), qui partagent les mêmes services.

Activités

@Get('taux-occupation')
taux() {
  const salles = [{ code: 'S1', places: 24, occupees: 20 }, { code: 'S2', places: 16, occupees: 4 }];
  const total = salles.reduce((t, s) => t + s.places, 0);
  const occupees = salles.reduce((t, s) => t + s.occupees, 0);
  return { taux: Math.round((occupees / total) * 100) + '%' };
}

// salles.service.ts
@Injectable()
export class SallesService {
  private salles = [{ code: 'S1', places: 24, occupees: 20 }, { code: 'S2', places: 16, occupees: 4 }];

  tauxOccupation() {
    const total = this.salles.reduce((t, s) => t + s.places, 0);
    const occupees = this.salles.reduce((t, s) => t + s.occupees, 0);
    return { taux: Math.round((occupees / total) * 100) };   // un nombre : le client le formate
  }
}

// salles.controller.ts
@Get('taux-occupation')
taux() {
  return this.sallesService.tauxOccupation();
}