Express.js
Explica cómo organizar una aplicación Express.js por features y boundaries, separando transporte, casos de uso, dominio, datos e infraestructura sin carpetas genéricas.
La estructura de un proyecto debe hacer visibles las responsabilidades y dependencias reales. Una carpeta no crea arquitectura, pero puede ayudar a preservarla.
Express no impone organización. El objetivo es que un cambio de negocio afecte una zona predecible y que el transporte HTTP no domine todo el código.
Una estructura por feature puede ser:
src/
app/
create-app.ts
error-handler.ts
config/
load-config.ts
modules/
orders/
http/
orders.router.ts
create-order.handler.ts
create-order.schema.ts
order.response.ts
application/
create-order.ts
cancel-order.ts
domain/
order.ts
order-errors.ts
infrastructure/
postgres-order.repository.ts
shared/
database/
logging/
server.tsEstructuras globales como:
controllers/
services/
repositories/
models/parecen ordenadas al inicio, pero dispersan una feature entre muchas carpetas. Para cambiar pedidos debes saltar por todo el proyecto.
Agrupar por feature mantiene juntos contratos relacionados y reduce imports cruzados.
Conoce Express, request, response, status, headers y schemas de transporte.
Coordina casos de uso, transacciones y dependencias mediante contratos explícitos.
Contiene reglas y conceptos que pueden expresarse sin Express ni PostgreSQL. No todo proyecto necesita un dominio rico.
Implementa DB, gateways, queues y detalles externos.
Las capas son una herramienta. Una aplicación CRUD pequeña puede combinar application/domain sin perder claridad.
HTTP → application → domain
infrastructure → contracts de application/domainEl caso de uso no debería importar Express. El repository PostgreSQL implementa una interfaz que la aplicación consume.
No conviertas esta dirección en ceremonias: TypeScript interfaces solo aportan valor cuando existe sustitución, test o boundary real.
Cada feature puede exponer una factory:
export function createOrdersModule(deps: OrdersDependencies) {
const createOrder = new CreateOrder(deps);
return {
router: createOrdersRouter({ createOrder }),
};
}El composition root importa esta API, no archivos internos arbitrarios.
server.ts o una factory superior conecta implementaciones:
const ordersRepository = new PostgresOrderRepository(pool);
const ordersModule = createOrdersModule({
orders: ordersRepository,
clock,
ids,
});
app.use('/orders', ordersModule.router);La dependencia es visible y centralizada.
Una carpeta shared suele acumular utilidades sin dueño. Mueve allí solo piezas realmente transversales y estables:
Una regla de pedidos no es shared porque otro módulo la llamó una vez.
No existe número mágico. Divide cuando:
No crees un archivo por función trivial si aumenta navegación sin aportar boundary.
Nombres orientados a intención:
create-order.ts
reserve-inventory.ts
map-order-error.tsmejor que:
order-service.ts
utils.ts
helper.tsLos nombres genéricos esconden responsabilidad.
Distingue:
Pueden compartir forma en una app pequeña, pero no deben quedar acoplados por accidente.
Cada módulo recibe configuración relevante, no process.env completo. Esto facilita tests y evita dependencias ocultas.
Los errores de dominio viven junto al módulo. El mapper HTTP central conoce categorías o códigos, no detalles internos de cada query.
Evita una jerarquía universal de 30 clases si simples discriminated unions expresan mejor el resultado.
orders.router.ts
orders.handlers.ts
orders.repository.tsSepara application, HTTP e infrastructure.
Evalúa límites más fuertes, packages o servicios.
No empieces con microservicios para resolver una carpeta grande.
La creación de pedidos cambia para emitir outbox:
create-order.ts coordina.postgres-order.repository.ts persiste.orders.router.ts no cambia salvo contrato.La estructura reduce el radio de impacto.
Usa herramientas/lint para detectar ciclos. Los ciclos suelen indicar módulos sin dirección clara o un shared mal definido.
No resuelvas todos los ciclos moviendo código a common; identifica ownership.
Un monorepo puede separar packages de contratos, SDK o módulos compartidos, pero añade build y versionado. No es requisito para una buena estructura Express.
La estructura debe permitir:
Si un test necesita mockear 20 imports globales, las dependencias están ocultas.
utils como vertedero.shared/utils es riesgoso?Dependency injection pragmática hace explícitas esas dependencias sin requerir un framework de contenedor.