Conceptos básicos de modularidad

7 ejemplos para empezar con la Modularidad en backends de Node.js: 5 básicos y 2 intermedios.

Requisitos previos

TypeScript 5.6+, Express 5 o Fastify 5, y una carpeta src/ con al menos una ruta de API.

npm install express@5 zod
npm install -D typescript@5.6 tsx

Ejemplos básicos

1. Manejador de ruta delgado

La ruta analiza HTTP y delega.

// infrastructure/http/orders-router.ts
import express from "express";
import { createOrder } from "../../application/create-order";
 
export const ordersRouter = express.Router();
 
ordersRouter.post("/", async (req, res, next) => {
  try {
    const order = await createOrder(req.body);
    res.status(201).json({ data: order });
  } catch (err) {
    next(err);
  }
});

El objetivo es un manejador de menos de 10 líneas
createOrder no tiene importaciones de Express
Los errores fluyen a un middleware de errores centralizado

Relacionado: Casos de uso y servicios - capa de aplicación

2. Función de caso de uso con dependencias explícitas

// application/create-order.ts
import type { OrderRepository } from "../domain/ports/order-repository";
 
export type CreateOrderDeps = { orders: OrderRepository };
 
export async function createOrder(
  deps: CreateOrderDeps,
  input: { customerId: string; sku: string; qty: number }
) {
  if (input.qty <= 0) throw new Error("INVALID_QTY");
  const order = { id: crypto.randomUUID(), ...input, status: "pending" as const };
  await deps.orders.save(order);
  return order;
}

Las dependencias se pasan explícitamente, sin singletons ocultos
La prueba unitaria pasa un OrderRepository en memoria
Los errores de dominio se lanzan como errores tipados en aplicaciones más grandes

3. Interfaz de puerto para persistencia

// domain/ports/order-repository.ts
export type Order = {
  id: string;
  customerId: string;
  sku: string;
  qty: number;
  status: "pending" | "shipped";
};
 
export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

La aplicación depende de la interfaz, no de Prisma
El adaptador en infrastructure/ implementa el puerto
Cambiar Postgres por DynamoDB modifica un solo archivo

Relacionado: Patrón de Repositorio - dobles de prueba

4. Dirección de importación prohibida

Permitido:
  infrastructure/http  -> application -> domain
 
Prohibido:
  domain -> express
  domain -> infrastructure
  application -> express Request type

ESLint no-restricted-imports codifica la regla en CI
Los tipos de framework se detienen en el adaptador HTTP
Mantiene los casos de uso invocables desde CLI y workers de cola

Relacionado: Mejores prácticas de modularidad - lista de verificación de cumplimiento

5. La raíz de composición conecta las dependencias

// main.ts
import express from "express";
import { ordersRouter } from "./infrastructure/http/orders-router";
import { PostgresOrderRepository } from "./infrastructure/postgres-order-repository";
import { createOrderHandler } from "./infrastructure/http/create-order-handler";
 
const orders = new PostgresOrderRepository(pool);
const app = express();
app.use(express.json());
app.use("/orders", createOrderHandler({ orders }));
app.listen(3000);

Solo main.ts conoce las clases concretas
Los manejadores cierran las dependencias a través de funciones de fábrica
Las pruebas de integración construyen una raíz de composición alternativa

Relacionado: Patrones de inyección de dependencias - manual vs Awilix vs Nest

Ejemplos intermedios

6. Kernel compartido vs Módulo de características

src/
├── modules/orders/     # módulo de características - posee las reglas de pedidos
├── modules/billing/
└── shared/
    ├── errors.ts       # Clase base AppError
    └── logger.ts       # instancia de pino

shared/ no tiene reglas de negocio como el cálculo de impuestos
Si dos módulos necesitan lógica fiscal, billing la posee y expone un servicio
Evita el archivo "dios" shared/utils.ts

7. Probar caso de uso sin HTTP

import { describe, it, expect } from "node:test";
import { createOrder } from "../application/create-order";
 
describe("createOrder", () => {
  it("guarda un pedido válido", async () => {
    const saved: unknown[] = [];
    const orders = { save: async (o: unknown) => { saved.push(o); }, findById: async () => null };
    const result = await createOrder({ orders }, { customerId: "c1", sku: "SKU1", qty: 2 });
    expect(result.status).toBe("pending");
    expect(saved).toHaveLength(1);
  });
});

node:test se ejecuta en milisegundos
Sin supertest, sin enlace de puerto
El mismo patrón se escala a Vitest/Jest

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.

Requisitos previos

TypeScript 5.6+, Express 5 o Fastify 5, y una carpeta src/ con al menos una ruta de API.

npm install express@5 zod
npm install -D typescript@5.6 tsx

Ejemplos básicos

1. Manejador de ruta delgado

La ruta analiza HTTP y delega.

// infrastructure/http/orders-router.ts
import express from "express";
import { createOrder } from "../../application/create-order";
 
export const ordersRouter = express.Router();
 
ordersRouter.post("/", async (req, res, next) => {
  try {
    const order = await createOrder(req.body);
    res.status(201).json({ data: order });
  } catch (err) {
    next(err);
  }
});

El objetivo es un manejador de menos de 10 líneas
createOrder no tiene importaciones de Express
Los errores fluyen a un middleware de errores centralizado

Relacionado: Casos de uso y servicios - capa de aplicación

2. Función de caso de uso con dependencias explícitas

// application/create-order.ts
import type { OrderRepository } from "../domain/ports/order-repository";
 
export type CreateOrderDeps = { orders: OrderRepository };
 
export async function createOrder(
  deps: CreateOrderDeps,
  input: { customerId: string; sku: string; qty: number }
) {
  if (input.qty <= 0) throw new Error("INVALID_QTY");
  const order = { id: crypto.randomUUID(), ...input, status: "pending" as const };
  await deps.orders.save(order);
  return order;
}

Las dependencias se pasan explícitamente, sin singletons ocultos
La prueba unitaria pasa un OrderRepository en memoria
Los errores de dominio se lanzan como errores tipados en aplicaciones más grandes

3. Interfaz de puerto para persistencia

// domain/ports/order-repository.ts
export type Order = {
  id: string;
  customerId: string;
  sku: string;
  qty: number;
  status: "pending" | "shipped";
};
 
export interface OrderRepository {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

La aplicación depende de la interfaz, no de Prisma
El adaptador en infrastructure/ implementa el puerto
Cambiar Postgres por DynamoDB modifica un solo archivo

Relacionado: Patrón de Repositorio - dobles de prueba

4. Dirección de importación prohibida

Permitido:
  infrastructure/http  -> application -> domain
 
Prohibido:
  domain -> express
  domain -> infrastructure
  application -> express Request type

ESLint no-restricted-imports codifica la regla en CI
Los tipos de framework se detienen en el adaptador HTTP
Mantiene los casos de uso invocables desde CLI y workers de cola

Relacionado: Mejores prácticas de modularidad - lista de verificación de cumplimiento

5. La raíz de composición conecta las dependencias

// main.ts
import express from "express";
import { ordersRouter } from "./infrastructure/http/orders-router";
import { PostgresOrderRepository } from "./infrastructure/postgres-order-repository";
import { createOrderHandler } from "./infrastructure/http/create-order-handler";
 
const orders = new PostgresOrderRepository(pool);
const app = express();
app.use(express.json());
app.use("/orders", createOrderHandler({ orders }));
app.listen(3000);

Solo main.ts conoce las clases concretas
Los manejadores cierran las dependencias a través de funciones de fábrica
Las pruebas de integración construyen una raíz de composición alternativa

Relacionado: Patrones de inyección de dependencias - manual vs Awilix vs Nest

Ejemplos intermedios

6. Kernel compartido vs Módulo de características

src/
├── modules/orders/     # módulo de características - posee las reglas de pedidos
├── modules/billing/
└── shared/
    ├── errors.ts       # Clase base AppError
    └── logger.ts       # instancia de pino

shared/ no tiene reglas de negocio como el cálculo de impuestos
Si dos módulos necesitan lógica fiscal, billing la posee y expone un servicio
Evita el archivo "dios" shared/utils.ts

7. Probar caso de uso sin HTTP

import { describe, it, expect } from "node:test";
import { createOrder } from "../application/create-order";
 
describe("createOrder", () => {
  it("guarda un pedido válido", async () => {
    const saved: unknown[] = [];
    const orders = { save: async (o: unknown) => { saved.push(o); }, findById: async () => null };
    const result = await createOrder({ orders }, { customerId: "c1", sku: "SKU1", qty: 2 });
    expect(result.status).toBe("pending");
    expect(saved).toHaveLength(1);
  });
});

node:test se ejecuta en milisegundos
Sin supertest, sin enlace de puerto
El mismo patrón se escala a Vitest/Jest

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.

Conceptos básicos de modularidad

Buscar en la documentación

Conceptos básicos de modularidad