Clean Architecture et architecture hexagonale : structurer votre application pour la maintenabilité

La Clean Architecture et hexagonale sont deux manières d’organiser le code d’une application autour de son métier. Elles placent les règles métier au centre. Donc, elles repoussent la base de données, le framework et l’interface à l’extérieur. Les dépendances pointent toujours vers le centre. Vous remplacez ainsi une technologie sans réécrire le cœur de l’application. De plus, vous testez le métier sans infrastructure.

Beaucoup d’applications mélangent les règles métier, les requêtes SQL et le code du framework. Ce mélange ralentit chaque évolution. Il rend aussi les tests lents et fragiles. Donc, expliquons les deux architectures avec des exemples en TypeScript. Précisons aussi quand elles valent leur coût. AquilApp, agence de développement web et mobile à Nantes, conçoit chaque logiciel sur mesure avec cette exigence de structure.

Pourquoi l’architecture logicielle est un investissement, pas un coût ? 

L’architecture logicielle est l’organisation d’un système en composants, avec des règles qui encadrent leurs dépendances. Robert C. Martin lui donne un but précis dans Clean Architecture (Pearson, 2017). Elle doit réduire les ressources humaines nécessaires pour construire et maintenir le système.

Le scénario est courant. Un projet démarre vite, car tout tient dans les contrôleurs. Deux ans plus tard : 

• Changer de base de données touche des centaines de fichiers. 
• Ajouter une application mobile à l’application web demande de dupliquer la logique métier.

La phase de conception du cycle de développement logiciel est le moment où ces frontières coûtent le moins chère à poser. Après la mise en production, chacune d’entre elles qui a été oubliée devient un chantier de refonte.

La recherche DORA de Google Cloud relie l’architecture à la performance de livraison. Elle identifie l’architecture comme un prédicteur de la livraison continue. De plus, elle décrit des équipes qui testent à la demande, sans environnement d’intégration partagé, et qui déploient indépendamment des autres équipes.

Pour aller plus loin, consultez aussi notre autre article : CQRS et Event Sourcing.

Quelles sont les couches et la règle de dépendance du Clean Architecture d’Uncle Bob ?

La Clean Architecture est un style d’architecture décrit par Robert C. Martin, surnommé « Uncle Bob ». L’article a été publié le 13 août 2012. Martin la présente comme une synthèse d’architectures antérieures : l’hexagonale, l’architecture en oignon et d’autres. Elle organise le code en quatre cercles concentriques, du centre vers l’extérieur :

1. Entities (entités) : les règles métier les plus générales, ou les objets métier de l’application. Ce sont les éléments les moins susceptibles de changer.
2. Use Cases (cas d’usage) : les règles propres à l’application. Ils orchestrent les échanges de données avec les entités.
3. Interface Adapters (adaptateurs d’interface) : ils convertissent les données entre le format des cas d’usage et celui de la base de données ou du web. Contrôleurs et présentateurs y vivent.
4. Frameworks and Drivers : la base de données, le framework web et les outils. Cette couche contient surtout du code de liaison.

Martin précise que les cercles sont schématiques. Vous pouvez en ajouter. Une seule règle reste obligatoire.

Qu’est-ce que la règle de dépendance ?

La règle de dépendance est la contrainte centrale de la Clean Architecture : les dépendances du code source pointent uniquement vers l’intérieur. Un cercle interne ne mentionne aucun nom déclaré dans un cercle externe. Cela vaut pour les fonctions, les classes et les variables.

Les formats de données suivent la même règle. Une ligne renvoyée par un framework de base de données ne traverse pas la frontière vers un cas d’usage. La donnée franchit la frontière sous la forme la plus pratique pour le cercle interne.

Comment le cœur appelle-t-il l’extérieur sans en dépendre ?

Le cœur utilise l’inversion de dépendance. Le cas d’usage appelle une interface qu’il déclare lui-même. La couche externe implémente cette interface. Le flux d’exécution va vers l’extérieur. Cependant, la dépendance du code va vers l’intérieur. Martin illustre ce mécanisme avec un « Use Case Output Port » que le présentateur implémente.

Quels sont les ports, les adaptateurs et le domaine métier d’une architecture hexagonale ?

L’architecture hexagonale est aussi appelée « ports et adaptateurs ». C’est un style proposé par Alistair Cockburn. Son intention, publiée en 2005, est claire. Une application doit pouvoir être pilotée aussi bien par des utilisateurs que par des programmes, des tests automatisés ou des scripts. Elle doit aussi se développer et se tester sans ses périphériques ni sa base de données.

Le vocabulaire tient en quatre termes :

• Le cœur (l’hexagone) contient la logique métier et les cas d’usage.
• Un port est un point d’échange défini par le cœur, dans le langage du métier.
• Un adaptateur convertit un événement technique en appel de port, ou l’inverse.
• Les ports entrants et sortants distinguent ce qui pilote l’application (API REST, ligne de commande, tests) de ce qu’elle pilote (base de données, messagerie, service de paiement).

Les adaptateurs restent à l’extérieur du cœur. Ce dernier ignore la nature du périphérique d’entrée. Le dessin en hexagone est une convention. Vous définissez autant de ports que nécessaire.

Un exemple concret : le cœur déclare un port sortant CommandeRepository. En production, un adaptateur PostgreSQL l’implémente. En test, un adaptateur en mémoire le remplace. AWS Prescriptive Guidance décrit le même bénéfice : des composants testés sans dépendre des bases de données ni des interfaces, et moins de dépendance à une technologie donnée.

Quels sont les points communs et les différences entre le clean architecture et hexagonale ?

Martin cite lui-même l’architecture hexagonale et l’architecture en oignon de Jeffrey Palermo (juillet 2008). Selon lui, elles se ressemblent beaucoup. Toutes visent la séparation des préoccupations. De plus, toutes prévoient au moins une couche pour les règles métier et une autre pour les interfaces.

Le clean architecture et hexagonale partagent quatre principes :

• Le cœur métier ne dépend d’aucun framework, d’aucune interface ni d’aucune base de données.
• Les règles métier se testent sans interface, sans base et sans serveur web.
• L’inversion de dépendance relie le cœur à l’extérieur.
• Les adaptateurs traduisent les données à la périphérie.

Critère	Architecture hexagonale	Clean Architecture
Auteur et date	Alistair Cockburn, 2005	Robert C. Martin, 2012 (livre en 2017)
Représentation	Un hexagone : intérieur et extérieur	Cercles concentriques
Vocabulaire	Ports et adaptateurs	Entities, Use Cases, Interface Adapters, Frameworks and Drivers
Découpage interne du cœur	Non prescrit	Entités et cas d’usage, extensibles
Règle centrale	Le cœur définit les ports, les adaptateurs restent dehors	Les dépendances du code pointent vers l’intérieur

Sources : A. Cockburn, « Hexagonal architecture » (2005, alistair.cockburn.us) ; R. C. Martin, « The Clean Architecture » (13 août 2012, blog.cleancoder.com) et Clean Architecture (Pearson, 2017).

Notre avis : en pratique, le clean architecture et hexagonale donnent une structure de dossiers très proche. Retenez le vocabulaire que votre équipe maîtrise. Appliquez ensuite sans concession la règle qui compte : le cœur ne dépend de rien d’extérieur. 

Ce choix se prend en même temps que vos méthodes de développement logiciel. En effet, l’architecture doit suivre la façon dont l’équipe conçoit, teste et livre.

Comment mettre en pratique les deux méthodes : exemple concret en TypeScript

TypeScript convient bien à cet exercice. En effet, ses interfaces expriment les ports de façon explicite. Pour comparer les deux langages, consultez notre article TypeScript vs JavaScript. L’exemple traite un cas d’usage simple : créer une commande. Voici l’organisation des dossiers.

src/

  domain/            # entités et règles métier

    commande.ts

  application/       # cas d’usage et ports

    commande-repository.ts

    creer-commande.ts

  infrastructure/    # adaptateurs

    commande-repository-memoire.ts

Étape 1 : l’entité

Elle porte la règle métier et n’importe rien.

// domain/commande.ts

export interface LigneCommande {

  reference: string;

  prixUnitaireEnCentimes: number;

  quantite: number;

}

export class Commande {

  private constructor(

    readonly id: string,

    readonly lignes: readonly LigneCommande[],

  ) {}

  static creer(id: string, lignes: LigneCommande[]): Commande {

    if (lignes.length === 0) {

      throw new Error(« Une commande contient au moins une ligne. »);

    }

    return new Commande(id, lignes);

  }

  totalEnCentimes(): number {

    return this.lignes.reduce(

      (somme, ligne) => somme + ligne.prixUnitaireEnCentimes * ligne.quantite,

      0,

    );

  }

}

Étape 2 : le port et le cas d’usage

Le cœur déclare l’interface dont il a besoin.

// application/commande-repository.ts

import { Commande } from « ../domain/commande »;

export interface CommandeRepository {

  enregistrer(commande: Commande): Promise<void>;

}

// application/creer-commande.ts

import { Commande, LigneCommande } from « ../domain/commande »;

import { CommandeRepository } from « ./commande-repository »;

export class CreerCommande {

  constructor(private readonly commandes: CommandeRepository) {}

  async executer(id: string, lignes: LigneCommande[]): Promise<number> {

    const commande = Commande.creer(id, lignes);

    await this.commandes.enregistrer(commande);

    return commande.totalEnCentimes();

  }

}

Étape 3 : l’adaptateur et le test

L’adaptateur en mémoire permet de tester sans base de données.

// infrastructure/commande-repository-memoire.ts

import { Commande } from « ../domain/commande »;

import { CommandeRepository } from « ../application/commande-repository »;

export class CommandeRepositoryMemoire implements CommandeRepository {

  readonly commandes: Commande[] = [];

  async enregistrer(commande: Commande): Promise<void> {

    this.commandes.push(commande);

  }

}

// creer-commande.test.ts (Vitest)

import { it, expect } from « vitest »;

import { CreerCommande } from « ./application/creer-commande »;

import { CommandeRepositoryMemoire } from « ./infrastructure/commande-repository-memoire »;

it(« enregistre la commande et renvoie son total », async () => {

  const depot = new CommandeRepositoryMemoire();

  const total = await new CreerCommande(depot).executer(« cmd-1 », [

    { reference: « A-100 », prixUnitaireEnCentimes: 2500, quantite: 2 },

  ]);

  expect(total).toBe(5000);

  expect(depot.commandes).toHaveLength(1);

});

Le cas d’usage ignore où la commande est stockée. En production, un adaptateur PostgreSQL implémente CommandeRepository. Le code du domaine et de l’application ne change pas. Pour vérifier la règle de dépendance dans le temps, un outil comme dependency-cruiser fait échouer la construction quand un import pointe vers l’extérieur.

Quand adopter ces architectures et quand est-ce overkill ?

Le clean architecture et hexagonale ont un coût. Elles ajoutent des fichiers, des interfaces et une courbe d’apprentissage pour l’équipe. Jeffrey Palermo l’écrit à propos de l’architecture en oignon : elle ne convient pas aux petits sites. Elle convient aux applications métier à longue durée de vie et au comportement complexe.

Adoptez-les dans ces situations :

• Le métier comporte des règles complexes, appelées à évoluer pendant plusieurs années.
• Plusieurs interfaces (web, mobile, API) partagent la même logique.
• Une brique externe (base de données, fournisseur de paiement) risque de changer.
• L’équipe compte plusieurs développeurs qui doivent travailler sans se bloquer.

Évitez-les pour un prototype jetable, une application de saisie sans règle métier ou un produit dont les hypothèses ne sont pas validées.

Situation	Recommandation AquilApp	Raison
Prototype ou MVP (Minimum Viable Product)	Structure légère, sans couches formelles	Le produit peut changer de direction avant que la structure serve
Application de gestion sans règle complexe	Architecture en couches classique	Peu de logique métier à protéger
Logiciel métier durable, règles complexes	Clean Architecture ou hexagonale	Les règles métier représentent l’actif principal
Même métier exposé sur le web, le mobile et une API	Hexagonale ou Clean Architecture	Un seul cœur, plusieurs adaptateurs entrants

Sources : analyse AquilApp ; réserve de J. Palermo, « The Onion Architecture : part 1 » (juillet 2008).

Faites attention aux pièges. Une équipe crée les dossiers domain et application, mais laisse le domaine importer l’ORM (Object-Relational Mapping, la couche qui relie les objets au SQL). Cette structure ne respecte pas la règle de dépendance. Elle coûte autant qu’une vraie architecture sans en apporter les bénéfices.

Quels sont les gains mesurables en matière de testabilité et de maintenabilité pour ces deux méthodes ? 

Martin conclut son article de 2012 ainsi : séparer le logiciel en couches et respecter la règle de dépendance produit un système intrinsèquement testable. Cockburn part du même besoin, tester l’application sans ses périphériques. Un test de cas d’usage tourne en mémoire. Il n’utilise ni réseau, ni base, ni serveur web.

Attention cependant, aucune étude ne mesure ces deux patterns en particulier. La recherche DORA mesure le couplage lâche en général. Elle relève des équipes qui testent à la demande, déploient indépendamment et modifient leur conception sans autorisation extérieure. Elle suit quatre indicateurs : le délai de mise en production d’un changement, la fréquence de déploiement, le taux d’échec des changements et le délai de rétablissement du service. 

Vous mesurez les gains sur votre propre projet avec quatre relevés :

1. La durée de la suite de tests du cœur métier, comparée à celle des tests qui passent par la base.
2. Le nombre de fichiers modifiés pour une évolution type, comme l’ajout d’un canal de notification.
3. Le temps nécessaire pour remplacer une brique externe sur un périmètre pilote.
4. Les quatre indicateurs DORA, relevés avant et après la refonte.

A lire aussi notre autre article sur le Domain-Driven Design (DDD).

Conclusion

La Clean Architecture et hexagonale reposent sur une même règle : le métier ne dépend pas de la technique. 

Néanmoins, l’hexagonale apporte le vocabulaire des ports et des adaptateurs. De son côté, la Clean Architecture ajoute une organisation en couches. Adoptez-les pour un logiciel métier durable. Évitez-les pour un prototype. 

Pour cadrer la structure de votre application avec nos équipes, découvrez notre expertise de développement logiciel sur mesure ou échangez avec nous sur votre projet.