Clean Architecture Demo
Loading...
Searching...
No Matches
Introducción

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.

Clean
Architecture

Diagrama C4 de sistema de software

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.

Note
En esta demo no se utiliza un servidor de correo externo pero está diseñada de forma tal que podría agregarse uno.

Task Management System
Software

Diagrama C4 de contenedores

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-.

Task Management
Containers

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.

Diagrama C4 de componentes

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-.

Task Management
Components

Puedes ver claramente como las clases en los contenedores mantienen las referencias del diagrama de contenedores, es decir, "de arriba hacia abajo".

Diagrama C4 de código

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.

Task Management
Components

Implementación de la arquitectura

La arquitectura en este demo está organizada en proyectos de C# independientes, donde cada proyecto corresponde a un círculo:

Note
En la documentación de Microsoft sobre Clean Architecture el círculo central es Application Core e incluye lo que en la documentación original de Clean Architecture son los círculos Entities y Use Cases. A pesar de ser una demo en .NET, usamos la terminología original.
  1. TaskManagement.Domain es una librería de C# en la que se define el dominio de la aplicación: entidades y objetos valor, y eventos. El domino utiliza eventos para informar cuando se crea, se completa, o se asigna una tarea, o cuando cambia su prioridad -ver por ejemplo la propiedad TaskItem.DomainEvents y el método TaskItem.Create en TaskItem-; por esto, esta aplicación también utiliza una arquitectura dirigida por eventos. La capa del dominio tiene la responsabilidad de generar eventos, pero es la capa de aplicación la que tienen la responsabilidad de procesarlos -ver por ejemplo CreateTaskInteractor.ExecuteAsync en CreateTaskInteractor-. El proyecto TaskManagement.Domain no referencia ningún otro proyecto, es el centro de los círculos concéntricos.
  2. TaskManagement.Application es otra librería de C# en la que se definen las funcionalidades de la aplicación -comandos y consultas-, o dicho de otra forma, donde se implementa la lógica de los casos de uso. Esta aplicación usa el patrón CQRS donde los comandos están separados de las consultas -ver por ejemplo la clase CreateTaskInteractor y la clase GetTaskByIdInteractor-. La capa de aplicación define -y utiliza- abstracciones que emplean el patrón de inyección de dependencias -ver por ejemplo las interfaces IEmailService, ITaskRepository, ITaskReadRepository o IUnitOfWork-1. Cada caso de uso tiene además un puerto de entrada, que usa el controlador, y un puerto de salida, que implementa un presenter en la capa de interfaz API -ver por ejemplo las interfaces ICreateTaskInputBoundary y ICreateTaskOutputBoundary-. Las clases concretas que implementan estas abstracciones están definidas en la capa de infraestructura -ver por ejemplo las clases TaskRepository y TaskReadRepository, respectivamente- y también son creadas en tiempo de ejecución en la capa de interfaz API -ver las llamadas a builder.services… .AddScoped<IUnitOfWork>(…), .AddScoped<ITaskReadRepository, TaskReadRepository>(), y .AddScoped<IDomainEventDispatcher, InProcessDomainEventDispatcher>() en Program-. Los eventos creados en la capa del dominio son procesados en la capa de aplicación usando una abstracción -ver la interfaz IDomainEventDispatcher-; y esa abstracción también está implementada en una clase definida en la capa de infraestructura -ver la clase InProcessDomainEventDispatcher-. El proyecto TaskManagement.Application referencia solamente el proyecto TaskManagement.Domain, la dependencia es de un círculo externo al centro de los círculos concéntricos.
  3. TaskManagement.Infrastructure es otra librería de C# en la que se definen cómo se implementa la infraestructura para las abstracciones definidas en la capa de aplicación de -repositorios, despacho de eventos y persistencia-. Las abstracciones ITaskRepository y ITaskReadRepository de la capa de aplicación se implementan con las clases TaskRepository y TaskReadRepository, respectivamente, de esta capa de infraestructura. También en este caso se usa injección de dependencias en la capa de interfaz API -ver por ejemplo en Program las llamadas a builder.services...AddScoped<ITaskRepository, TaskRepository>() y builder.services...AddScoped<ITaskReadRepository, TaskReadRepository>()-. Como ya fue mencionado antes, la abstracción IDomainEventDispatcher definida en la capa de aplicación se implementa con la clase InProcessDomainEventDispatcher de esta capa de infraestructura y la instancia se crea en tiempo de ejecución también con injección de dependencias en la capa de interfaz API en Program -ver builder.services...AddScoped<IDomainEventDispatcher, InProcessDomainEventDispatcher>()-. El proyecto TaskManagement.Infrastructure referencia solamente el proyecto TaskManagement.Application, la dependencia es de un círculo externo a un círculo interno. Esta capa de infraestructura tiene también la configuración de los frameworks de acceso a datos.
  4. TaskManagement.API es una aplicación web en .NET en la que se define la interfaz, en esta demo, una API REST. El proyecto referencia tanto al proyecto TaskManagement.Application como al proyecto TaskManagement.Infrastructure, ambos en círculos internos. Como toda aplicación web en .NET la carpeta contiene los controladores que implementan los endpoint de la API REST -ver por ejemplo TasksController-. También contiene los presenters que convierten el resultado de cada caso de uso en una respuesta HTTP -ver por ejemplo CreateTaskPresenter-. Solo Program, la raíz de composición, usa la capa de infraestructura. El archivo TaskManagement.http tiene ejemplos para invocar la API REST.

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.

Conceptos de Clean Architecture en esta demo

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 Email
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.

Frameworks utilizados

La aplicación utiliza los siguientes frameworks.

Entity Framework Core

Entity Framework Core es el ORM de .NET. En esta demo se usa solo en la capa de infraestructura, para las escrituras.

Dapper

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.

Resumen de clases e interfaces definidos en cada capa

1. Capa del dominio

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í:

public class TaskItem
{
// Método factory para creación segura de entidad
public static Result<TaskItem> Create(string title, string description, ...)
{
// La validación sucede en el dominio
var validation = Validate(title, description, dueDate, createdBy);
if (validation.IsFailure)
return Result.Failure<TaskItem>(validation.Errors);
// La creación de la entidad genera un evento del dominio
var task = new TaskItem { ... };
task.AddDomainEvent(new TaskCreatedEvent(...));
return Result.Success(task);
}
// Métodos de negocio que refuerzan invariantes
public Result Complete()
{
if (Status == TaskStatus.Completed)
return Result.Failure(TaskErrors.AlreadyCompleted);
Status = TaskStatus.Completed;
AddDomainEvent(new TaskCompletedEvent(...));
return Result.Success();
}
}
TaskManagement.Domain.Entities.TaskStatus TaskStatus
Definition TaskRecord.cs:2

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.

public class Result
{
public bool IsSuccess { get; }
public IReadOnlyList<string> Errors { get; }
…
}
// Uso
var result = TaskItem.Create(…);
if (result.IsSuccess)
// Usar result.Value
else
// Manejar result.Errors

2. Capa de aplicación

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.

Diagrama de
secuencia

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.

public sealed class CreateTaskInteractor : ICreateTaskInputBoundary
{
private readonly ITaskRepository _taskRepository;
private readonly IUnitOfWork _unitOfWork;
private readonly IDomainEventDispatcher _eventDispatcher;
private readonly ICreateTaskOutputBoundary _output;
…
public async Task ExecuteAsync(CreateTaskInput input, CancellationToken cancellationToken = default)
{
…
// Traduce la prioridad del DTO a la del dominio
if (!TryToDomainPriority(input.Priority, out var priority))
{
_output.PresentValidationErrors(["Priority is not valid."]);
return;
}
// Delega a la capa del dominio la lógica de negocio
var createResult = TaskItem.Create(
input.Title,
input.Description,
priority,
input.DueDate,
input.CreatedBy);
if (createResult.IsFailure)
{
_output.PresentValidationErrors(createResult.Errors);
return;
}
// Persiste la entidad del dominio
var task = createResult.Value!;
await _taskRepository.AddAsync(task, cancellationToken);
await _unitOfWork.SaveChangesAsync(cancellationToken);
// Despacha los eventos del dominio
await _eventDispatcher.DispatchAsync(task.DomainEvents, cancellationToken);
…
// Entrega el resultado por el puerto de salida
_output.PresentSuccess(new CreateTaskOutput(task.Id));
}
…
}
record CreateTaskOutput(Guid TaskId)
CreateTaskOutput es el DTO de salida del caso de uso de crear una tarea.

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.

3. Capa de infraestructura

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.

// Interfaz definida en capa de aplicación
public interface ITaskRepository
{
Task<TaskItem?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
Task AddAsync(TaskItem task, CancellationToken cancellationToken = default);
…
}
// Implementación en la capa de infraestructura
public sealed class TaskRepository : ITaskRepository
{
// Los detalles de infraestructura como el uso de Entity Framework quedan
// ocultos del dominio y de la aplicación
public async Task<TaskItem?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default)
{
var record = await _dbContext.Tasks
.AsNoTracking()
.FirstOrDefaultAsync(t => t.Id == id, cancellationToken);
// Los objetos del ORM no salen de esta capa
return record?.ToEntity();
}
…
}

4. Capa de interfaz

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í-.

[ApiController]
[Route("api/[controller]")]
public sealed class TasksController : ControllerBase
{
[HttpPost]
[Authorize]
public async Task<IActionResult> Create(
[FromBody] CreateTaskRequest request,
[FromServices] ICreateTaskInputBoundary createTask,
[FromServices] CreateTaskPresenter presenter,
CancellationToken cancellationToken)
{
// Traduce la solicitud HTTP al DTO de entrada del caso de uso
var input = new CreateTaskInput(
request.Title,
request.Description,
request.Priority,
request.DueDate,
GetUserId(User));
// Ejecuta el caso de uso a través de su puerto de entrada
await createTask.ExecuteAsync(input, cancellationToken);
// Devuelve la respuesta HTTP que construyó el presenter
return presenter.Result;
}
…
}

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.

public sealed class CreateTaskPresenter : ICreateTaskOutputBoundary
{
public IActionResult Result { get; private set; } = …
public void PresentSuccess(CreateTaskOutput output)
{
Result = new CreatedAtActionResult(
nameof(TasksController.GetById),
"Tasks",
new { id = output.TaskId },
output.TaskId);
}
public void PresentValidationErrors(IReadOnlyList<string> errors) =>
Result = ErrorResponses.ValidationFailed(errors);
}

En el programa principal en Program se realiza la inyección de dependencias.

// Registra los adaptadores de la capa de infraestructura para los puertos de salida
builder.Services
.AddDbContext<TaskDbContext>(options =>
options.UseSqlite(builder.Configuration.GetConnectionStr("DefaultConnection")))
.AddScoped<IUnitOfWork>(sp => sp.GetRequiredService<TaskDbContext>())
.AddScoped<ITaskRepository, TaskRepository>()
.AddSingleton<Func<DbConnection>>(_ => () => new SqliteConnectiondtos(connectionString))
.AddScoped<ITaskReadRepository, TaskReadRepository>()
.AddScoped<IDomainEventDispatcher, InProcessDomainEventDispatcher>()
.AddScoped<IDomainEventSubscriber<TaskCompletedEvent>, TaskCompletedNotificationHandler>()
.AddScoped<IEmailService, LoggingEmailService>()
// Registra el presenter y el caso de uso
builder.Services
// Crear tarea
.AddScoped<CreateTaskPresenter>()
.AddScoped<ICreateTaskOutputBoundary>(sp => sp.GetRequiredService<CreateTaskPresenter>())
.AddScoped<ICreateTaskInputBoundary, CreateTaskInteractor>()
// Completar tarea
.AddScoped<CompleteTaskPresenter>()
.AddScoped<ICompleteTaskOutputBoundary>(sp => sp.GetRequiredService<CompleteTaskPresenter>())
.AddScoped<ICompleteTaskInputBoundary, CompleteTaskInteractor>()
// Consultar tarea
.AddScoped<GetTaskByIdPresenter>()
.AddScoped<IGetTaskByIdOutputBoundary>(sp => sp.GetRequiredService<GetTaskByIdPresenter>())
.AddScoped<IGetTaskByIdInputBoundary, GetTaskByIdInteractor>()
var builder
Definition Program.cs:60

Cómo navegar el código

  1. Comienza con la capa del dominio TaskManagement.Domain
    • Lee TaskItem para entender el modelo del dominio
    • Lee Result para entender el manejo de errores
    • Lee DomainEvent para entender la arquitectura dirigida por eventos
  2. Muévete a la capa de aplicación TaskManagement.Application
  3. Explora la capa de infraestructura TaskManagement.Infrastructure
  4. Revisa la capa de interfaz API TaskManagement.API

Beneficios de Clean Architecture

Esta demo permite entender los siguientes beneficios de Clean Architecture:

  • Facilidad de testeo: La lógica del dominio sin dependencias externas facilita escribir casos de prueba.
  • Facilidad de mantenimiento: Separación clara de responsabilidades y aspectos.
  • Flexibilidad: Fácil de intercambiar implementaciones -base de datos, servicio de email, etc.-
  • Escalabilidad: Cada capa se puede optimizar de forma independiente.
  • Reutilización: La lógica del dominio se puede reutilizar en diferentes UIs -web, consola, API, etc.-
  • Independencia: La lógica de negocio está aislada de los frameworks.