Busca en todas las páginas de la documentación
NestJS parece, a primera vista, como Express o Fastify con decoradores adicionales, pero su abstracción central real es diferente en tipo, no solo en estilo: un grafo de módulos, interconectados por un contenedor IoC (inversión de control), que se asienta sobre un adaptador HTTP intercambiable que puede ser Express, Fastify o algo completamente diferente.
Ese es un punto de partida significativamente diferente a "una cadena de funciones" o "un árbol de plugins": NestJS toma prestada su arquitectura del sistema de inyección de dependencias de Angular y la aplica en el lado del servidor, razón por la cual los equipos que vienen de Spring Boot o Angular tienden a encontrarla inmediatamente familiar, y los equipos que vienen de Express o Fastify puros tienden a encontrar la maquinaria de decoradores y DI poco familiar al principio.
Esta página es el modelo mental detrás de esa maquinaria: qué es realmente un módulo, cómo el contenedor resuelve las dependencias a partir de los metadatos del decorador y cómo el recorrido de una solicitud a través de guards, interceptors y pipes difiere de una cadena de middleware o los hooks del ciclo de vida de un plugin.
Conceptos básicos de NestJS cubre esto de forma práctica con módulos y controladores funcionales; Inyección de Dependencias profundiza en los ámbitos de los proveedores y los tokens personalizados construidos sobre el modelo descrito aquí.
Un módulo, decorado con @Module(), es la unidad arquitectónica de NestJS: declara qué proveedores (servicios, repositorios, cualquier cosa inyectable) posee, qué controladores manejan sus rutas HTTP y qué otros módulos importa o exporta para compartir proveedores entre límites.
@Module({
imports: [DatabaseModule],
controllers: [UsersController],
providers: [UsersService],
exports: [UsersService],
})
export class UsersModule {}Cada aplicación tiene exactamente un módulo raíz (convencionalmente AppModule), y cada otro módulo se conecta a él, directa o indirectamente, a través de imports, razón por la cual toda la estructura se denomina con precisión un grafo: los módulos son nodos y las imports son los bordes que los conectan.
El contenedor IoC es lo que realmente construye este grafo al inicio: en lugar de que un UsersController construya su propio UsersService con new, declara la dependencia como un parámetro del constructor, y el contenedor mira el tipo de ese parámetro, encuentra (o crea) el proveedor coincidente y lo entrega, "inversión de control" porque la clase ya no controla cómo sus propias dependencias cobran vida.
Una forma sencilla de imaginarlo: en lugar de que cada trabajador busque sus propias herramientas en un cobertizo, un capataz (el contenedor) lee la lista de herramientas de todos con anticipación, ensambla las herramientas y entrega exactamente lo que cada trabajador declaró que necesita antes de que comience el trabajo.
El mecanismo que hace posible la inyección de constructor sin ningún código de registro explícito son los metadatos del decorador: @Injectable(), @Controller() y los tipos de parámetros del constructor se registran, en tiempo de compilación, a través de emitDecoratorMetadata de TypeScript y la librería reflect-metadata, de modo que cuando el contenedor se ejecuta, puede leer "el constructor de esta clase necesita un UsersService" directamente de los metadatos adjuntos a la clase, sin que tengas que escribir ningún cableado manual.
Este es un mecanismo genuinamente diferente de la mutación de objetos compartidos de Express o los ámbitos de plugins encadenados por prototipos de Fastify; nada de esto sucede pasando un objeto a través de una cadena; sucede porque el contenedor inspecciona los metadatos generados en tiempo de compilación y resuelve un grafo de dependencias antes de que llegue una sola solicitud.
@Module() los metadatos declaran proveedores/controladores/importaciones
│
▼
El contenedor IoC resuelve el grafo en el arranque:
lee los metadatos de los parámetros del constructor (reflect-metadata)
instancia los proveedores en orden de dependencia
inyecta las instancias resueltas en cada consumidor
│
▼
NestFactory.create(AppModule, adapter) entrega la aplicación
resuelta a un adaptador HTTP (Express o Fastify) para el transporteEse último paso es el patrón adaptador en el núcleo de NestJS: NestJS en sí es agnóstico al transporte (el grafo de módulos y el contenedor DI no saben nada sobre HTTP específicamente), y NestFactory.create() conecta el adaptador que elijas (platform-express por defecto, o platform-fastify para un mejor rendimiento) para aceptar conexiones y despachar solicitudes al grafo resuelto.
Dentro de una sola solicitud, NestJS superpone una tubería más elaborada de lo que cualquiera de los frameworks subyacentes ofrece por sí solo: el middleware (a nivel de adaptador, estilo Express o Fastify) se ejecuta primero, luego los guards (decisiones de autorización: ¿puede esta solicitud continuar?), luego los interceptors (envuelven al manejador, pueden transformar la entrada o la salida), luego los pipes (validan y transforman los argumentos), luego el manejador de ruta en sí, luego los interceptors nuevamente a la salida, con los filtros de excepción capturando cualquier cosa que se lance en el camino.
Ese orden fijo (no middleware, luego lo que sea que escribas en línea) es deliberado: les da a las preocupaciones transversales (autenticación, validación, modelado de respuestas) un lugar definido y predecible para vivir en lugar de competir por la posición en una cadena plana.
La mayor ventaja del grafo de módulos se manifiesta en las pruebas y la escalabilidad del equipo: debido a que cada dependencia llega a través del constructor en lugar de ser importada e instanciada directamente, Test.createTestingModule() puede intercambiar cualquier proveedor por un mock con overrideProvider(), probando un controlador o servicio de forma completamente aislada de sus dependencias reales, algo considerablemente más incómodo de lograr limpiamente en una cadena Express plana o un árbol de plugins no administrado.
El patrón adaptador también rinde frutos más allá de HTTP: debido a que el grafo de módulos y el contenedor DI no saben nada específico de HTTP, la misma arquitectura impulsa el modo de microservicios de NestJS, intercambiando el adaptador HTTP por un transporte como TCP, Redis o una cola de mensajes, mientras que los proveedores, guards y el resto del grafo permanecen conceptualmente sin cambios (consulta Modo de Microservicios).
El costo de arranque es el compromiso que conlleva todo esto: resolver un grafo de dependencias grande, recorrer los metadatos del decorador e instanciar proveedores singleton lleva tiempo y memoria reales y medibles al inicio, lo que generalmente no es un problema para un proceso de servidor de larga duración, pero es una consideración genuina para entornos sensibles al arranque en frío como serverless (consulta Realidad del rendimiento de NestJS para los números honestos).
El ámbito del proveedor es el punto más delicado del modelo: los proveedores por defecto son singleton (una instancia para toda la vida útil de la aplicación), lo cual es eficiente pero significa que cualquier cosa específica de la solicitud, como un contexto de usuario por solicitud, necesita una opción explícita Scope.REQUEST, lo que conlleva su propio costo de reinstanciación por solicitud que los proveedores singleton no pagan.
| Abstracción central del framework | Fortaleza | Debilidad | Mejor ajuste |
|---|---|---|---|
| NestJS: grafo de módulos DI | Arquitectura impuesta; testeabilidad inyectada por constructor; agnóstico al transporte | Abstracción más pesada; costo real de arranque; curva de aprendizaje más pronunciada | Equipos grandes, servicios empresariales de larga duración, sistemas mixtos HTTP/microservicios |
| Fastify: árbol de plugins encapsulado | Ámbitos aislados; despacho compilado por esquema para velocidad | Sin contenedor DI; estructura menos impuesta que los módulos | APIs de alto rendimiento o con esquema primero |
| Express: cadena de middleware plana | Mínimo, familiar, enorme ecosistema | Sin encapsulación, sin DI; la estructura es totalmente por convención | APIs CRUD pequeñas a medianas |
Scope.REQUEST se vuelven a crear por solicitud, y eso es un costo explícito y opcional.reflect-metadata, que el contenedor IoC lee al inicio para resolver el grafo de dependencias; eliminar los decoradores eliminaría la capacidad del contenedor de saber qué depende de qué.Un grafo de módulos, cada uno declarando sus propios proveedores, controladores e importaciones/exportaciones, resuelto en el arranque por un contenedor IoC que inyecta dependencias basadas en metadatos generados por decoradores.
No, NestJS en sí es agnóstico al transporte. NestFactory.create() conecta un adaptador, típicamente Express (platform-express, el predeterminado) o Fastify (platform-fastify), para manejar el transporte HTTP real debajo del grafo de módulos resuelto.
A partir de los metadatos en tiempo de compilación generados por decoradores (@Injectable(), @Controller()) y los tipos de parámetros del constructor, registrados a través de emitDecoratorMetadata de TypeScript y la librería reflect-metadata; el contenedor lee esos metadatos al inicio en lugar de requerir un registro manual.
Es una clase decorada con @Module() que declara qué proveedores posee, qué controladores manejan sus rutas y qué proveedores exportados de otros módulos importa; cada módulo es un nodo en el grafo de dependencias general de la aplicación.
Para dar a las distintas preocupaciones transversales un lugar definido y predecible en una tubería fija: decisiones de autorización en guards, comportamiento de envoltura en interceptors, validación de argumentos en pipes, en lugar de competir por la posición en una lista de middleware indiferenciada.
Por defecto, sí: una instancia por cada ciclo de vida de la aplicación, resuelta una vez al inicio. El estado específico de la solicitud requiere optar explícitamente por un proveedor en Scope.REQUEST, lo que lo reinstancia por solicitud con un costo adicional.
Debido a que el grafo de módulos y el contenedor DI son agnósticos al transporte, la misma arquitectura respalda el modo de microservicios de NestJS, intercambiando el adaptador por un transporte no HTTP (TCP, Redis, una cola de mensajes) mientras que los proveedores, guards y el resto del grafo permanecen conceptualmente iguales.
Resolver un grafo de dependencias completo (leer metadatos de decoradores, instanciar proveedores singleton en el orden correcto) lleva tiempo y memoria medibles antes de que el servidor pueda aceptar su primera solicitud, a diferencia de una cadena de middleware plana o un árbol de plugins con comparativamente poco que resolver de antemano.
Para servicios pequeños, prototipos o equipos que no necesitan una arquitectura impuesta y testeabilidad inyectada por constructor; el contenedor, los metadatos del decorador y el boilerplate del módulo añaden una sobrecarga real que una cadena Express plana o un árbol de plugins Fastify ligero evitan por completo.
El paso manual de dependencias (funciones de fábrica, cierres) logra una testeabilidad similar sin un contenedor, pero requiere que el equipo imponga la disciplina por sí mismo; el contenedor de NestJS hace que la inyección de constructor sea el patrón predeterminado y consistente en toda la base de código.
Una forma de construir un grafo de módulos real para pruebas mientras se sustituye cualquier proveedor con overrideProvider().useValue(), de modo que un controlador o servicio se pueda probar contra dependencias simuladas sin tocar la base de datos real, la API externa u otros proveedores de los que depende.
No, los módulos te dan un límite de dependencia impuesto, pero tú sigues decidiendo cómo agrupar las características en módulos. Una mala agrupación (un módulo gigante con todo dentro) anula el beneficio de la arquitectura, aunque el mecanismo de DI siga funcionando técnicamente.
Versiones de la pila: Esta página fue escrita para NestJS 11 en Node.js 24 LTS, con TypeScript 5.6+.
Revisado por Chris St. John·Última actualización: 15 jul 2026