Busca en todas las páginas de la documentación
La inyección de dependencias (DI) proporciona a los casos de uso sus dependencias (repositorios, gateways, loggers) en lugar de importar singletons. En Node.js, puedes cablear manualmente, usar Awilix o confiar en la DI integrada de NestJS 11.
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
// DI manual - raíz de composición
const orders = new PostgresOrderRepository(pool);
const createOrder = new CreateOrder(orders);
app.post("/orders", (req, res) => createOrder.execute(req.body));// Awilix - contenedor
import { createContainer, asClass, asValue } from "awilix";
const container = createContainer();
container.register({
pool: asValue(pool),
orderRepository: asClass(PostgresOrderRepository).singleton(),
createOrder: asClass(CreateOrder).singleton(),
});Cuándo usarlo:
// application/create-order.ts
import type { OrderRepository } from "../domain/ports/order-repository";
export class CreateOrder {
constructor(private readonly orders: OrderRepository) {}
async execute(input: { customerId: string; sku: string; qty: number }) {
const order = { id: crypto.randomUUID(), ...input, status: "pending" as const };
await this.orders.save(order);
return order;
}
}
// raíz de composición manual
import express from "express";
import { Pool } from "pg";
import { PostgresOrderRepository } from "./infrastructure/postgres-order-repository";
import { CreateOrder } from "./application/create-order";
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const createOrder = new CreateOrder(new PostgresOrderRepository(pool));
const app = express();
app.use(express.json());
app.post("/orders", async (req, res) => {
res.status(201).json({ data: await createOrder.execute(req.body) });
});
// Alternativa Awilix - src/container.ts
import { createContainer, asClass, asValue, InjectionMode } from "awilix";
export function buildContainer(pool: Pool) {
const container = createContainer({ injectionMode: InjectionMode.CLASSIC });
container.register({
pool: asValue(pool),
orderRepository: asClass(PostgresOrderRepository).singleton(),
createOrder: asClass(CreateOrder).singleton(),
});
return container;
}
// Resolver en main
// const { createOrder } = buildContainer(pool).cradle;Lo que esto demuestra:
CreateOrder depende solo de la interfaz OrderRepositorymain.ts o container.ts - el único lugar que news adaptadores concretos@Injectable(), inyección por constructor, importaciones/exportaciones de módulos| Patrón | Pros | Contras | Mejor para |
|---|---|---|---|
| Manual | Obvio, cero magia, pruebas rápidas | Verboso a escala | <15 enlaces |
| Awilix | Cableado automático, ciclos de vida con ámbito | Curva de aprendizaje, resolución en tiempo de ejecución | Express/Fastify de tamaño mediano |
| Nest DI | Módulos de primera clase, utilidades de prueba | Opinión de decoradores, costo de arranque | Equipos estándar de Nest |
proxyquire/mocks de módulos | Hack rápido | Frágil, rompe el encapsulamiento | Evitar en código de producción |
@Injectable()
export class CreateOrder {
constructor(private readonly orders: OrderRepository) {}
}
@Module({
providers: [
CreateOrder,
{ provide: "OrderRepository", useClass: PostgresOrderRepository },
],
controllers: [OrdersController],
})
export class OrdersModule {}// Inyección basada en tokens sin magia de cadenas - usa símbolos o interfaces
export const OrderRepositoryToken = Symbol("OrderRepository");
type OrderRepository = import("../domain/ports/order-repository").OrderRepository;container.resolve disperso en las rutas. Solución: Resolver una vez al inicio; inyectar en los manejadores.export const db = new Pool(). Solución: Registrar en la raíz de composición; pasar a los repositorios.| Alternativa | Usar Cuándo | No Usar Cuándo |
|---|---|---|
| Funciones de fábrica manuales | Servicios pequeños de Fastify | Más de 30 casos de uso con dependencias compartidas |
tsyringe | DI de decoradores sin Nest | El equipo evita los decoradores |
| Funciones puras + parámetro de dependencias | Estilo funcional | Grafos grandes con configuración compartida |
| Sin DI - importar singletons | Scripts desechables | APIs de larga duración |
Cuando tienes más de 10 clases para cablear y cadenas new repetidas en main.ts. Antes de eso, el manual es más claro.
No tiene DI de primera clase. Usa manual, Awilix o fastify-decorators con cuidado.
Registra dobles de prueba: container.register({ orderRepository: asValue(inMemoryRepo) }).
Usa AsyncLocalStorage o un ámbito hijo de contenedor por solicitud en Awilix (patrón de plugin scopePerRequest).
Los proveedores con ámbito REQUEST añaden sobrecarga. Por defecto, singleton; usa REQUEST solo para estados verdaderamente por solicitud.
Sí, durante la migración. Los nuevos módulos se registran en Awilix; los legados permanecen manuales hasta que se tocan.
Las interfaces de TypeScript se borran en tiempo de ejecución. Usa una clase abstracta, un símbolo de token o un token de cadena en Nest.
Construye un contenedor más pequeño en el main del worker con dependencias específicas del trabajo; comparte el singleton del pool.
Para objetos de valor y tipos de dominio puros, sí. Para repositorios y clientes HTTP, no, inyéctalos.
Nivel superior del manejador de Lambda: el arranque en frío construye el contenedor una vez, reutilízalo en invocaciones en la misma instancia.
Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.
Revisado por Chris St. John·Última actualización: 19 jul 2026