· arquitectura hexagonal node.js

Guía práctica de arquitectura hexagonal con Node.js y TypeScript

Domina la arquitectura hexagonal con Node.js y TypeScript. Guía práctica para agencias y startups B2B. Mejora mantenibilidad y escalabilidad.

Guía práctica de arquitectura hexagonal con Node.js y TypeScript

En el vertiginoso mundo del desarrollo de software B2B, la agilidad, la mantenibilidad y la escalabilidad no son meros atributos deseables, sino requisitos fundamentales para el éxito. Las agencias y startups que buscan construir productos robustos y adaptables a largo plazo se enfrentan a un desafío constante: cómo estructurar su código para resistir el paso del tiempo y las inevitables evoluciones del negocio. Aquí es donde la arquitectura hexagonal Node.js emerge como una solución poderosa, especialmente cuando se combina con la robustez y expresividad de TypeScript.

Como copywriter senior especializado en software B2B, he visto de primera mano cómo las arquitecturas monolíticas o desorganizadas pueden convertirse en cuellos de botella, frenando la innovación y disparando los costos de mantenimiento. La arquitectura hexagonal, también conocida como Puertos y Adaptadores, ofrece un paradigma que desacopla el núcleo de la lógica de negocio de las preocupaciones externas, como bases de datos, APIs, interfaces de usuario o sistemas de terceros. Esto se traduce directamente en aplicaciones más fáciles de probar, mantener y evolucionar.

Si eres un Director de Producto, CTO o líder de equipo tecnológico hispanohablante, esta guía está diseñada para ti. Profundizaremos en los principios de la arquitectura hexagonal aplicados a Node.js y TypeScript, proporcionando ejemplos concretos y estrategias prácticas para su implementación. Prepárate para transformar tu enfoque de desarrollo y construir software que realmente perdure.

¿Qué es la Arquitectura Hexagonal y Por Qué Debería Importarte?

La arquitectura hexagonal, concebida por Alistair Cockburn, busca crear sistemas que sean independientes de sus tecnologías de infraestructura y que permitan la interacción a través de “puertos” y “adaptadores”. Imagina tu lógica de negocio como el núcleo de un hexágono. Las caras del hexágono representan los diferentes tipos de interacciones que tu aplicación puede tener con el mundo exterior.

La principal ventaja de este enfoque es el desacoplamiento. El núcleo de tu aplicación no sabe nada sobre la base de datos que utiliza, ni sobre cómo se le llama (REST, GraphQL, CLI). Esto significa que puedes cambiar la tecnología de la base de datos, añadir una nueva interfaz de usuario o integrar un nuevo servicio externo sin tener que modificar el código central de tu lógica de negocio.

Beneficios Clave para tu Negocio:

Imagina que tu startup lanza un MVP con una base de datos PostgreSQL. Con la arquitectura hexagonal, si en el futuro decides migrar a MongoDB por razones de escalabilidad o costo, el impacto en tu lógica de negocio será mínimo. Solo necesitarás reemplazar el adaptador de persistencia. Esto podría significar una reducción del tiempo de inactividad durante la migración de hasta un 70% y una disminución del 50% en los errores post-migración, según estudios internos de empresas que han adoptado este patrón.

Implementando la Arquitectura Hexagonal con Node.js y TypeScript

Node.js, con su naturaleza asíncrona y su ecosistema maduro, es una plataforma excelente para implementar la arquitectura hexagonal. TypeScript añade una capa de seguridad y expresividad que facilita la definición clara de interfaces y tipos, cruciales para este patrón.

Estructura de Carpetas Sugerida

Una estructura de carpetas bien organizada es fundamental. Aquí proponemos una estructura común que separa claramente las capas:

src/
├── domain/             # Lógica de negocio pura, independiente de la infraestructura
│   ├── models/         # Entidades de dominio
│   ├── services/       # Lógica de negocio central
│   ├── ports/          # Interfaces de puertos (ej: IUserRepository, IOrderService)
│   └── exceptions/     # Excepciones de dominio
├── infrastructure/     # Implementaciones de adaptadores y configuraciones
│   ├── adapters/       # Implementaciones de los puertos
│   │   ├── persistence/  # Adaptadores de base de datos (ej: PostgreSQLUserRepository)
│   │   ├── api/          # Adaptadores de API (ej: ExpressOrderController)
│   │   └── external/     # Adaptadores para servicios externos
│   ├── config/         # Configuraciones de infraestructura
│   └── index.ts        # Punto de entrada de la infraestructura
├── application/        # Orquestación, casos de uso (opcional, puede estar en domain)
│   └── usecases/       # Lógica de aplicación que orquesta el dominio
├── main.ts             # Punto de entrada principal de la aplicación
└── types/              # Tipos globales compartidos (si es necesario)

Definición de Puertos con TypeScript

Los puertos se definen como interfaces en TypeScript. Esto asegura que el dominio declare qué capacidades necesita sin especificar cómo se implementarán.

Ejemplo: Puerto de Salida para Usuarios

// src/domain/ports/IUserRepository.ts

export interface User {
  id: string;
  name: string;
  email: string;
}

export interface IUserRepository {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  save(user: User): Promise<void>;
}

Ejemplo: Puerto de Entrada para Órdenes

// src/domain/ports/IOrderService.ts

export interface Order {
  id: string;
  userId: string;
  items: string[];
  totalAmount: number;
  createdAt: Date;
}

export interface IOrderService {
  createOrder(userId: string, items: string[], totalAmount: number): Promise<Order>;
  getOrderById(orderId: string): Promise<Order | null>;
  getOrdersByUserId(userId: string): Promise<Order[]>;
}

Implementación de Adaptadores

Los adaptadores implementan las interfaces de los puertos. Aquí es donde interactuamos con tecnologías específicas.

Ejemplo: Adaptador de Persistencia (PostgreSQL)

// src/infrastructure/adapters/persistence/PostgreSQLUserRepository.ts
import { User, IUserRepository } from '../../../domain/ports/IUserRepository';
import { Pool } from 'pg'; // Asumiendo que usas 'pg' para PostgreSQL

export class PostgreSQLUserRepository implements IUserRepository {
  private pool: Pool;

  constructor(dbConfig: any) {
    this.pool = new Pool(dbConfig);
  }

  async findById(id: string): Promise<User | null> {
    const result = await this.pool.query('SELECT * FROM users WHERE id = $1', [id]);
    return result.rows.length > 0 ? result.rows[0] : null;
  }

  async findByEmail(email: string): Promise<User | null> {
    const result = await this.pool.query('SELECT * FROM users WHERE email = $1', [email]);
    return result.rows.length > 0 ? result.rows[0] : null;
  }

  async save(user: User): Promise<void> {
    await this.pool.query(
      'INSERT INTO users (id, name, email) VALUES ($1, $2, $3) ON CONFLICT (id) DO UPDATE SET name = $2, email = $3',
      [user.id, user.name, user.email]
    );
  }
}

Ejemplo: Adaptador de API (Express)

// src/infrastructure/adapters/api/ExpressOrderController.ts
import { Request, Response, Router } from 'express';
import { IOrderService } from '../../../domain/ports/IOrderService';

export class ExpressOrderController {
  private orderService: IOrderService;
  private router: Router;

  constructor(orderService: IOrderService) {
    this.orderService = orderService;
    this.router = Router();
    this.setupRoutes();
  }

  private setupRoutes(): void {
    this.router.post('/', this.createOrder.bind(this));
    this.router.get('/:orderId', this.getOrderById.bind(this));
    this.router.get('/user/:userId', this.getOrdersByUserId.bind(this));
  }

  private async createOrder(req: Request, res: Response): Promise<void> {
    try {
      const { userId, items, totalAmount } = req.body;
      const order = await this.orderService.createOrder(userId, items, totalAmount);
      res.status(201).json(order);
    } catch (error: any) {
      res.status(500).json({ message: error.message });
    }
  }

  private async getOrderById(req: Request, res: Response): Promise<void> {
    try {
      const { orderId } = req.params;
      const order = await this.orderService.getOrderById(orderId);
      if (order) {
        res.json(order);
      } else {
        res.status(404).json({ message: 'Order not found' });
      }
    } catch (error: any) {
      res.status(500).json({ message: error.message });
    }
  }

  private async getOrdersByUserId(req: Request, res: Response): Promise<void> {
    try {
      const { userId } = req.params;
      const orders = await this.orderService.getOrdersByUserId(userId);
      res.json(orders);
    } catch (error: any) {
      res.status(500).json({ message: error.message });
    }
  }

  public getRouter(): Router {
    return this.router;
  }
}

El Núcleo del Dominio

El código del dominio debe ser lo más puro posible, sin dependencias externas.

Ejemplo: Servicio de Dominio para Órdenes

// src/domain/services/OrderService.ts
import { Order, IOrderService } from '../ports/IOrderService';
import { IUserRepository } from '../ports/IUserRepository';
import { v4 as uuidv4 } from 'uuid'; // Asumiendo que usas uuid para IDs

export class OrderService implements IOrderService {
  private userRepository: IUserRepository;

  constructor(userRepository: IUserRepository) {
    this.userRepository = userRepository;
  }

  async createOrder(userId: string, items: string[], totalAmount: number): Promise<Order> {
    // Validación de dominio (ej: ¿existe el usuario?)
    const user = await this.userRepository.findById(userId);
    if (!user) {
      throw new Error('User not found');
    }

    // Lógica de negocio para crear la orden
    const newOrder: Order = {
      id: uuidv4(),
      userId,
      items,
      totalAmount,
      createdAt: new Date(),
    };

    // Si tuvieras un puerto para persistir órdenes, lo llamarías aquí
    // await this.orderRepository.save(newOrder);

    return newOrder;
  }

  async getOrderById(orderId: string): Promise<Order | null> {
    // Lógica de dominio para obtener orden por ID
    // ... (asumiendo que hay un puerto IOrderRepository)
    return null; // Placeholder
  }

  async getOrdersByUserId(userId: string): Promise<Order[]> {
    // Lógica de dominio para obtener órdenes por ID de usuario
    // ... (asumiendo que hay un puerto IOrderRepository)
    return []; // Placeholder
  }
}

Inyección de Dependencias y Orquestación

La clave para conectar los adaptadores con el dominio es la Inyección de Dependencias. El punto de entrada principal de la aplicación (main.ts o index.ts) es el lugar ideal para configurar y “enchufar” los adaptadores concretos a las interfaces del dominio.

Ejemplo: main.ts

// src/main.ts
import express from 'express';
import { PostgreSQLUserRepository } from './infrastructure/adapters/persistence/PostgreSQLUserRepository';
import { OrderService } from './domain/services/OrderService';
import { ExpressOrderController } from './infrastructure/adapters/api/ExpressOrderController';
import dotenv from 'dotenv';

dotenv.config(); // Cargar variables de entorno

const app = express();
app.use(express.json());

// Configuración de la base de datos (ejemplo)
const dbConfig = {
  user: process.env.DB_USER,
  host: process.env.DB_HOST,
  database: process.env.DB_NAME,
  password: process.env.DB_PASSWORD,
  port: parseInt(process.env.DB_PORT || '5432', 10),
};

// 1. Crear instancias de adaptadores de infraestructura
const userRepository = new PostgreSQLUserRepository(dbConfig);

// 2. Crear instancias de servicios de dominio, inyectando dependencias
const orderService = new OrderService(userRepository); // Inyectamos el userRepository

// 3. Crear instancias de adaptadores de entrada (controladores) e inyectar servicios de dominio
const orderController = new ExpressOrderController(orderService); // Inyectamos el orderService

// 4. Registrar las rutas de los adaptadores de entrada en la aplicación principal
app.use('/api/orders', orderController.getRouter());

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Este enfoque garantiza que el OrderService nunca sepa que está utilizando PostgreSQLUserRepository. Podríamos fácilmente reemplazarlo por un MongoUserRepository o incluso un InMemoryUserRepository para pruebas, sin tocar el OrderService.

Beneficios Tangibles para la Mantenibilidad y Escalabilidad

La adopción de la arquitectura hexagonal no es solo una cuestión de diseño elegante; tiene un impacto directo y medible en la salud de tu codebase y en la capacidad de tu producto para crecer.

Mantenibilidad: Reducción del Tiempo de Resolución de Incidencias

Escalabilidad: Preparación para el Crecimiento

Checklist para Implementar la Arquitectura Hexagonal

Adoptar un nuevo patrón arquitectónico puede parecer abrumador. Aquí tienes un checklist para guiarte en la implementación:

Fase de Diseño y Planificación

Fase de Implementación

Fase de Mantenimiento y Evolución

Conclusión: Hacia un Software B2B Más Robusto y Adaptable

La arquitectura hexagonal Node.js, potenciada por TypeScript, no es una moda pasajera, sino un enfoque arquitectónico probado que ofrece beneficios tangibles para agencias y startups B2B. Al desacoplar la lógica de negocio de las preocupaciones de infraestructura, construyes sistemas que son intrínsecamente más fáciles de mantener, probar y evolucionar. Esto se traduce directamente en una reducción de los costos de desarrollo y mantenimiento a largo plazo, una mayor velocidad de innovación y una capacidad superior para adaptarse a los cambios del mercado.

Si estás buscando llevar tus proyectos al siguiente nivel, mejorar la calidad de tu código y asegurar la longevidad de tus aplicaciones, la arquitectura hexagonal es un camino que vale la pena explorar. En Alken, entendemos los desafíos únicos del desarrollo de software B2B y ayudamos a empresas como la tuya a implementar arquitecturas robustas y escalables que impulsen el crecimiento.

¿Listo para transformar tu enfoque de desarrollo y construir software que realmente perdure?

Contáctanos en [email protected] para descubrir cómo podemos ayudarte a implementar la arquitectura hexagonal en tus proyectos Node.js y TypeScript.