|
Clean Architecture Demo
|
A continuación describimos la arquitectura de esta demo de Clean Architecture utilizando modelos C4.
Recuerda que en Clean Architecture el código se organiza en círculos concéntricos, donde cada círculo representa diferentes áreas del software. Los elementos de código de un círculo no pueden tener referencias a elementos en un círculo exterior, o dicho de otra forma, las dependencias pueden ir sólo de afuera hacia adentro.

El primer diagrama C4 es el del sistema de software. Muestra los sistemas adyacentes que en este caso son el Usuario que gestiona las tareas y un Email Service que envía correos electrónicos para notificar cambios en las tareas.
El segundo diagrama C4 es el de contenedores. Muestra la aplicación ASP .NET Core que expone una API REST TaskManagement.API y las librerías TaskManagement.Domain, TaskManagement.Application y TaskManagement.Infrastructure que implementan las capas del dominio, aplicación e infraestructura, respectivamente, de acuerdo a los círculos de Clean Architecture mostrados más arriba. También se muestra la base de datos utilizada por la capa de infraestructura para almacenamiento de datos.
Traduciendo la terminología C4 a .NET, los contenedores son los ensamblados que contienen el código de las librería -cada ensamblado se genera a partir de un proyecto .csproj con el mismo nombre; las propiedades de la librería se especifican en ese proyecto-.
Puedes ver claramente en el diagrama que las dependencias van "de arriba hacia abajo", lo que equivale a "afuera hacia adentro" cuando las capas se muestran en círculos.
El siguiente diagrama C4 es el de componentes. Muestra las funcionalidades de la aplicación encapsuladas detrás de interfaces -tipos- bien definidos.
Traduciendo la terminología de C4 a .NET, los componentes son las clases -las clases definen tipos-.
Puedes ver claramente como las clases en los contenedores mantienen las referencias del diagrama de contenedores, es decir, "de arriba hacia abajo".
El último diagrama C4 es el de código. Muestra cómo los componentes son implementados en código.
En este caso usamos un diagrama de clases -parcial- mostrando algunas de las clases involucradas en la creación de una tarea.
La arquitectura en este demo está organizada en proyectos de C# independientes, donde cada proyecto corresponde a un círculo:
1 Algunos autores definen las abstracciones relacionadas con el dominio en la capa del dominio, aunque no sean utilizadas en esa capa. Siguiendo esos autores, interfaces como ITaskRepository se definirían en la capa de dominio. En esta demo, interfaces como esa son definidas en la capa de aplicación, porque es allí donde se usan.
La siguiente tabla muestra dónde está cada concepto, con el caso de uso de crear una tarea como ejemplo.
| Concepto | Círculo | Elemento en esta demo |
|---|---|---|
| Entidad | Entidades | TaskItem |
| Objeto valor | Entidades | |
| Evento del dominio | Entidades | TaskCreatedEvent, TaskCompletedEvent |
| Interactor | Casos de uso | CreateTaskInteractor |
| DTO de entrada y de salida | Casos de uso | CreateTaskInput, CreateTaskOutput |
| Puerto de entrada -*input boundary*- | Casos de uso | ICreateTaskInputBoundary |
| Puerto de salida -*output boundary*- | Casos de uso | ICreateTaskOutputBoundary |
| Puerto de salida -repositorios y servicios externos- | Casos de uso | ITaskRepository, IUnitOfWork, IEmailService |
| Adaptador conductor -*controller*- | Adaptadores de interfaz | TasksController |
| Presenter | Adaptadores de interfaz | CreateTaskPresenter |
| View model | Adaptadores de interfaz | TaskViewModel |
| Adaptador conducido -*gateway*- | Adaptadores de interfaz | TaskRepository, LoggingEmailService |
| Objeto del ORM | Frameworks & Drivers | TaskRecord |
| Configuración de la inyección de dependencias | Frameworks & Drivers | Program.cs |
Los cuatro proyectos no coinciden exactamente con los cuatro círculos: TaskManagement.API y TaskManagement.Infrastructure contienen tanto adaptadores de interfaz como código que depende de los frameworks.
La regla de dependencias se verifica con pruebas de arquitectura en ArchitectureTests.cs, que se ejecutan en el pipeline de CI. Las reglas de negocio y los casos de uso se prueban sin base de datos ni servidor web en TaskManagement.Domain.UnitTests y TaskManagement.Application.UnitTests, respectivamente. Hay un proyecto de pruebas por capa, y las pruebas de integración de la API y las de arquitectura están en proyectos propios.
La aplicación utiliza los siguientes frameworks.
Entity Framework Core es el ORM de .NET. En esta demo se usa solo en la capa de infraestructura, para las escrituras.
Dapper es una librería de mapeo objeto-relacional -ORM- de código abierto para aplicaciones .NET. Permite acceder de forma rápida y sencilla a los datos de las bases de datos sin necesidad de escribir código complejo.
La capa del dominio está definida aquí.
| Componente | Archivos | Propósito |
|---|---|---|
| Entidades | Entities/TaskItem.cs, Entities/TaskStatus.cs, Entities/TaskPriority.cs | Clases de modelo de negocio representando conceptos del dominio |
| Objetos valor | ValueObjects/Email.cs, Common/ValueObject.cs | Objetos inmutables representando valores del dominio |
| Eventos del dominio | Events/DomainEvent.cs | Eventos representando ocurrencias importantes del dominio |
| Interfaces | Ver nota 1 | Ver nota 1 |
| Tipos compartidos | Common/Result.cs, Common/TaskErrors.cs | Tipos comunes compartidos internamente en el dominio |
Principio clave: La capa del dominio nunca depende de las capas de aplicación o infraestructura y contiene solo datos y reglas del negocio.
La entidad TaskItem es un aggregate root que define y gestiona sus propios datos y reglas del negocio. Está definida así:
La capa del dominio utiliza el patrón Result para el resultado de las operaciones. La clase Result representa tanto resultados exitosos -en cuyo caso incluye también el valor del resultado- como errores -en cuyo caso incluye la lista de errores-. Esto permite que un método pueda retornar tanto un resultado como un error.
La capa de aplicación está definida aquí.
| Componente | Archivos | Propósito |
|---|---|---|
| Comandos | Commands/CreateTaskInteractor.cs, Commands/CompleteTaskInteractor.cs | Interactors de casos de uso que cambian estado (CQRS) |
| Consultas | Queries/GetTaskByIdInteractor.cs | Interactors de casos de uso de lecturas de datos (CQRS) |
| Puertos de entrada y salida | Commands/ICreateTaskInputBoundary.cs, Commands/ICreateTaskOutputBoundary.cs, etc. | Contratos de cada caso de uso con los controladores y los presenters |
| DTO | Commands/CreateTaskInput.cs, Commands/CreateTaskOutput.cs, Queries/TaskDto.cs, etc. | Objetos de transferencia de datos para entrada/salida |
| Puertos | Ports/IUnitOfWork.cs, Ports/ITaskRepository.cs, Ports/ITaskReadRepository.cs, Ports/IEmailService.cs, Ports/IDomainEventDispatcher.cs | Abstracciones para servicios de infraestructura y despacho de eventos |
| Manejadores de eventos | Events/IDomainEventSubscriber.cs, Events/TaskCompletedNotificationHandler.cs | Reacciones de la aplicación a los eventos del dominio |
| Compartido | Shared/PagedResult.cs, Shared/TaskPriorityLevel.cs | DTO y tipos comunes |
Principio clave: La capa de aplicación implementa casos de uso de negocio pero delega la lógica de negocio a la capa del dominio. Básicamente es un orquestador de objetos del dominio, sin lógica del negocio.
El siguiente diagrama muestra una versión simplificada de un comando de la capa de aplicación y su interacción con la capa del dominio.
La clase CreateTaskInteractor implementa el caso de uso. El resultado no se devuelve al controlador: sale por el puerto de salida ICreateTaskOutputBoundary, de modo que el caso de uso no conoce a quién le entrega el resultado ni en qué formato se muestra.
En ese método, las variables _taskRepository, _unitOfWork y _eventDispatcher -de tipos definidos en esta capa de aplicación- son asignadas mediante inyección de dependencias con clases implementadas en la capa de infraestructura. La variable _output es asignada con un presenter de la capa de interfaz.
La capa de infraestructura está definida aquí.
| Componente | Archivos | Propósito |
|---|---|---|
| DbContext | Persistence/TaskDbContext.cs | Contexto de base de datos de Entity Framework |
| Repositorios | Persistence/Repositories/TaskRepository.cs, TaskReadRepository.cs | Implementaciones de acceso a datos con Entity Framework y Dapper respectivamente |
| Configuraciones | Persistence/Configuration/TaskConfiguration.cs | Configuraciones de Entity Framework |
| Objetos del ORM | Persistence/Records/TaskRecord.cs | Representación de una fila para Entity Framework; no sale de esta capa |
| Servicios externos | Email/LoggingEmailService.cs | Implementación de IEmailService; en esta demo solo registra el envío en el log |
| Despacho de eventos | EventDispatching/InProcessDomainEventDispatcher.cs | Entrega los eventos del dominio a sus manejadores, en el mismo proceso |
Principio clave: La capa de infraestructura implementa interfaces definidas en la capa de aplicación usando inyección de dependencias.
Esta capa implementa el patrón Repository. La interfaz ITaskRepository definida en la capa de aplicación es implementada por la clase TaskRepository definida en esta capa de infraestructura.
En esta demo la interfaz es una API web. La capa de interfaz está definida aquí.
| Componente | Archivos | Propósito |
|---|---|---|
| Controladores | Controllers/TasksController.cs | Endpoints HTTP |
| Presenters | Presenters/CreateTaskPresenter.cs, Presenters/CompleteTaskPresenter.cs, Presenters/GetTaskByIdPresenter.cs | Convierten el resultado de un caso de uso en una respuesta HTTP |
| View models | ViewModels/TaskViewModel.cs | Datos tal como se muestran en la respuesta HTTP |
| Middleware | Middleware/ExceptionHandlingMiddleware.cs | Respuesta para fallas inesperadas |
| Solicitudes | Requests/CreateTaskRequest.cs | DTO de entrada para solicitudes HTTP |
| Inicio | Program.cs | Raíz de composición de inyección de dependencias |
Principio clave: La capa de UI traduce HTTP a los DTO de entrada de los casos de uso, y sus resultados a respuestas HTTP. No tiene lógica de negocio y delega todo a la capa de aplicación.
A continuación un fragmento de la clase TasksController con la implementación del POST de HTTP para crear una tarea -hay ejemplos para probar todos los endpoints aquí-.
El presenter implementa el puerto de salida del caso de uso. Decide los códigos de estado y el formato de la respuesta. Hay una instancia por solicitud: el caso de uso escribe en el mismo objeto que lee el controlador.
En el programa principal en Program se realiza la inyección de dependencias.
Esta demo permite entender los siguientes beneficios de Clean Architecture: