Mejores Prácticas de Modularidad

Dirección de importación: rutas → casos de uso → dominio. Estas prácticas mantienen los código base de Node.js testeables y listos para cambios de framework o persistencia.

Cómo Usar Esta Lista

• Automatiza las reglas de importación antes de los debates de revisión de código
• Aplícalo a workers y puntos de entrada CLI, no solo HTTP
• Combínalo con las Mejores Prácticas de Arquitectura para límites macro
• Las nuevas rutas deben llamar a casos de uso existentes, sin orquestación duplicada

A - Disciplina de Capas

• Los manejadores de rutas se mantienen por debajo de 15 líneas. Parsean, autorizan, llaman al caso de uso, mapean la respuesta.
• Los casos de uso son dueños de la orquestación y las reglas de aplicación. No los repositorios, no las rutas.
• La capa de dominio no tiene importaciones de express, fastify, @nestjs/*, prisma, ioredis.
• La infraestructura implementa puertos definidos en el dominio/aplicación. Mapea filas de ORM a entidades de dominio en el adaptador.
• La raíz de composición es el único lugar que instancia adaptadores concretos.

B - Dirección de Importación

• Flujo permitido: infrastructure → application → domain. Nunca dominio → infraestructura.
• Las llamadas entre características pasan por la API pública del módulo o el servicio de aplicación. No se accede a infrastructure/ de pares.
• CI ejecuta dependency-cruiser o ESLint para fallar importaciones prohibidas.
• El kernel compartido contiene solo utilidades. No hay reglas de precios, impuestos o descuentos en shared/.
• Los archivos barrel exportan una superficie pública intencional. No export * from './infrastructure'.

C - Pruebas

• Pruebas unitarias de casos de uso con repositorios en memoria. Pruebas de menos de 10 ms por comando.
• Las pruebas de integración acceden a Postgres real a través de Testcontainers para adaptadores de repositorio.
• Las pruebas HTTP (supertest) cubren códigos de estado y autenticación. No cada rama de regla de negocio.
• Los workers llaman a los mismos casos de uso que las rutas HTTP. Sin lógica de negocio bifurcada.
• Reinicia el contenedor DI o la caché de configuración entre pruebas.

D - Diseño de Casos de Uso

• Un caso de uso por comando o consulta. No OrderGodService.
• Tipos de entrada/salida explícitos. Los adaptadores mapean a DTOs JSON.
• Las comprobaciones de autorización residen en el caso de uso o en la política de dominio. No solo en el middleware de ruta.
• Idempotencia y transacciones documentadas por caso de uso.
• Devuelve errores de dominio tipados (AppError). El mapeador HTTP central traduce los códigos.

E - Persistencia

• Las interfaces de repositorio expresan lenguaje de dominio. findById, no findUnique.
• No hay cliente Prisma en los casos de uso. Inyecta OrderRepository.
• Los informes pesados utilizan modelos de lectura o servicios de consulta. No repositorios inflados.
• Repositorio en memoria enviado junto con el adaptador de Postgres para pruebas rápidas.
• Cursores de paginación devueltos desde el puerto del repositorio cuando las listas son grandes.

F - Notas del Framework (Express 5 / Fastify 5 / Nest 11)

• Express/Fastify: routers de fábrica ordersRouter(deps) para inyección.
• Fastify: usa plugins con ámbito encapsulado cuando los módulos necesitan aislamiento.
• Nest: controladores delgados; proveedores mapean a casos de uso. Evita la clase "dios" OrdersService gorda.
• Valida req.body con Zod en el borde HTTP antes de execute().
• Un framework HTTP por desplegable. No mezcles Express y Fastify en un solo proceso.

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Modularidad - ejemplos introductorios
• Casos de Uso y Servicios - capa de aplicación
• Patrón Repositorio - puertos de persistencia
• Patrones de Inyección de Dependencias - cableado
• Lista de Verificación de Refactorización - auditoría estructural

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS Activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.