Une application NestJS démarre presque toujours la même façon : un AppModule unique, quelques services, tout fonctionne. Six mois et vingt fonctionnalités plus tard, le même AppModule importe quinze modules qui s'importent mutuellement, deux services se référencent l'un l'autre via forwardRef, et ajouter une fonctionnalité simple nécessite de comprendre un graphe de dépendances que plus personne dans l'équipe ne maîtrise entièrement. Le problème n'est pas NestJS, qui fournit justement les outils pour éviter cette dérive : c'est l'absence de frontières de module imposées dès le départ.

Le mécanisme : modules, conteneur DI et scope des providers

NestJS organise l'application autour de modules, chacun déclarant ses providers (classes instanciées par le conteneur d'injection de dépendances), ses imports (modules dont il consomme des providers exportés) et ses exports (providers qu'il rend disponibles aux modules qui l'importent). Un provider non exporté reste strictement privé à son module, même si un autre module l'importe.

// orders/orders.module.ts
@Module({
  imports: [CustomersModule],
  controllers: [OrdersController],
  providers: [OrdersService, OrdersRepository],
  exports: [OrdersService],
})
export class OrdersModule {}
// orders/orders.service.ts
@Injectable()
export class OrdersService {
  constructor(
    private readonly ordersRepository: OrdersRepository,
    private readonly customersService: CustomersService,
  ) {}

  async placeOrder(dto: CreateOrderDto): Promise<Order> {
    const customer = await this.customersService.findById(dto.customerId);
    return this.ordersRepository.create({ ...dto, customer });
  }
}

Par défaut, un provider est en scope singleton : une seule instance pour toute la durée de vie de l'application, partagée entre toutes les requêtes. C'est le comportement souhaité dans l'immense majorité des cas, et c'est aussi ce qui rend NestJS performant comparé à une instanciation par requête.

Le symptôme le plus courant : la dépendance circulaire

Quand deux modules s'importent mutuellement, directement ou via une chaîne de modules intermédiaires, Nest ne peut pas déterminer dans quel ordre les instancier. Le symptôme typique est une erreur au démarrage, ou pire, un forwardRef() ajouté comme solution de contournement sans que la cause profonde ne soit traitée :

// customers/customers.module.ts
@Module({
  imports: [forwardRef(() => OrdersModule)],
  providers: [CustomersService],
  exports: [CustomersService],
})
export class CustomersModule {}
// customers/customers.service.ts
@Injectable()
export class CustomersService {
  constructor(
    @Inject(forwardRef(() => OrdersService))
    private readonly ordersService: OrdersService,
  ) {}

  async getCustomerOrderCount(customerId: string): Promise<number> {
    return this.ordersService.countByCustomer(customerId);
  }
}

forwardRef résout le problème technique d'instanciation, mais il ne résout pas le problème de conception : deux modules qui dépendent l'un de l'autre dans les deux sens signalent presque toujours une mauvaise répartition des responsabilités. Ici, CustomersService qui a besoin de compter les commandes d'un client dépend d'OrdersService, tandis qu'OrdersService dépend de CustomersService pour valider un client à la création d'une commande. C'est le signe que la logique de comptage de commandes par client ne devrait pas vivre dans CustomersService.

Diagnostiquer avant de recourir à forwardRef

Nest affiche au démarrage un message explicite en cas de dépendance circulaire non résolue, avec la chaîne complète des modules impliqués. Avant d'ajouter un forwardRef par réflexe, deux vérifications s'imposent :

npx madge --circular --extensions ts src/

madge cartographie les imports TypeScript du projet et liste les cycles réels, indépendamment du moment où Nest les détecte au runtime. Cela permet de voir l'ensemble du problème plutôt que le premier cycle que l'erreur de démarrage signale.

En complément, outiller le lint avec dependency-cruiser ou des règles ESLint de frontières de module (eslint-plugin-boundaries) transforme la convention de "pas de dépendance circulaire entre modules métier" en règle vérifiée automatiquement en CI, plutôt qu'en discipline d'équipe reposant sur la vigilance individuelle.

La correction : inverser la dépendance, pas la contourner

La correction structurelle consiste à extraire la logique partagée dans un module séparé, situé plus bas dans la hiérarchie de dépendances, que les deux modules métier peuvent importer sans jamais dépendre l'un de l'autre :

// order-customer-stats/order-customer-stats.module.ts
@Module({
  providers: [OrderCustomerStatsService],
  exports: [OrderCustomerStatsService],
})
export class OrderCustomerStatsModule {}
// order-customer-stats/order-customer-stats.service.ts
@Injectable()
export class OrderCustomerStatsService {
  constructor(
    @Inject(ORDERS_READ_PORT) private readonly ordersReadPort: OrdersReadPort,
  ) {}

  async countByCustomer(customerId: string): Promise<number> {
    return this.ordersReadPort.countByCustomer(customerId);
  }
}

L'usage d'un token d'injection (ORDERS_READ_PORT) associé à une interface plutôt qu'à la classe concrète OrdersService découple ce service de l'implémentation réelle, ce qui permet à OrdersModule de fournir l'implémentation sans que OrderCustomerStatsModule n'importe OrdersModule directement :

// orders/orders.module.ts
@Module({
  providers: [
    OrdersService,
    { provide: ORDERS_READ_PORT, useExisting: OrdersService },
  ],
  exports: [ORDERS_READ_PORT],
})
export class OrdersModule {}

Les compromis du scope request et du module partagé

Le scope REQUEST permet d'injecter le contexte de la requête HTTP courante (utilisateur authentifié, identifiant de tenant) directement dans un provider, mais il a un coût réel : un provider en scope REQUEST est réinstancié à chaque requête, et ce scope se propage à tous les providers qui en dépendent, transitivement. Un service placé haut dans le graphe de dépendances et marqué REQUEST par erreur peut transformer une grande partie de l'application en instances par requête, dégradant les performances sans qu'un profiling superficiel n'en révèle immédiatement la cause.

@Injectable({ scope: Scope.REQUEST })
export class TenantContextService {
  constructor(@Inject(REQUEST) private readonly request: Request) {}

  getTenantId(): string {
    return this.request.headers['x-tenant-id'] as string;
  }
}

Pour un contexte de requête léger (identifiant de tenant, identifiant de trace) sans payer le coût du scope REQUEST sur toute une chaîne de providers, une bibliothèque comme nestjs-cls, construite sur AsyncLocalStorage, propage ce contexte sans impliquer le conteneur DI, et reste singleton du point de vue de Nest.

Un SharedModule fourre-tout, qui exporte indistinctement tout ce qui est utilisé par plus d'un module métier, finit par recréer le même problème qu'un AppModule monolithique, simplement déplacé : tout le monde en dépend, personne ne sait plus ce qu'il contient réellement. Préférer des modules partagés fins et nommés par responsabilité (DatabaseModule, LoggingModule, AuthModule) à un module générique CommonModule ou SharedModule.

Quand le découpage en modules ne suffit pas

Pour un domaine métier complexe avec des règles de validation et des invariants riches, séparer la couche domaine (entités, règles métier, ports) de la couche infrastructure (repository Prisma ou TypeORM, clients HTTP) à l'intérieur même d'un module, selon une logique proche de l'architecture hexagonale, évite que les règles métier ne se retrouvent couplées à un ORM particulier. Le module expose un port (interface), et l'implémentation concrète est injectée via un provider personnalisé, exactement comme dans l'exemple ORDERS_READ_PORT plus haut, mais appliqué systématiquement plutôt que ponctuellement.

Pour des domaines avec des flux de commandes et d'événements complexes (un processus métier en plusieurs étapes, avec des effets de bord asynchrones), le module @nestjs/cqrs structure explicitement la séparation entre commandes, requêtes et événements, ce qui clarifie le flux de données dans un module qui, sinon, accumulerait des méthodes de service aux responsabilités mélangées.

Enfin, découper un monolithe NestJS en microservices via les transports @nestjs/microservices (TCP, Redis, NATS) est une décision d'architecture distincte, à ne pas confondre avec le découpage en modules : un monolithe modulaire aux frontières de module strictement respectées se prête à une extraction ultérieure en services séparés bien plus facilement qu'un monolithe aux dépendances circulaires, mais l'extraction elle-même répond à des besoins organisationnels et de scalabilité indépendants, pas à un problème de lisibilité du code.

En bref

Une dépendance circulaire entre deux modules NestJS n'est presque jamais un problème technique à résoudre par forwardRef, c'est un symptôme de conception qui indique qu'une responsabilité est mal placée dans le graphe de modules. Des frontières de module explicites, vérifiées par un outil comme madge en CI, coûtent moins cher à maintenir sur la durée qu'un graphe de dépendances que seule une poignée de développeurs sait encore reconstituer mentalement.