Implementación de Hexagonal Architecture en Angular para una mejor estructura

¿Qué es, en una línea? Aislar la lógica de negocio (TypeScript puro) del mundo exterior (Angular, Http, storage), usando puertos (contratos) y adaptadores (implementaciones).

Resumen rápido (lectores con prisa)

Patrón que separa dominio, aplicación e infraestructura para mantener la lógica de negocio independiente del framework. Útil cuando hay lógica cliente significativa y se busca testeo rápido. Implementación con puertos (contratos) y adaptadores (implementaciones concretas).

Hexagonal Architecture con Angular: las capas y el contrato de dependencia

Dominio (core)

Entidades y reglas. Nada de Angular, nada de RxJS. Tipo puro.

Aplicación

Casos de uso y puertos. Orquestan el dominio y definen contratos (interfaces o clases abstractas).

Infraestructura

Adaptadores concretos (HttpClient, NgRx, components). Aquí vive Angular.

Regla de oro: las capas exteriores conocen a las interiores; las interiores no conocen a las exteriores.

Referencia conceptual: Alistair Cockburn — Ports and Adapters (hexagonal)

Ejemplo mínimo y realista

Dominio puro

// domain/user.entity.ts
export class User {
  constructor(public id: string, public email: string, public role: 'admin' | 'user') {}
  isAdmin() { return this.role === 'admin'; }
}
  

Puerto (aplicación)

// application/ports/user.repository.port.ts
export abstract class UserRepositoryPort {
  abstract findById(id: string): Promise;
  abstract save(user: User): Promise;
}
  

Adaptador (infraestructura – Angular)

// infrastructure/adapters/http-user.repository.ts
@Injectable()
export class HttpUserRepository implements UserRepositoryPort {
  constructor(private http: HttpClient) {}
  findById(id: string) { return firstValueFrom(this.http.get(`/api/users/${id}`)); }
  save(user: User) { return firstValueFrom(this.http.post('/api/users', user)); }
}
  

Inyección con Angular (config)

// app.config.ts
providers: [
  { provide: UserRepositoryPort, useClass: HttpUserRepository },
  GetUserUseCase
]
  

Angular DI hace el puente. Más sobre DI en la doc oficial: Angular Dependency Injection

Testing: la ganancia real

Cuando los casos de uso son TypeScript puro, los tests son instantáneos y sin TestBed. No más correr un microclima Angular solo para comprobar una regla de negocio.

it('devuelve usuario por id', async () => {
  const mockRepo = { findById: jest.fn().mockResolvedValue(fakeUser) };
  const useCase = new GetUserUseCase(mockRepo as any);
  expect(await useCase.execute('123')).toEqual(fakeUser);
});
  

Resultado: CI más rápido, menos fragilidad y menos magia negra en los tests.

Estructura recomendada (simple y práctica)

Mantén carpetas por responsabilidad, no por tecnología:

src/
├── domain/
├── application/
│   ├── ports/
│   └── use-cases/
└── infrastructure/
    ├── adapters/
    └── ui/
  

Esto hace que mover o substituir adaptadores (pasar de Http a WebSocket, o de NgRx a Signals) sea una tarea controlada, no una reescritura.

Cuándo aplicarla (criterio técnico)

Aplica Hexagonal Architecture con Angular si:

• Tienes lógica importante en cliente (cálculos, reglas offline, validaciones complejas).
• Quieres tests rápidos y confiables.
• El producto vive años y el equipo crece.
• Necesitas desarrollar en paralelo con mocks estables.

No la apliques si

• Es un CRUD simple que solo pinta el backend.
• La prioridad es lanzar rápido con un equipo pequeño.
• El dominio todavía está cambiando cada sprint (prototipado extremo).

El patrón no te hace bueno; te sirve si resuelves un problema claro. Forzarlo es sobreingeniería.

Puntos de atención y antipatterns

• No conviertas cada función en una interfaz por paranoia. Aplica abstracción donde hay cambio probable.
• Evita traer RxJS al dominio para “beneficiarte” del stream — eso es acoplamiento. Usa adaptadores para transformar observables a promesas o tipos puros.
• No escondas lógica en componentes; los componentes deben orquestar, no contener reglas.

Cierre con acción

Si quieres, en el próximo artículo preparo:

• Un scaffold de proyecto Angular con carpeta hexagonal lista.
• Un checklist de decisiones (qué abstraer, cuándo usar InjectionToken vs clase abstracta).

Apúntate al newsletter de Dominicode para recibirlo y el starter con ejemplos de tests en Jest.

Esto no termina aquí. Si tu código se está volviendo difícil de probar o de migrar, la arquitectura es la palanca—y saber cuándo usarla es criterio.

FAQ