Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Bonnes pratiques et organisation du code d'un projet NestJS

Cette leçon rassemble les bonnes pratiques d'organisation d'un projet NestJS à partir d'un vrai projet. Elle présente le découpage en modules par fonctionnalité, la séparation entre contrôleurs, servi...

0 chapitres 0 QCM Accès gratuit
Bonnes pratiques et organisation du code d'un projet NestJS

À propos de ce cours

Cette leçon rassemble les bonnes pratiques d'organisation d'un projet NestJS à partir d'un vrai projet. Elle présente le découpage en modules par fonctionnalité, la séparation entre contrôleurs, services et accès aux données, une configuration validée au démarrage (refus réel de démarrer avec un secret trop court), un main.ts réduit et une fonction de configuration partagée avec les tests. Elle détaille les conventions de nommage, la qualité du code (lint, format, tests), la gestion des dépendances avec npm audit, le travail avec Git et GitHub, et se termine par une checklist de sécurité avant la mise en production. Activités corrigées.

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.

Organisation d'un projet NestJS

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/ contient demandes.module.ts, son contrôleur, son service, son entité et un sous-dossier dto/. 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: AuthModule importe UtilisateursModule, qui exporte UtilisateursService. É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
CoucheFaitNe fait pas
Contrôleurdéclare les routes, reçoit des DTO validés, choisit le code de statut, documente (Swagger), transmet l'utilisateur connecté au serviceaucune règle métier, aucun accès direct à la base
Servicerègles métier, droits sur les objets (filtre propriétaire), transactions, journalisation des événements métierne 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éspas de règle métier
DTOforme et validation des données reçues (et éventuellement renvoyées)pas de logique
Guards, pipes, intercepteurs, middlewarece qui est transversal : authentification, rôles, limite de débit, validation, sérialisation, journalpas 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 avec getUser(). 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.json et installer en production avec npm ci (versions exactes) ;
  • lancer npm audit --omit=dev régulièrement et corriger d'abord les niveaux high et critical; utiliser npm 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 install d'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 ; main reste 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 : .env dans .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
PointOù
Configuration validée au démarrage, secrets longs et uniques, .env hors du dépôt19.5, chapitre 10
NODE_ENV=production, synchronize: false, migrationschapitre 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, @Roleschapitre 13, 19.3
Contrôle du propriétaire sur chaque ressource (BOLA)19.3
ValidationPipe avec whitelist et forbidNonWhitelisted; @Exclude() ou DTO de sortiechapitre 07, 19.3
Limite de débit, connexion protégée, trust proxy correct19.2
Pages bornées, taille du corps et des fichiers limitée19.3, chapitre 15
Mots de passe hachés avec bcrypt, JWT à durée courtechapitre 13
Journal JSON sans secret, identifiant de requête, alertes19.4
npm audit --omit=dev sans faille élevée, npm ci19.5
Lint, tests unitaires et e2e (dont les accès refusés) au vertchapitre 17
HTTPS (et HSTS), API derrière nginxchapitre 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/ et config/ pour le transversal.
  • Contrôleur : HTTP ; service : règles métier et droits ; repository : données.
  • Configuration validée au démarrage ; .env.example versionné, .env jamais.
  • main.ts court, 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é ?