Busca en todas las páginas de la documentación
La capa de aplicación implementa casos de uso, que son pasos de orquestación que cumplen una intención de usuario ("Realizar pedido", "Reembolsar factura"). Los servicios agrupan casos de uso relacionados cuando comparten políticas; los repositorios y las pasarelas se encuentran detrás de los puertos.
Tarjeta de receta de referencia rápida: lista para copiar y pegar.
// application/place-order.ts
export class PlaceOrder {
constructor(
private readonly orders: OrderRepository,
private readonly inventory: InventoryPort
) {}
async execute(cmd: { customerId: string; sku: string; qty: number }) {
await this.inventory.reserve(cmd.sku, cmd.qty);
const order = { id: crypto.randomUUID(), ...cmd, status: "pending" as const };
await this.orders.save(order);
return order;
}
}Cuándo usarlo:
// domain/ports/order-repository.ts
export type Order = { id: string; customerId: string; sku: string; qty: number; status: string };
export interface OrderRepository {
save(order: Order): Promise<void>;
}
// domain/ports/inventory-port.ts
export interface InventoryPort {
reserve(sku: string, qty: number): Promise<void>;
}
// application/place-order.ts
export class PlaceOrder {
constructor(
private readonly orders: OrderRepository,
private readonly inventory: InventoryPort
) {}
async execute(cmd: { customerId: string; sku: string; qty: number }) {
if (cmd.qty <= 0) throw new AppError("INVALID_QTY", 400);
await this.inventory.reserve(cmd.sku, cmd.qty);
const order = { id: crypto.randomUUID(), ...cmd, status: "pending" };
await this.orders.save(order);
return order;
}
}
// application/order-service.ts - fachada opcional para comandos relacionados
export class OrderService {
constructor(
private readonly placeOrder: PlaceOrder,
private readonly cancelOrder: CancelOrder
) {}
place(cmd: Parameters<PlaceOrder["execute"]>[0]) {
return this.placeOrder.execute(cmd);
}
cancel(orderId: string) {
return this.cancelOrder.execute(orderId);
}
}
// infrastructure/http/orders-controller.ts
import express from "express";
import type { PlaceOrder } from "../../application/place-order";
export function ordersRouter(placeOrder: PlaceOrder) {
const router = express.Router();
router.post("/", async (req, res, next) => {
try {
const order = await placeOrder.execute(req.body);
res.status(201).json({ data: toOrderDto(order) });
} catch (err) {
next(err);
}
});
return router;
}
function toOrderDto(order: { id: string; status: string }) {
return { id: order.id, status: order.status };
}
class AppError extends Error {
constructor(
public code: string,
public status: number
) {
super(code);
}
}
class CancelOrder {
async execute(_orderId: string) {
return { cancelled: true };
}
}Lo que esto demuestra:
PlaceOrder secuencia el inventario y luego la persistenciaOrderService es opcional cuando múltiples comandos comparten la entrada del módulo| Patrón de nombre | Ejemplo |
|---|---|
| Comando de verbo | PlaceOrder, CancelSubscription |
| Consulta | GetOrderById, ListOpenInvoices |
| Servicio de política | PricingService (reglas puras, sin E/S) |
| Capa | Responsabilidad |
|---|---|
| Servicio de dominio | Reglas de negocio puras sobre entidades |
| Caso de uso | Orquestar puertos, transacciones, comprobaciones de autorización |
// Tipos de entrada/salida explícitos para el mapeo del adaptador
export type PlaceOrderInput = { customerId: string; sku: string; qty: number };
export type PlaceOrderResult = { id: string; status: "pending" };OrderEverything con 12 responsabilidades. Solución: Dividir por comando/consulta.Result.canPlaceOrder(user, cmd).PlaceOrder.execute.| Alternativa | Usar Cuándo | No Usar Cuándo |
|---|---|---|
| Script de transacción en ruta | CRUD de 3 puntos finales | Las reglas y la orquestación crecen |
| Manejadores CQRS | División de escala de lectura/escritura | CRUD simple |
| Solo eventos de dominio | Flujos de trabajo con muchos eventos | Flujos síncronos simples |
| Manejadores de comandos de Nest | Módulo CQRS de Nest adoptado | Servicios Express simples |
Ambos funcionan. Las clases ayudan a los contenedores de DI; las funciones con el parámetro deps están bien para la DI manual.
El adaptador HTTP valida la forma; el caso de uso valida las reglas de negocio (inventario disponible, cuenta activa).
Sí. GetOrderById es un caso de uso de consulta: solo lectura, sin efectos secundarios.
El caso de uso llama al puerto unitOfWork.withTransaction(async () => { ... }) o a un método de repositorio que acepta un cliente.
Prefiere componer servicios de dominio más pequeños o ayudantes privados compartidos. Las cadenas profundas de casos de uso ocultan el flujo.
El mismo patrón: la ruta llama a placeOrder.execute; usa la fábrica FastifyPlugin para la inyección.
Menos de 150 líneas. Extrae funciones privadas o servicios de dominio cuando la ramificación se dispara.
Acepta un puerto Logger o un registrador estructurado inyectado; registra eventos de negocio, no PII sin procesar.
La comprobación de la clave de idempotencia pertenece al caso de uso o a un caso de uso decorador IdempotentPlaceOrder dedicado.
OrdersService a menudo se convierte en casos de uso o en un envoltorio delgado alrededor de ellos; evita un OrdersService "Dios" gordo.
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: 16 jul 2026