1. Introduction

Le PDF du document est |ICI|.

Les codes du document sont |ICI|.

Ce document est un produit de l'IA Claude d'Anthropic. Il a pour vocation de transposer le document Introduction à ASP.NET MVC par l'exemple (2013) au framework web [NestJS] :

le framework [ASP.NET MVC] et le langage [C#] sont remplacés par le framework [NestJS] et le langage [TypeScript] ;
les vues [Razor] sont remplacées par des vues [Handlebars] ;
l'accès aux données [Entity Framework] est remplacé par l'ORM [TypeORM] et une base [MySQL].

Le document suit la progression du cours d'origine : d'abord de nombreux petits projets, chacun centré sur une notion, puis une étude de cas complète, une application web de prise de rendez-vous pour un cabinet de médecins, dont tous les fichiers sont commentés. Le chapitre du cours d'origine consacré aux bases de la programmation web (le protocole HTTP, le langage HTML) n'a pas été repris : on suppose ces bases connues.

1.1. La place de NestJS dans une application web

Une application web est souvent construite en couches, chaque couche ne parlant qu'à ses voisines :

la couche web reçoit les requêtes HTTP du navigateur et lui renvoie des pages HTML. C'est elle que [NestJS] nous aide à écrire ;
la couche métier contient les règles de gestion de l'application (« un patient ne peut avoir qu'un rendez-vous à venir », par exemple). Elle ignore tout du web : elle pourrait aussi bien servir une application en ligne de commande ;
la couche d'accès aux données (couche [DAO], pour [Data Access Object]) lit et écrit dans la base de données. Nous utiliserons l'ORM [TypeORM] ([Object Relational Mapper]) qui fait correspondre les lignes des tables et des objets [TypeScript].

La couche web suit elle-même le modèle [MVC] ([Model – View – Controller]) :

le contrôleur (C) est une classe dont les méthodes, appelées actions, traitent chacune un type de requête (par exemple [GET /agenda]). Une action lit les paramètres de la requête, fait travailler la couche métier, puis choisit la vue à afficher ;
le modèle (M) est l'ensemble des données que l'action transmet à la vue : un simple objet [JavaScript] ;
la vue (V) est un fichier [Handlebars] (extension [.hbs]) : du HTML dans lequel des balises [{{...}}] sont remplacées par les données du modèle.

Le traitement d'une requête suit les étapes numérotées du schéma :

1 : le navigateur envoie une requête HTTP, par exemple [GET /agenda?idMedecin=1&jour=2026-09-24] ;
2 : [NestJS], qui s'appuie sur le serveur web [Express], choisit l'action chargée de cette requête : c'est le routage. Avant d'y arriver, la requête peut traverser des middlewares, des gardes, des intercepteurs, des pipes, que nous découvrirons au fil des chapitres ;
3 : l'action demande à la couche métier les données dont elle a besoin ;
4 : elle construit le modèle de la vue et désigne la vue qui doit l'afficher ;
5 : le moteur de vues [Handlebars] fabrique la page HTML, que [NestJS] renvoie au navigateur.

[NestJS] est un framework [Node.js] écrit en [TypeScript]. Il reprend les idées des frameworks [Spring] ([Java]) et [Angular] : des décorateurs ([@Controller], [@Get], [@Injectable]...) décrivent le rôle de chaque classe, et l'injection de dépendances fournit à chaque objet ceux dont il a besoin. On l'utilise souvent pour écrire des serveurs qui renvoient du JSON à un client [JavaScript] ([Angular], [React], [Flutter]...). Ce document l'utilise pour écrire une application web classique : c'est le serveur qui fabrique les pages HTML, et le navigateur se contente de les afficher.

1.2. Les outils utilisés

Les exemples ont été écrits et testés avec les outils suivants (leur installation est décrite en annexe) :

[Node.js] 20 et son gestionnaire de paquets [npm] ;
l'éditeur [Visual Studio Code] ;
un navigateur récent ([Chrome], [Firefox], [Edge]) ;
l'outil en ligne de commande [curl], qui affiche les réponses HTTP brutes (il est livré avec [Windows] 10 et 11) ;
le SGBD [MySQL] (ou [MariaDB]), par exemple celui de [Laragon] sous [Windows], à partir du chapitre sur l'accès aux données.

Les versions des bibliothèques sont celles du fichier [package.json] du dossier des exemples : [NestJS] 10, [TypeScript] 5, [hbs] 4 ([Handlebars]), [class-validator] 0.14, [TypeORM] 0.3, [Bootstrap] 5.

1.3. Les exemples

Les exemples sont rangés dans un dossier [exemples], un sous-dossier par exemple :

exemples/
├── 01-structure/
├── 02-routage/
├── ...
├── 28-couches/
├── node_modules/
├── package.json
└── package-lock.json

Tous les exemples partagent les mêmes bibliothèques, déclarées dans [exemples/package.json]. On les installe une seule fois, dans une console ouverte sur le dossier [exemples]. Dans VSCode ouvrez le dossier des exemples :

puis dans un terminal intégré à VSCode, tapez la commande

npm install

Chaque exemple a ensuite la structure minimale d'un projet [NestJS] :

13-premiere-vue/
├── src/
│   ├── app.module.ts
│   ├── main.ts
│   └── vues.controller.ts
├── views/
│   ├── inconnu.hbs
│   └── index.hbs
├── nest-cli.json
└── tsconfig.json

[src] : le code [TypeScript] ;
[views] : les vues [Handlebars] (à partir du chapitre 4) ;
[nest-cli.json] : la configuration de l'outil en ligne de commande de [NestJS] ;
[tsconfig.json] : la configuration du compilateur [TypeScript].

Pour exécuter un exemple, on ouvre une console sur son dossier

et on tape :

npx nest start

[npx] trouve l'outil [nest] dans le dossier [node_modules] du dossier parent. [nest start] compile le code [TypeScript] dans le dossier [dist], puis exécute [dist/main.js]. Avec l'option [--watch], le code est recompilé et le serveur relancé à chaque modification d'un fichier [.ts] :

npx nest start --watch

Tous les exemples écoutent sur le port 3000 : on ne peut en exécuter qu'un à la fois. On arrête le serveur par [Ctrl-C] dans la console.

Le fichier [tsconfig.json] est le même pour tous les exemples :

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2022",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "strictNullChecks": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Commentons ce fichier :

ligne 3 : le code compilé utilise les modules [CommonJS] de [Node.js] ([require]) ;
ligne 4 : le code produit est du [JavaScript] récent (ES2022), que [Node.js] 20 comprend ;
lignes 6-7 : le code source est dans [src], le code compilé dans [dist] ;
lignes 9-10 : indispensables à [NestJS]. Les décorateurs ([@Controller]...) sont une fonctionnalité de [TypeScript] qu'il faut activer, et [emitDecoratorMetadata] conserve dans le code compilé le type des paramètres des constructeurs et des méthodes : c'est grâce à lui que [NestJS] sait quel objet injecter dans un constructeur ;
ligne 12 : le compilateur signale l'usage d'une valeur qui peut être [null] ou [undefined] ;
ligne 13 : on ne vérifie pas les fichiers de déclaration des bibliothèques (compilation plus rapide).

Le fichier [nest-cli.json] est lui aussi commun à tous les exemples :

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true
  }
}

ligne 4 : le code source est dans [src] ;
ligne 6 : le dossier [dist] est vidé avant chaque compilation (un fichier supprimé de [src] ne laisse pas de copie compilée périmée).

1.4. Contenu du document

Le document progresse ainsi :

Chapitre	Contenu	Exemples
Contrôleurs, actions, routage	du navigateur à l’action : routes, réponses, redirections, modules	01 à 06
Le modèle d'une action	les paramètres de la requête : conversion, validation, formulaires POST	07 à 12
La vue et son modèle	Handlebars, gabarit, partiels, helpers, formulaires, validation, PRG	13 à 21
Internationalisation	une application en français et en anglais	22
Portées des données	application, requête, client	23
Le cycle de vie d'une requête	middleware, garde, intercepteur, pipe, filtre d'exceptions	24
Authentification et autorisation	JWT dans un cookie, rôles, captcha, limitation des tentatives	25 à 27
Architecture en couches	web / métier / DAO avec TypeORM et MySQL	28
Étude de cas	l'application RdvMedecins, commentée fichier par fichier	-

Chaque exemple introduit peu de nouveautés, et les chapitres s'appuient les uns sur les autres : il est préférable de les lire dans l'ordre. L'étude de cas, elle, réutilise toutes les notions des chapitres précédents : chaque fois que c'est utile, son commentaire renvoie à l'exemple où la notion a été présentée.