Busca en todas las páginas de la documentación
La arquitectura hexagonal (puertos y adaptadores) mantiene tus reglas de negocio en el centro y empuja los frameworks, bases de datos y colas a los bordes. En Node.js, eso significa que las rutas de Express y los clientes de Prisma nunca se filtran en el código de dominio.
Tarjeta de receta de referencia rápida: lista para copiar y pegar.
// domain/ports/notification-port.ts
export interface NotificationPort {
send(to: string, body: string): Promise<void>;
}
// application/place-order.ts
export class PlaceOrder {
constructor(
private readonly orders: OrderRepository,
private readonly notifications: NotificationPort
) {}
async execute(input: { customerId: string; sku: string }) {
const order = { id: crypto.randomUUID(), ...input };
await this.orders.save(order);
await this.notifications.send(input.customerId, `Order ${order.id} placed`);
return order;
}
}Cuándo usarlo:
// src/modules/billing/domain/ports/invoice-repository.ts
export type Invoice = { id: string; customerId: string; amountCents: number };
export interface InvoiceRepository {
save(invoice: Invoice): Promise<void>;
}
// src/modules/billing/domain/ports/payment-gateway.ts
export interface PaymentGateway {
charge(customerId: string, amountCents: number): Promise<{ chargeId: string }>;
}
// src/modules/billing/application/charge-invoice.ts
export class ChargeInvoice {
constructor(
private readonly invoices: InvoiceRepository,
private readonly payments: PaymentGateway
) {}
async execute(invoiceId: string) {
// carga, cobra, persiste - no hay tipos HTTP aquí
const invoice = { id: invoiceId, customerId: "c1", amountCents: 5000 };
const { chargeId } = await this.payments.charge(invoice.customerId, invoice.amountCents);
await this.invoices.save({ ...invoice, id: chargeId });
return { invoiceId, chargeId };
}
}
// src/modules/billing/infrastructure/http/routes.ts
import express from "express";
import type { ChargeInvoice } from "../../application/charge-invoice";
export function billingRouter(chargeInvoice: ChargeInvoice) {
const router = express.Router();
router.post("/invoices/:id/charge", async (req, res, next) => {
try {
const result = await chargeInvoice.execute(req.params.id);
res.json({ data: result });
} catch (err) {
next(err);
}
});
return router;
}
// src/modules/billing/infrastructure/stripe-payment-gateway.ts
import type { PaymentGateway } from "../../domain/ports/payment-gateway";
export class StripePaymentGateway implements PaymentGateway {
async charge(customerId: string, amountCents: number) {
return { chargeId: `ch_${customerId}_${amountCents}` };
}
}
// src/main.ts - root de composición
import express from "express";
import { ChargeInvoice } from "./modules/billing/application/charge-invoice";
import { billingRouter } from "./modules/billing/infrastructure/http/routes";
import { StripePaymentGateway } from "./modules/billing/infrastructure/stripe-payment-gateway";
const chargeInvoice = new ChargeInvoice(
{ save: async () => {} },
new StripePaymentGateway()
);
const app = express();
app.use(express.json());
app.use("/billing", billingRouter(chargeInvoice));
app.listen(3000);Lo que esto demuestra:
ChargeInvoice depende solo de las interfaces de los puertos, no de Stripe o Expressmain.ts es el único lugar que elige adaptadores concretosChargeInvoice con los mismos puertos| Carpeta | Contiene | No debe importar |
|---|---|---|
domain/ | Entidades, errores de dominio, interfaces de puerto | express, fastify, prisma, ioredis |
application/ | Casos de uso, DTOs entre capas | Tipos de solicitud HTTP, clientes ORM |
infrastructure/http/ | Rutas, controladores, middleware | Dominio de otros módulos |
infrastructure/persistence/ | Adaptadores de repositorio | Internos de casos de uso de la aplicación |
main.ts | Cableado, inicio del servidor | Reglas de negocio |
src/modules/billing/
├── domain/
│ ├── invoice.ts
│ └── ports/
│ ├── invoice-repository.ts
│ └── payment-gateway.ts
├── application/
│ └── charge-invoice.ts
└── infrastructure/
├── http/routes.ts
├── postgres-invoice-repository.ts
└── stripe-payment-gateway.ts// Prefiere interfaces de puerto pequeñas - más fáciles de simular en las pruebas
export interface Clock {
now(): Date;
}
export class ExpireSessions {
constructor(private readonly clock: Clock) {}
isExpired(createdAt: Date, ttlMs: number): boolean {
return this.clock.now().getTime() - createdAt.getTime() > ttlMs;
}
}
// Doble de prueba
const fixedClock: Clock = { now: () => new Date("2026-01-01T00:00:00Z") };save(prismaOrder) acopla el dominio a Prisma. Solución: Mapea entre entidades de dominio y DTOs de persistencia solo dentro del adaptador.main.ts se convierte en 400 líneas de cableado. Solución: Fábricas registerBillingModule() por módulo que devuelven routers y servicios.InMemoryInvoiceRepository junto con el real.| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
MVC en capas (controllers/services/repos) | APIs CRUD pequeñas, equipos con muchos juniors | Múltiples puntos de entrada o cambios frecuentes de infraestructura |
| Módulos NestJS con DI | El equipo ya estandarizó en Nest 11 | Servicios Fastify ligeros donde los decoradores se sienten pesados |
| Script de transacción en manejadores de rutas | Spikes y prototipos de menos de una semana | Código de producción que se espera que viva más de 12 meses |
| Arquitectura Limpia (misma idea, más capas) | Dominios grandes con reglas complejas | BFFs simples sin lógica de dominio |
Un puerto es una interfaz que tu aplicación define (NotificationPort). Un adaptador es la implementación concreta que se comunica con el mundo real (SendGridNotificationAdapter, InMemoryNotificationAdapter).
No. Una función chargeInvoice(deps, input) funciona si las dependencias se pasan explícitamente. Las clases ayudan cuando los casos de uso llevan estado o usas un contenedor DI.
En el límite del adaptador HTTP. Analiza req.body en un DTO tipado, luego pasa objetos planos al caso de uso. La validación de dominio cubre invariantes que Zod no puede expresar (por ejemplo, "la factura no debe ser cobrada dos veces").
Sí. Los proveedores de Nest implementan puertos; los controladores son adaptadores de conducción. Mantén las carpetas de dominio libres de @Injectable() si quieres pruebas unitarias sin framework.
Prefiere los puertos locales del módulo. Si dos módulos necesitan la misma abstracción, mueve el puerto a shared/ports/ solo cuando exista un segundo consumidor; evita los kernels compartidos prematuros.
Sí. Un consumidor de BullMQ es un adaptador de conducción que deserializa una carga útil de trabajo y llama al mismo caso de uso que tu ruta HTTP.
Si cada llamada externa tiene su propio puerto, es posible que estés sobre-abstraiendo. Comienza con repositorios y gateways que esperas intercambiar o simular en las pruebas.
Envuelve Prisma en un adaptador de repositorio. Nunca exportes PrismaClient desde las capas de dominio o aplicación.
Extrae un caso de uso y un puerto a la vez. Deja las rutas heredadas llamando al código antiguo hasta que se pruebe la nueva ruta, luego elimina el bloque antiguo.
Relacionado pero no idéntico. Hexagonal se trata de la dirección de la dependencia; DDD agrega contextos delimitados, agregados y lenguaje ubicuo. Puedes usar hexagonal sin DDD completo.
Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.
Revisado por Chris St. John·Última actualización: 19 jul 2026