À propos de ce cours
Objectifs de la leçon
- Organiser un projet NestJS en modules par fonctionnalité.
- Répartir le code entre contrôleurs, services et accès aux données.
- Valider la configuration au démarrage et garder main.ts court.
- Appliquer des conventions de nommage et des outils de qualité.
- Gérer les dépendances et préparer une mise en production sûre.
Versions: NestJS 12.5 (projet CommonJS créé avec nest new), TypeScript 6, Node.js 24, MariaDB 10.11, helmet 8.3, @nestjs/throttler 6.7. Tout le code de ce chapitre provient d'un vrai projet, api-securisee, et toutes les sorties ont réellement été obtenues en l'exécutant. Les mêmes notions s'appliquent à NestJS 10 et 11.
Pourquoi des règles d'organisation ?
Un projet de TP tient dans quelques fichiers ; un projet réel grandit pendant des années, avec plusieurs développeurs. Sans règles communes, chacun range le code à sa façon, les mêmes vérifications sont écrites trois fois (ou oubliées une fois), et la sécurité dépend de la mémoire de chacun. NestJS impose déjà une structure (modules, injection de dépendances) : cette leçon en tire des règles simples, appliquées dans le projet du chapitre.
Un dossier par fonctionnalité, et dans chacun, des couches aux responsabilités distinctes.
Un module par fonctionnalité
On range le code par fonctionnalité métier (auth, utilisateurs, demandes), pas par type technique (un dossier controllers/, un dossier services/…). Tout ce qui concerne les demandes est au même endroit, et le module décide de ce qu'il exports aux autres :
src/
├── auth/
│ ├── dto/
│ │ ├── connexion.dto.ts
│ │ └── inscription.dto.ts
│ ├── auth.controller.ts
│ ├── auth.guard.ts
│ ├── auth.module.ts
│ ├── auth.service.ts
│ └── decorateurs.ts
├── commun/
│ ├── creer-logger.ts
│ └── journal-http.middleware.ts
├── config/
│ └── environnement.ts
├── demandes/
│ ├── dto/
│ │ ├── creer-demande.dto.ts
│ │ └── rechercher-demandes.dto.ts
│ ├── demande.entity.ts
│ ├── demandes.controller.ts
│ ├── demandes.module.ts
│ └── demandes.service.ts
├── sante/
│ └── sante.controller.ts
├── utilisateurs/
│ ├── utilisateur.entity.ts
│ ├── utilisateurs.controller.ts
│ ├── utilisateurs.module.ts
│ └── utilisateurs.service.ts
├── app.module.ts
├── configurer-app.ts
├── main.ts
└── swagger.ts
- Un dossier = un module:
demandes/contientdemandes.module.ts, son contrôleur, son service, son entité et un sous-dossierdto/. Les tests unitaires (*.spec.ts, chapitre 17) se placent à côté du fichier testé. commun/: ce qui sert à tout le projet sans appartenir à un métier (middleware, logger, filtres, décorateurs génériques).config/: la validation de l'environnement.- À la racine de
src:main.ts,app.module.ts,configurer-app.ts, et ce qui est global (swagger.ts). - Les dépendances entre modules passent par
imports/exports:AuthModuleimporteUtilisateursModule, qui exporteUtilisateursService. Évitez les dépendances circulaires (A importe B qui importe A) : c'est souvent le signe qu'une partie doit être déplacée dans un troisième module.
Le CLI crée cette structure pour vous : nest g resource demandes (chapitre 05) génère module, contrôleur, service, entité et DTO dans un dossier.
Chaque couche a un rôle
| Couche | Fait | Ne fait pas |
|---|---|---|
| Contrôleur | déclare les routes, reçoit des DTO validés, choisit le code de statut, documente (Swagger), transmet l'utilisateur connecté au service | aucune règle métier, aucun accès direct à la base |
| Service | règles métier, droits sur les objets (filtre propriétaire), transactions, journalisation des événements métier | ne connaît ni req ni res d'Express : il est testable sans HTTP |
| Repository (TypeORM) | accès aux données, requêtes avec paramètres liés | pas de règle métier |
| DTO | forme et validation des données reçues (et éventuellement renvoyées) | pas de logique |
| Guards, pipes, intercepteurs, middleware | ce qui est transversal : authentification, rôles, limite de débit, validation, sérialisation, journal | pas de règle propre à une seule route |
Exemple dans le projet : le contrôleur des demandes ne fait que transmettre ; c'est le service qui décide qu'un stagiaire ne voit que ses demandes.
📄 src/demandes/demandes.controller.ts (extrait)
@Get(':id')
une(@Param('id', ParseIntPipe) id: number, @Moi() moi: UtilisateurConnecte) {
return this.service.une(id, moi);
}
Une configuration validée au démarrage
Une variable d'environnement oubliée ou mal recopiée ne doit pas provoquer une panne trois jours plus tard, à la première connexion : l'application doit refuser de démarrer, avec un message clair. ConfigModule.forRoot({ validate }) (chapitre 10) appelle une fonction de validation écrite avec class-validator :
📄 src/config/environnement.ts
import { plainToInstance } from 'class-transformer';
import { IsIn, IsInt, IsOptional, IsString, MinLength, validateSync } from 'class-validator';
class Environnement {
@IsIn(['development', 'test', 'production']) NODE_ENV: string;
@IsInt() PORT: number;
@IsString() DB_HOTE: string;
@IsInt() DB_PORT: number;
@IsString() DB_UTILISATEUR: string;
@IsString() DB_MOT_DE_PASSE: string;
@IsString() DB_NOM: string;
@IsString() @MinLength(32) JWT_SECRET: string;
@IsOptional() @IsString() CORS_ORIGINES?: string;
@IsOptional() @IsString() TRUST_PROXY?: string;
@IsOptional() @IsIn(['texte', 'json']) LOG_FORMAT?: string;
@IsOptional() @IsString() LOG_NIVEAUX?: string;
}
export function validerEnvironnement(brut: Record<string, unknown>) {
const env = plainToInstance(Environnement, brut, { enableImplicitConversion: true });
const erreurs = validateSync(env, { skipMissingProperties: false });
if (erreurs.length) {
throw new Error('Configuration invalide :\n' + erreurs.map((e) => ` - ${Object.values(e.constraints ?? {}).join(', ')}`).join('\n'));
}
return env;
}
Résultat réel au démarrage avec NODE_ENV=prod (au lieu de production) et JWT_SECRET=secret:
[Nest] 5191 - 11/15/2026, 6:01:25 PM LOG [NestFactory] Starting Nest application...
[Nest] 5191 - 11/15/2026, 6:01:25 PM ERROR [ExceptionHandler] Error: Configuration invalide :
- NODE_ENV must be one of the following values: development, test, production
- JWT_SECRET must be longer than or equal to 32 characters
at Object.validerEnvironnement [as validate] (/projet/dist/config/environnement.js:86:15)
Le .env.example, versionné sur GitHub, documente chaque variable ; le .env, qui contient les vrais secrets, ne l'est jamais :
📄 .env.example
NODE_ENV=development
PORT=3000
DB_HOTE=localhost
DB_PORT=3306
DB_UTILISATEUR=root
DB_MOT_DE_PASSE=
DB_NOM=api_securisee
# au moins 32 caractères : node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"
JWT_SECRET=
CORS_ORIGINES=http://localhost:4200
# derrière nginx sur la même machine : TRUST_PROXY=loopback
TRUST_PROXY=
# texte (lisible) ou json (production, outils de collecte)
LOG_FORMAT=texte
# fatal | error | warn | log | debug | verbose
LOG_NIVEAUX=
Un main.ts court
main.ts crée l'application, installe le logger, appelle configurerApp() et démarre l'écoute. Toute la configuration HTTP (préfixe, Helmet, CORS, pipes, intercepteurs) est dans configurerApp(), appelée aussi par les tests e2e : les tests vérifient exactement l'application de production, et non une version sans whitelist ou sans Helmet (chapitre 17).
Conventions de nommage
- Fichiers en minuscules avec tirets et suffixe de rôle :
demandes.controller.ts,creer-demande.dto.ts,journal-http.middleware.ts,demande.entity.ts(le CLI le fait pour vous). - Classes en PascalCase avec le même suffixe :
DemandesController,CreerDemandeDto. Variables et méthodes en camelCase, constantes globales en MAJUSCULES. - Une seule langue pour les noms métier, appliquée partout : ici le français (
demandes,proprietaire), sans mélanger avecgetUser(). Les mots imposés par NestJS (Controller,Module,canActivate) restent en anglais. - Routes au pluriel et en minuscules (
/api/demandes/:id), méthodes HTTP qui disent l'action (chapitre 06).
La qualité du code, vérifiée par des outils
Un projet NestJS 12 est livré avec Oxlint (analyse statique, npm run lint) et Prettier (mise en forme, npm run format). Ce que les outils vérifient n'a plus à être vérifié par un humain lors d'une revue de code :
Résultat réel sur le projet :
$ npm run lint
> api-securisee@0.0.1 lint
> oxlint --type-aware src/ test/
(code de sortie : 0)
Ajoutez npm run lint, npm test et npm run build à votre routine avant chaque commit ; au chapitre 20, GitHub Actions les exécutera automatiquement à chaque push.
Les dépendances : npm audit
Votre code ne représente qu'une petite partie de ce qui s'exécute : node_modules contient des centaines de paquets. Une faille dans l'un d'eux est une faille dans votre API (A03:2025, chaîne d'approvisionnement). npm audit compare vos dépendances à une base de failles connues :
Résultats réels sur le projet :
$ npm audit --omit=dev
found 0 vulnerabilities
$ npm audit | grep vulnerabilities
25 vulnerabilities (6 low, 17 moderate, 2 high)
Les 25 failles signalées concernent uniquement les outils de développement (CLI, Jest…), qui ne sont pas installés en production : --omit=dev ne garde que ce qui sera réellement exécuté, et n'en trouve aucune. Bonnes habitudes :
- versionner
package-lock.jsonet installer en production avecnpm ci(versions exactes) ; - lancer
npm audit --omit=devrégulièrement et corriger d'abord les niveaux high et critical; utilisernpm audit fix(sans--force, qui peut installer des versions majeures incompatibles), puis relancer les tests ; - activer Dependabot sur GitHub (onglet Security) : il ouvre des Pull Requests de mise à jour ;
- avant d'ajouter un paquet, vérifier qu'il est maintenu et largement utilisé ; ne jamais copier une commande
npm installd'une source douteuse (noms imitant de vrais paquets).
Git et GitHub
- Une branche par fonctionnalité (
securite/helmet), fusionnée par Pull Request après relecture ;mainreste toujours déployable. - Des messages de commit clairs, par exemple au format Conventional Commits:
feat(demandes): recherche paginée,fix(securite): contrôle du propriétaire,chore: mise à jour des dépendances. - Jamais de secret dans le dépôt :
.envdans.gitignore. Un secret poussé par erreur doit être changé: le supprimer dans un nouveau commit ne suffit pas, il reste dans l'historique. - Un README qui explique comment installer, configurer, lancer et tester le projet.
Checklist avant la mise en production
| Point | Où |
|---|---|
Configuration validée au démarrage, secrets longs et uniques, .env hors du dépôt | 19.5, chapitre 10 |
NODE_ENV=production, synchronize: false, migrations | chapitre 12 |
| Helmet ; CORS limité aux origines réelles ; Swagger désactivé ou protégé | 19.1, chapitres 14 et 18 |
Guard d'authentification global, @Public() explicite, @Roles | chapitre 13, 19.3 |
| Contrôle du propriétaire sur chaque ressource (BOLA) | 19.3 |
ValidationPipe avec whitelist et forbidNonWhitelisted; @Exclude() ou DTO de sortie | chapitre 07, 19.3 |
Limite de débit, connexion protégée, trust proxy correct | 19.2 |
| Pages bornées, taille du corps et des fichiers limitée | 19.3, chapitre 15 |
| Mots de passe hachés avec bcrypt, JWT à durée courte | chapitre 13 |
| Journal JSON sans secret, identifiant de requête, alertes | 19.4 |
npm audit --omit=dev sans faille élevée, npm ci | 19.5 |
| Lint, tests unitaires et e2e (dont les accès refusés) au vert | chapitre 17 |
| HTTPS (et HSTS), API derrière nginx | chapitre 20 |
Activités
Activité 1 Ranger un projet
Un projet contient : src/controllers/users.controller.ts, src/controllers/demandes.controller.ts, src/services/user.service.ts, src/services/demandes.service.ts, src/entities/User.ts, src/entities/demande.ts, src/utils/logger.ts. Proposez la nouvelle arborescence et les noms corrigés.
Voir le corrigé
src/utilisateurs/: utilisateurs.module.ts, utilisateurs.controller.ts, utilisateurs.service.ts, utilisateur.entity.ts; src/demandes/: demandes.module.ts, demandes.controller.ts, demandes.service.ts, demande.entity.ts, dto/; src/commun/creer-logger.ts. Une seule langue (utilisateurs et non users), fichiers en minuscules avec suffixe. Faites les déplacements avec git mv pour garder l'historique.
Activité 2 Sortir la logique du contrôleur
Réécrivez ce contrôleur en déplaçant la logique dans le service :
@Post(':id/valider')
async valider(@Param('id', ParseIntPipe) id: number, @Req() req) {
const d = await this.repo.findOneBy({ id });
if (!d) throw new NotFoundException();
if (req.user.role !== 'admin') throw new ForbiddenException();
d.statut = 'validee';
return this.repo.save(d);
}
Voir le corrigé
// contrôleur
@Roles('admin')
@Post(':id/valider')
valider(@Param('id', ParseIntPipe) id: number, @Moi() moi: UtilisateurConnecte) {
return this.service.valider(id, moi);
}
// service
async valider(id: number, moi: UtilisateurConnecte) {
const d = await this.repo.findOneBy({ id });
if (!d) throw new NotFoundException('Demande introuvable');
d.statut = 'validee';
const r = await this.repo.save(d);
this.logger.log(`Demande ${id} validée`, { par: moi.id });
return r;
}Le rôle est vérifié par le guard (@Roles), la règle métier est dans le service, testable sans requête HTTP, et l'action est journalisée pour l'audit.
Activité 3 Valider sa configuration
Ajoutez à votre projet un fichier config/environnement.ts comme celui de la leçon, adapté à vos variables. Testez trois erreurs : une variable absente, un port non numérique, un secret trop court. Le message affiché permet-il de corriger sans lire le code ?
Voir le corrigé
Chaque contrainte non respectée est listée avant l'arrêt. Pour des messages encore plus clairs, ajoutez des messages personnalisés : @MinLength(32, { message: 'JWT_SECRET doit contenir au moins 32 caractères' }). Mettez à jour .env.example en même temps. Commit : feat(config): validation de l'environnement.
Activité 4 Audit complet de votre projet
Appliquez la checklist de la leçon à votre projet de TP 12. Pour chaque point non respecté, ouvrez une issue GitHub avec un titre clair et une étiquette securite, puis traitez-les une par une dans des branches séparées.
Voir le corrigé
Exemples d'issues : « Activer Helmet », « Limiter les tentatives de connexion », « Contrôle du propriétaire sur PATCH /stagiaires/:id », « Masquer motDePasseHash dans /utilisateurs/moi », « Journal JSON en production ». Référencez l'issue dans le commit ou la Pull Request (Fixes #12) : GitHub la fermera automatiquement à la fusion. Le dépôt devient la trace de votre démarche de sécurisation.
À retenir
- Un dossier et un module par fonctionnalité ;
commun/etconfig/pour le transversal. - Contrôleur : HTTP ; service : règles métier et droits ; repository : données.
- Configuration validée au démarrage ;
.env.exampleversionné,.envjamais. main.tscourt,configurerApp()partagée avec les tests e2e.- Nommage cohérent, lint, format et tests avant chaque commit.
npm audit --omit=dev,npm ci, Dependabot ; une checklist de sécurité avant la production.
Cet article vous a-t-il aidé ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !