L'architecture d'une application NestJS : vue d'ensemble

Une architecture imposée… et c'est une bonne nouvelle

Au chapitre 01, nous avons vu qu'Express laisse chaque développeur organiser son code comme il l'entend. NestJS fait le choix inverse : il impose une architecture. Tous les projets NestJS se ressemblent, ce qui permet à un nouveau développeur (ou à un enseignant qui corrige un TP !) de s'y retrouver en quelques minutes.

Cette architecture repose sur trois briques et sur des enrichisseurs qui s'intercalent sur le trajet des requêtes.

1. Les trois briques fondamentales

@Module({
  imports: [GroupesModule],               // modules dont on utilise les services
  controllers: [StagiairesController],    // guichets HTTP de ce module
  providers: [StagiairesService],         // services de ce module
  exports: [StagiairesService],           // ce que l'on partage avec les autres modules
})
export class StagiairesModule {}

2. L'arbre des modules

Toute application a un module racine, AppModule, passé à NestFactory.create() dans main.ts. Il importe des modules de fonctionnalité, qui peuvent à leur tour en importer d'autres. NestJS parcourt cet arbre au démarrage pour tout construire.

AppModule importe les modules de fonctionnalité ; ceux-ci importent les modules dont ils utilisent les services.

Les journaux de démarrage montrent ce travail. Voici ceux, réels, de l'application de la leçon 5.2 (deux modules : groupes et stagiaires) :

Terminal au démarrage :

[Nest] LOG [NestFactory] Starting Nest application...
[Nest] LOG [InstanceLoader] AppModule dependencies initialized +13ms
[Nest] LOG [InstanceLoader] GroupesModule dependencies initialized +0ms
[Nest] LOG [InstanceLoader] StagiairesModule dependencies initialized +0ms
[Nest] LOG [RoutesResolver] GroupesController {/api/groupes}: +4ms
[Nest] LOG [RouterExplorer] Mapped {/api/groupes, GET} route +4ms
[Nest] LOG [RouterExplorer] Mapped {/api/groupes/:code, GET} route +1ms
[Nest] LOG [RoutesResolver] StagiairesController {/api/stagiaires}: +0ms
[Nest] LOG [RouterExplorer] Mapped {/api/stagiaires/:id, GET} route +1ms
[Nest] LOG [NestApplication] Nest application successfully started +2ms

• InstanceLoader: chaque module est chargé et ses providers créés (injection de dépendances résolue).
• RoutesResolver / RouterExplorer: chaque contrôleur est inspecté et ses routes enregistrées, grâce aux métadonnées des décorateurs (leçon 4.7).

3. Le conteneur d'injection de dépendances

Vous n'écrivez jamais new StagiairesService(). Le conteneur (ou injecteur) de NestJS :

1. lit les providers de chaque module ;
2. lit le type des paramètres de chaque constructeur (design:paramtypes, leçon 4.7) ;
3. crée les instances dans le bon ordre (d'abord les dépendances) et les relie ;
4. par défaut, crée une seule instance de chaque provider (singleton), partagée par tous ceux qui l'injectent.

C'est exactement le mini-injecteur que vous avez construit au chapitre 04… en version industrielle, qui gère aussi les modules, la visibilité (exports), les portées et les dépendances circulaires (chapitre 07).

4. Les enrichisseurs : sur le trajet des requêtes

Entre l'arrivée d'une requête et l'exécution du contrôleur, NestJS peut faire intervenir des classes spécialisées. Chacune a un rôle précis :

Leur ordre d'exécution est détaillé à la leçon 5.5.

5. L'architecture en couches

À l'intérieur d'un module, le code se répartit en couches, chacune avec une seule responsabilité :

Exemple à ne pas suivre: un contrôleur « obèse » qui fait tout.

@Controller('stagiaires')
export class StagiairesController {
  private stagiaires = [{ id: 1, nom: 'Ben Ali', notes: [14, 9, 16] }];

  @Get(':id/bulletin')
  bulletin(@Param('id') id: string, @Res() res: Response) {
    const s = this.stagiaires.find((x) => x.id === Number(id));
    if (!s) return res.status(404).json({ message: 'Introuvable' });
    const moyenne = s.notes.reduce((a, b) => a + b, 0) / s.notes.length;   // règle métier
    const mention = moyenne >= 16 ? 'Très bien' : moyenne >= 14 ? 'Bien' : 'Passable';
    return res.json({ nom: s.nom, moyenne, mention });
  }
}

Problèmes : la règle de calcul est enfermée dans une route HTTP (impossible à réutiliser dans un export PDF ou une tâche planifiée), le contrôleur manipule directement la réponse Express, et le test unitaire du calcul exige de simuler une requête HTTP.

Version en couches:

@Injectable()
export class BulletinsService {
  constructor(private readonly stagiaires: StagiairesService) {}

  calculer(id: number) {
    const s = this.stagiaires.findOne(id);              // lève NotFoundException si absent
    const moyenne = s.notes.reduce((a, b) => a + b, 0) / s.notes.length;
    return { nom: s.nom, moyenne: +moyenne.toFixed(2), mention: this.mention(moyenne) };
  }

  mention(moyenne: number): string {
    return moyenne >= 16 ? 'Très bien' : moyenne >= 14 ? 'Bien' : moyenne >= 10 ? 'Passable' : 'Ajourné';
  }
}

@Controller('stagiaires')
export class StagiairesController {
  constructor(private readonly bulletins: BulletinsService) {}

  @Get(':id/bulletin')
  bulletin(@Param('id') id: string) {
    return this.bulletins.calculer(Number(id));          // le contrôleur délègue
  }
}

6. Organiser le projet par fonctionnalités

src/
├── main.ts
├── app.module.ts
├── common/                 ← éléments partagés : services utilitaires, middleware, décorateurs
│   ├── common.module.ts
│   └── journal.service.ts
├── config/                 ← configuration (chapitre 10)
├── formations/             ← une fonctionnalité = un dossier = un module
│   ├── dto/
│   ├── formations.controller.ts
│   ├── formations.module.ts
│   └── formations.service.ts
├── groupes/
└── stagiaires/

Quand une fonctionnalité grandit, on peut la découper en sous-modules (par exemple stagiaires/absences). La règle : tout ce qui change ensemble reste ensemble.

7. Si vous connaissez Angular

Activités

// notes.service.ts
@Injectable()
export class NotesService {
  private notes = [
    { stagiaire: 'Ben Ali', groupe: 'DEV101', valeur: 14 },
    { stagiaire: 'Trabelsi', groupe: 'DEV101', valeur: 17 },
    { stagiaire: 'Gharbi', groupe: 'DEV102', valeur: 9 },
  ];

  moyenneGroupe(code: string) {
    const valeurs = this.notes.filter((n) => n.groupe === code.toUpperCase()).map((n) => n.valeur);
    if (valeurs.length === 0) throw new NotFoundException(`Aucune note pour le groupe ${code}`);
    return { groupe: code.toUpperCase(), moyenne: valeurs.reduce((a, b) => a + b, 0) / valeurs.length };
  }
}

// notes.controller.ts
@Controller('notes')
export class NotesController {
  constructor(private readonly notesService: NotesService) {}

  @Get('groupe/:code/moyenne')
  moyenne(@Param('code') code: string) {
    return this.notesService.moyenneGroupe(code);
  }
}