Busque em todas as páginas da documentação
Injeção de Dependência (DI) fornece aos casos de uso suas dependências (repositórios, gateways, loggers) em vez de importar singletons. Em Node.js, você pode configurar manualmente, usar Awilix ou confiar na DI embutida do NestJS 11.
Cartão de receita de referência rápida - pronto para copiar e colar.
// DI Manual - raiz de composição
const orders = new PostgresOrderRepository(pool);
const createOrder = new CreateOrder(orders);
app.post("/orders", (req, res) => createOrder.execute(req.body));// Awilix - container
import { createContainer, asClass, asValue } from "awilix";
const container = createContainer();
container.register({
pool: asValue(pool),
orderRepository: asClass(PostgresOrderRepository).singleton(),
createOrder: asClass(CreateOrder).singleton(),
});Quando usar isso:
// 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;
}
}
// raiz de composição 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 em main
// const { createOrder } = buildContainer(pool).cradle;O que isso demonstra:
CreateOrder depende apenas da interface OrderRepositorygrepmain.ts ou container.ts - o único local que instancia classes concretas (new)@Injectable(), injeção de construtor, importações/exportações de módulos| Padrão | Prós | Contras | Melhor para |
|---|---|---|---|
| Manual | Óbvio, sem mágica, testes rápidos | Verboso em escala | <15 bindings |
| Awilix | Auto-configuração, tempos de vida com escopo | Curva de aprendizado, resolução em tempo de execução | Projetos Express/Fastify de médio porte |
| Nest DI | Módulos de primeira classe, utilitários de teste | Opinião de decorador, custo de inicialização | Equipes padronizadas em Nest |
proxyquire/mocks de módulo | Hack rápido | Frágil, quebra encapsulamento | Evitar em código de produção |
@Injectable()
export class CreateOrder {
constructor(private readonly orders: OrderRepository) {}
}
@Module({
providers: [
CreateOrder,
{ provide: "OrderRepository", useClass: PostgresOrderRepository },
],
controllers: [OrdersController],
})
export class OrdersModule {}// Injeção baseada em token sem "mágica de string" - use símbolos ou interfaces
export const OrderRepositoryToken = Symbol("OrderRepository");
type OrderRepository = import("../domain/ports/order-repository").OrderRepository;container.resolve espalhado em rotas. Correção: Resolver uma vez na inicialização; injetar em manipuladores.export const db = new Pool(). Correção: Registrar na raiz de composição; passar para repositórios.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Funções de fábrica manuais | Pequenos serviços Fastify | 30+ casos de uso com dependências compartilhadas |
tsyringe | DI com decoradores sem Nest | Equipe evita decoradores |
| Funções puras + parâmetro de dependências | Estilo funcional | Grandes grafos com configuração compartilhada |
| Sem DI - importar singletons | Scripts descartáveis | APIs de longa duração |
Quando você tem 10+ classes para configurar e cadeias de new repetidas em main.ts. Antes disso, o manual é mais claro.
Sem DI de primeira classe. Use manual, Awilix ou fastify-decorators com cuidado.
Registre "test doubles": container.register({ orderRepository: asValue(inMemoryRepo) }).
Use AsyncLocalStorage ou escopo filho do container por requisição em Awilix (padrão de plugin scopePerRequest).
Provedores com escopo REQUEST adicionam sobrecarga. Padrão é singleton; use REQUEST apenas para estado verdadeiramente por requisição.
Sim, durante a migração. Novos módulos se registram em Awilix; legados permanecem manuais até serem tocados.
Interfaces TypeScript são apagadas em tempo de execução. Use classe abstrata, token de símbolo ou token de string no Nest.
Construa um container menor no main do worker com dependências específicas do job - compartilhe o singleton do pool.
Para objetos de valor e tipos de domínio puros, sim. Para repositórios e clientes HTTP, não - injete-os.
No topo do manipulador Lambda: o "cold start" constrói o container uma vez, reutilizando-o entre invocações na mesma instância.
Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (LTS Ativo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.
Revisado por Chris St. John·Última atualização: 19 de jul. de 2026