Software Architecture
Explica arquitectura hexagonal mediante puertos de entrada y salida, adapters y un núcleo independiente de protocolos, frameworks y proveedores concretos.
La arquitectura hexagonal separa el núcleo de aplicación de los mecanismos externos mediante puertos definidos desde las necesidades del núcleo y adaptadores que traducen tecnologías, protocolos y modelos concretos.
Ports and Adapters propone que una aplicación pueda ser utilizada y probada sin quedar atada a un canal específico de entrada ni a un mecanismo concreto de salida.
adaptadores de entrada
HTTP · CLI · mensajes · jobs
↓
puertos entrantes
↓
núcleo de aplicación
↓
puertos salientes
↓
adaptadores de salida
DB · APIs · correo · brokerEl “hexágono” no representa seis lados obligatorios. Es una forma de mostrar que existen múltiples puntos de conexión alrededor de un núcleo protegido.
Una aplicación suele comenzar con un único canal, como HTTP, y una base concreta. Si la lógica queda escrita directamente dentro de controllers y modelos ORM:
Hexagonal convierte esas conexiones en adaptadores explícitos.
Un puerto entrante representa una capacidad ofrecida por la aplicación:
interface ConfirmOrderUseCase {
execute(command: ConfirmOrderCommand): Promise<ConfirmOrderResult>;
}Puede ser invocado desde:
El puerto no conoce el transporte. Su contrato expresa intención de aplicación.
El adapter traduce el mundo externo al puerto:
class ConfirmOrderHttpController {
constructor(private readonly confirmOrder: ConfirmOrderUseCase) {}
async handle(request: HttpRequest): Promise<HttpResponse> {
const command = {
orderId: request.params.orderId,
actorId: request.auth.userId,
tenantId: request.auth.tenantId,
requestId: request.headers["idempotency-key"],
};
const result = await this.confirmOrder.execute(command);
return mapConfirmOrderResult(result);
}
}No debería contener invariantes del pedido ni queries directas.
Representan capacidades externas que el núcleo necesita:
interface OrderRepository {
findById(id: OrderId): Promise<Order | null>;
save(order: Order): Promise<void>;
}
interface PaymentGateway {
authorize(input: AuthorizationRequest): Promise<AuthorizationResult>;
}El núcleo define contratos desde su lenguaje. No importa tipos de Prisma o Stripe.
Implementan puertos usando tecnología concreta:
class PostgresOrderRepository implements OrderRepository {
constructor(private readonly db: Database) {}
async findById(id: OrderId): Promise<Order | null> {
const row = await this.db.orders.findOne({ id: id.value });
return row ? mapRowToOrder(row) : null;
}
async save(order: Order): Promise<void> {
await this.db.orders.update(mapOrderToRow(order));
}
}El adapter traduce:
Inician una interacción: controller, CLI, test, cron o message consumer.
Son utilizados por la aplicación: repository, gateway, clock, event publisher.
La distinción ayuda a comprender quién controla el flujo.
El ensamblaje ocurre en el borde:
const repository = new PostgresOrderRepository(db);
const payments = new StripePaymentGateway(stripe);
const useCase = new ConfirmOrder(repository, payments);
const controller = new ConfirmOrderHttpController(useCase);El núcleo no utiliza un service locator para buscar dependencias. Las recibe explícitamente.
DomiSys puede confirmar un pedido desde:
Todos pueden usar el mismo puerto:
HTTP adapter ─┐
Webhook adapter ─┼→ ConfirmOrderUseCase
Job adapter ─────┘Cada adapter traduce identidad y datos. El caso de uso aplica las mismas reglas.
Un puerto saliente no debe copiar el proveedor.
Mal diseño:
interface PaymentGateway {
createPaymentIntent(params: Stripe.PaymentIntentCreateParams): Promise<Stripe.PaymentIntent>;
}Diseño protegido:
interface PaymentGateway {
authorize(input: AuthorizationRequest): Promise<AuthorizationResult>;
}El segundo contrato permite traducir unidades, estados, idempotencia y errores.
Fakes de puertos salientes:
class InMemoryOrderRepository implements OrderRepository {
// implementación controlable para reglas
}Prueba parsing, autenticación, mapeo y códigos.
Prueba contra tecnología real o sandbox.
Verifica que todas las implementaciones respeten la misma semántica.
Hexagonal enfatiza:
Clean Architecture enfatiza:
Pueden aplicarse juntas. No es necesario elegir una etiqueta exclusiva.
Repository<T> permite operaciones que el dominio no necesita y filtra persistencia.
Un wrapper que devuelve tipos externos no protege el núcleo.
Abstraer Math.max o una función estable añade ruido. Crea puertos para fronteras relevantes.
Si una operación usa varias persistencias, el diseño debe establecer coordinación. La arquitectura hexagonal no define automáticamente atomicidad.
Un consumer es adapter de entrada; publicar es un puerto saliente. Deben manejar duplicación, orden y errores según su contrato.
Una aplicación pequeña puede usar funciones y pocos contratos. La idea importante es conservar límites, no cumplir una cantidad de clases.
Arquitectura en capas compara una organización por niveles de abstracción y muestra cuándo las capas aportan separación o solo forwarding.