Onion Architecture vs Clean Architecture en .NET

Onion Architecture y Clean Architecture siguen la misma regla: las dependencias apuntan hacia dentro, hacia el dominio. Se diferencian en cómo organizan el código que la cumple. Onion organiza por capas. Clean organiza por casos de uso.

Esa diferencia es lo bastante pequeña como para que la mayoría de los equipos pudiera adoptar cualquiera de las dos. Se nota en un lugar concreto: en Clean Architecture, una nueva característica es una nueva clase de caso de uso en un proyecto Application, y en Onion es un nuevo método en un servicio existente.

Recurrimos a Clean Architecture cuando la parte difícil son las reglas de negocio, y Onion gana sin discusión cuando la parte difícil es la división en capas y el equipo quiere menos convenciones. En una aplicación pequeña no gana ninguna de las dos: ambas añaden proyectos, indirección y mapeo que puede que el código nunca llegue a necesitar.

¿Qué es la arquitectura Onion?

La arquitectura Onion es un tipo de arquitectura en capas que se puede representar como una serie de círculos concéntricos, parecidos a las capas de una cebolla. Jeffrey Palermo presentó esta arquitectura por primera vez para resolver las carencias del enfoque tradicional de arquitectura en N capas.

Hay varias formas de dividir la arquitectura Onion, pero existen algunas capas comunes:

• Capa de dominio
• Capa de servicios
• Capa de infraestructura
• Capa de presentación

Conceptualmente, se considera que las capas de infraestructura y de presentación están al mismo nivel de la jerarquía.

Veamos la jerarquía:

Cabe destacar que las capas exteriores solo dependen de las capas interiores, y no al revés. A medida que vamos ‘pelando las capas de la cebolla’, dejamos al descubierto las capas interiores.

Onion está estrechamente relacionada con el patrón Hexagonal (Ports and Adapters), pero no es lo mismo. Alistair Cockburn publicó primero la arquitectura Hexagonal, y Onion se basa en ella en lugar de limitarse a cambiarle el nombre.

La arquitectura Hexagonal rodea el núcleo de la aplicación, el “hexágono”, con “puertos” simétricos: las interfaces a través de las cuales la aplicación se comunica con el mundo exterior. Los “adaptadores” encajan en esos puertos y conectan la aplicación con sistemas o frameworks externos. Lo que Hexagonal no hace es ordenar el interior de ese núcleo en capas jerarquizadas, y ese orden es lo que añade Onion. A partir de aquí nos centramos en Onion.

A continuación, veamos el patrón Clean Architecture.

¿Qué es Clean Architecture?

Clean Architecture es un patrón orientado a crear aplicaciones fáciles de mantener, escalar y probar. Al igual que en la arquitectura Onion, lo conseguimos dividiendo el sistema en capas con funciones específicas.

Analicemos las capas:

La capa de dominio, idéntica a la de la arquitectura Onion, representa las reglas de negocio y las entidades fundamentales. No depende de otras capas.

La capa de aplicación, situada justo por fuera de la capa de dominio, actúa como intermediaria y contiene los casos de uso que exponen las reglas de negocio. Solo depende del dominio.

La capa de infraestructura, de nuevo idéntica a la de la arquitectura Onion, implementa servicios externos como bases de datos, almacenamiento de archivos y correo electrónico. Contiene las implementaciones de las interfaces definidas en la capa de dominio.

La capa de presentación, una vez más similar a la de la arquitectura Onion, se encarga de gestionar las interacciones del usuario y de mostrar los datos en la interfaz de usuario.

Un principio clave aquí es que las dependencias fluyen hacia dentro. Esto permite cambiar implementaciones concretas en el futuro sin afectar a otras partes de la aplicación.

¿Qué es Clean Code Architecture?

No existe ningún patrón llamado “clean code architecture”. La expresión mezcla dos ideas distintas del mismo autor: Clean Code, sobre cómo escribir funciones y clases legibles, y Clean Architecture, sobre cómo organizar las dependencias entre proyectos.

Clean Code trata del interior de los métodos y las clases. Clean Architecture trata de qué proyecto puede hacer referencia a cuál. Son independientes: una solución de Clean Architecture de manual puede estar llena de métodos ilegibles, y una aplicación de consola de un solo proyecto puede seguir Clean Code al pie de la letra.

Quien busca la expresión combinada casi siempre quiere Clean Architecture: las entidades en el centro, los casos de uso a su alrededor, los adaptadores y los frameworks en el exterior, y todas las dependencias apuntando hacia dentro.

Si la pregunta real es sobre nombres, longitud de las funciones y comentarios, eso es Clean Code, y ninguno de los diagramas de capas de esta página te va a ayudar con ello.

Clean Architecture vs Onion Architecture: ¿cuál es la diferencia?

La regla de dependencia es idéntica en ambas. Robert C. Martin la formula como “las dependencias del código fuente solo pueden apuntar hacia dentro”, y la publicación de Jeffrey Palermo sobre Onion dice lo mismo: “todo el acoplamiento va hacia el centro”.

La diferencia está en qué rodea el centro y en qué se basan los nombres de las capas. Onion organiza por capas: un núcleo de dominio, luego los servicios y después la infraestructura y la presentación a su alrededor. Clean organiza por casos de uso: las entidades en el centro, una capa de aplicación que da nombre a cada cosa que hace el sistema, luego los adaptadores de interfaz y después los frameworks.

En una solución, eso se ve de inmediato. El núcleo de Clean Architecture tiene un proyecto Application lleno de handlers de casos de uso. El núcleo de Onion, en cambio, suele tener interfaces e implementaciones de servicios agrupadas por entidad.

La consecuencia que conviene recordar es dónde va el comportamiento nuevo. En Clean Architecture, una nueva característica es una nueva clase de caso de uso. En Onion, es un nuevo método en un servicio existente.

Las dos se solapan mucho, y no solo según nuestra interpretación: la guía de arquitectura de .NET de Microsoft presenta Hexagonal, Ports-and-Adapters, Onion y Clean como nombres que ha recibido la misma arquitectura. En la práctica, Clean Architecture es una variante de Onion con capas más explícitas, y ambas se basan en la inversión de dependencias, de modo que las capas exteriores dependen de abstracciones declaradas más hacia dentro.

Primero, destaquemos de qué depende cada proyecto en las dos arquitecturas, empezando por Onion Architecture:

Ahora, veamos las dependencias en Clean Architecture:

Aunque nuestras aplicaciones tienen un número distinto de proyectos, los principios siguen siendo los mismos. Los proyectos de la capa del núcleo solo dependen entre sí (es decir, dentro de la misma capa). Los proyectos de la capa de infraestructura solo dependen de la capa de dominio, mientras que los proyectos de la capa de presentación dependen de todas las demás capas.

Así que, en cuanto a dependencias, no hay diferencia entre los patrones. La capa más externa depende de las capas interiores. Este es el principio fundamental de ambos patrones, y los dos lo consiguen con el principio de inversión de dependencias en C#.

Ninguno de los dos patrones se impone por sí solo. El compilador no pone ninguna objeción a que un proyecto de dominio haga referencia a un driver de base de datos, así que, si la dirección nos importa, deberíamos hacer cumplir estas reglas de capas con pruebas de arquitectura que hagan fallar la compilación cuando una referencia apunte en la dirección equivocada.

Estructura de proyectos de la capa del núcleo en Onion y Clean Architecture

En la arquitectura Onion, la capa del núcleo se organiza en un conjunto de proyectos:

Tenemos las entidades de dominio o de negocio, las excepciones, las interfaces de repositorio y las interfaces e implementaciones de servicios. Además, estos componentes son parte integral de la arquitectura. Fíjate en que todo se organiza en torno a “Pizza” y “Orders”.

Veamos la capa del núcleo en la solución de Clean Architecture:

Así que de nuevo tenemos entidades y, otra vez, interfaces de repositorio. Nada nuevo. Pero fíjate en el proyecto CleanArchitecture.PizzaStore.Application. Contiene los casos de uso concretos que queremos que cumpla la aplicación.

Aquí aparece una de las diferencias clave entre los patrones. El patrón Clean Architecture intenta organizar el código en torno a los casos de uso y se centra de verdad en la lógica de negocio. El énfasis está en definir explícitamente esos casos de uso.

Una vez que existe ese proyecto Application, la siguiente pregunta es qué aspecto tiene un caso de uso dentro de él. Una respuesta habitual es una solicitud y un handler por operación, que es lo que supone organizar la capa de aplicación con CQRS y MediatR.

En otras palabras, mientras que la arquitectura Onion se centra en las capas y en el flujo de dependencias, Clean Architecture se centra en organizar la aplicación en torno a los casos de uso, sin dejar de mantener los mismos principios de dependencia.

Clean Architecture da prioridad a la independencia de las reglas de negocio mediante una disposición en capas concéntricas de entidades, casos de uso y adaptadores, mientras que la arquitectura Onion gira en torno a un modelo de dominio central con capas estructuradas a su alrededor para mantener una separación clara de responsabilidades y facilitar una gestión flexible de las dependencias.

¿Cómo decidir qué patrón usar?

Elige Clean Architecture cuando la parte difícil sean las reglas de negocio, y Onion cuando lo sea la división en capas.

La ceremonia adicional de Clean Architecture (una clase por caso de uso) compensa cuando el dominio es realmente complejo, cuando varios puntos de entrada comparten el mismo comportamiento o cuando el equipo necesita dejar por escrito las reglas del juego en un lugar donde alguien que acaba de incorporarse pueda leerlas.

Onion es la más ligera de las dos. Ofrece la misma dirección de dependencias con menos clases por funcionalidad y menos convenciones, lo que encaja con un equipo experimentado que trabaja sobre un modelo bien conocido en el que la mayoría de las operaciones son lecturas y escrituras normales.

Para una aplicación pequeña, ninguna de las dos. Ambas añaden proyectos, indirección y mapeo a un código que puede que nunca llegue a necesitarlos.

Elijamos la que elijamos, lo que vale la pena defender en una revisión es la dirección de las dependencias. Los nombres de las capas son negociables.

Atribuciones de “Presentada por” consultadas el 13 de septiembre de 2026 en The Onion Architecture: Part 1, de Jeffrey Palermo, y en The Clean Architecture, de Robert C. Martin.

Cuando una sola aplicación crece hasta abarcar varias áreas de negocio en gran medida independientes, la siguiente decisión no es Onion o Clean, sino si conviene dividirla, y el monolito modular es la primera respuesta habitual.

Estructura y flexibilidad

Como con cualquier patrón arquitectónico, a menudo sacrificamos simplicidad. Así que solo conviene usar uno de estos patrones si creemos que la aplicación crecerá con las necesidades y los recursos del negocio. Aun así, entre los dos patrones, si la prioridad es una lógica de negocio compleja, Clean Architecture es la mejor opción. Si la prioridad es una estructura y unas capas claras, Onion podría ser una mejor opción.

Experiencia

Como Clean Architecture se ciñe estrictamente a sus directrices, puede encajar con equipos acostumbrados a ese tipo de reglas. Esta estructura ayuda a que los nuevos desarrolladores se integren con facilidad y reduce las probabilidades de romper los patrones establecidos. Sin embargo, este rigor se paga con flexibilidad. Para equipos experimentados que entienden las capas y saben mantener el foco en ellas, pero prefieren más flexibilidad, la arquitectura Onion puede ser una mejor opción.

Mantenimiento

Clean Architecture facilita mantener separadas las distintas áreas de negocio y ampliarlas exponiendo explícitamente la funcionalidad a través de casos de uso, de forma muy parecida a Vertical Slice Architecture. Por otro lado, la arquitectura Onion ofrece una separación de responsabilidades más clara, lo que significa que es más fácil ampliar la aplicación en su conjunto.

Conclusión

En este artículo, hemos analizado más de cerca los patrones Onion y Clean Architecture. En concreto, hemos examinado cómo aborda cada uno el diseño de software. Aunque son muy parecidos, hemos destacado algunos matices que pueden ayudarnos a decidir cuál elegir al crear nuestra próxima aplicación. Como en cualquier decisión de arquitectura, es importante entender todas las contrapartidas, así como el motivo por el que se aplica el patrón. Esperamos que este artículo te ayude a tomar esa decisión en el futuro.

¡Feliz programación!

Probado con .NET 10.0.10.