08 - Glossaire complet

Tous les termes utilises dans cette serie, plus quelques concepts lies que tu croiseras forcement dans la litterature sur l'architecture logicielle.

A

Adaptateur (Adapter)

Une implementation concrète d'un port. C'est le code qui connecte le domaine au monde réel. Un adaptateur entrant recoit des requêtes de l'extérieur (un controller Express, une commande CLI). Un adaptateur sortant communique avec l'extérieur pour le compte du domaine (un repository PostgreSQL, un client Stripe).

typescript// Adaptateur sortant : implemente le port OrderRepositoryPort
class PgOrderRepository implements OrderRepositoryPort {
  async save(order: Order): Promise<void> {
    await db.query('INSERT INTO orders ...', [order.id, order.total]);
  }
}

Voir l'article 04 pour les détails.

Anti-corruption Layer (ACL)

Une couche de traduction entre ton domaine et un système externe dont le modèle de donnees ne correspond pas au tien. Par exemple, si l'API Stripe renvoie un objet PaymentIntent avec 40 champs, l'ACL le transforme en un Payment propre avec 5 champs qui ont du sens dans ton domaine.

Application Service

Synonyme de "use case". C'est la couche qui orchestre les appels au domaine et aux ports sortants pour réaliser une opération métier. Le service applicatif ne contient pas de logique métier, il coordonne.

typescriptclass CreateOrderUseCase {
  constructor(
    private repo: OrderRepositoryPort,
    private payment: PaymentGatewayPort,
  ) {}

  async execute(items: CartItem[]): Promise<Order> {
    const order = Order.create(items); // logique metier dans le domaine
    await this.payment.charge(order.total); // port sortant
    await this.repo.save(order); // port sortant
    return order;
  }
}

C

Clean Architecture

L'architecture proposee par Robert C. Martin (Uncle Bob) en 2012. Tres proche de l'architecture hexagonale, avec des cercles concentriques au lieu d'un hexagone. Le principe est le meme : le domaine au centre, les dépendances pointent vers l'intérieur. La différence est surtout dans le vocabulaire (Entities, Use Cases, Interface Adapters, Frameworks) et la formalisation des couches.

Comparaison dans l'article 07.

Controller

Un adaptateur entrant qui recoit des requêtes HTTP et les traduit en appels aux use cases. Dans une archi hexagonale, le controller ne contient aucune logique métier. Il désérialisé la requête, appelle le use case, et sérialisé la réponse.

typescript// Adaptateur entrant Express
app.post('/orders', async (req, res) => {
  const result = await createOrderUseCase.execute(req.body.items);
  res.json({ orderId: result.id });
});

Couplage

Le degre de dépendance entre deux modules. L'architecture hexagonale cherche a minimiser le couplage entre le domaine et l'infrastructure. Si tu peux changer ta base de donnees sans toucher au domaine, le couplage est faible. Si changer la DB oblige a modifier 30 fichiers, le couplage est fort.

D

Dependency Injection (DI)

Le mecanisme par lequel les adaptateurs sont fournis aux use cases au lieu d'etre créés par eux. Tu passes les dépendances en paramètre du constructeur. Pas besoin de framework DI, un simple new CreateOrderUseCase(pgRepo, stripePayment) dans le main.ts suffit.

Voir l'article 06 pour le cablage complet.

Dependency Inversion Principle (DIP)

Le 5e principe SOLID de Robert C. Martin. Les modules de haut niveau (le domaine) ne doivent pas dépendre des modules de bas niveau (PostgreSQL, Stripe). Les deux doivent dépendre d'abstractions (les ports/interfaces). C'est le principe fondateur de l'architecture hexagonale.

En pratique : le domaine definit OrderRepositoryPort (interface), et l'adaptateur PgOrderRepository implemente cette interface. Le domaine ne connaît pas PostgreSQL.

Domaine (Domain)

Le coeur de l'application. Il contient les entités, les value objects, les regles métier et les invariants. Le domaine n'a aucune dépendance vers l'extérieur : pas d'import Express, Prisma, pg, nodemailer. Il est pur.

Voir l'article 02 et la serie sur les domaines.

Driven (cote sortant)

Le cote de l'hexagone qui est "conduit" par le domaine. Ce sont les ports et adaptateurs sortants : le domaine demande quelque chose (sauvegarder une commande, envoyer un email), et l'adaptateur l'exécuté. Synonyme : "secondary".

Driving (cote entrant)

Le cote de l'hexagone qui "conduit" le domaine. Ce sont les ports et adaptateurs entrants : un utilisateur, un cron job ou une API externe déclenché une action. Synonyme : "primary".

E

Entity

Un objet du domaine avec une identité persistante. Deux entités avec les memes attributs mais des IDs différents sont des objets différents. Exemple : deux commandes avec le meme montant ne sont pas la meme commande.

typescriptclass Order {
  constructor(
    readonly id: string,
    private items: OrderItem[],
    private status: OrderStatus,
  ) {}
}

H

Hexagone

La forme geometrique utilisee par Alistair Cockburn pour representer l'architecture. Pourquoi un hexagone et pas un cercle ? Parce que les 6 cotes permettent de dessiner plusieurs ports de chaque cote (entrants a gauche, sortants a droite). En pratique, le nombre de cotes n'a pas d'importance, c'est le concept de centre (domaine) et de bord (ports/adaptateurs) qui compte.

I

Inbound (entrant)

Synonyme de "driving". Les ports et adaptateurs entrants sont ceux par lesquels le monde extérieur interagit avec le domaine : HTTP controllers, CLI commands, event handlers, cron jobs.

Interface

En TypeScript, un contrat que les adaptateurs doivent respecter. C'est la définition d'un port. L'interface decrit les méthodes disponibles sans les implementer.

typescriptinterface OrderRepositoryPort {
  save(order: Order): Promise<void>;
  findById(id: string): Promise<Order | null>;
}

Invariant

Une condition qui doit toujours etre vraie pour une entité dans un état donne. Exemple : "une commande PAID doit avoir un montant > 0". Les invariants vivent dans le domaine, pas dans la base de donnees. Voir la serie sur les invariants.

M

Modular Monolith

Un monolithe structure en modules independants, chacun avec sa propre architecture hexagonale. Les modules communiquent via des interfaces, pas via des appels directs aux classes internes. C'est souvent le bon compromis entre un monolithe spaghetti et des microservices.

O

Onion Architecture

Une variante de l'architecture hexagonale proposee par Jeffrey Palermo. Les couches sont representees en anneaux concentriques : Domain Model au centre, Domain Services, Application Services, Infrastructure a l'extérieur. Les memes principes que l'hexa, une representation visuelle différente.

Outbound (sortant)

Synonyme de "driven". Les ports et adaptateurs sortants sont ceux par lesquels le domaine interagit avec le monde extérieur : bases de donnees, APIs tierces, systèmes de fichiers, envoi d'emails.

P

Port

Une interface TypeScript qui definit comment le domaine communique avec l'extérieur. Un port entrant definit ce que le monde peut demander au domaine (les use cases). Un port sortant definit ce que le domaine a besoin de l'extérieur (persistence, paiement, notification).

Voir l'article 03.

Ports and Adapters

Le nom officiel de l'architecture hexagonale, donne par Alistair Cockburn. "Ports" pour les interfaces, "Adapters" pour les implementations. Le terme "hexagonal" vient de la representation graphique.

R

Repository

Un pattern pour l'acces aux donnees. Un repository ressemble a une collection en mémoire : save, findById, findAll, delete. C'est le port sortant le plus courant. L'adaptateur implemente le repository avec la technologie de son choix (SQL, MongoDB, fichier, mémoire).

S

Side Effect

Un effet de bord declanche par une opération du domaine. Envoyer un email apres une commande, mettre à jour un cache, publier un événement. Les side effects passent par les ports sortants, jamais directement depuis le domaine.

SOLID

Les 5 principes de conception orientee objet de Robert C. Martin. L'architecture hexagonale applique surtout le D (Dependency Inversion) et le I (Interface Segregation). S = Single Responsibility, O = Open/Closed, L = Liskov Substitution, I = Interface Segregation, D = Dependency Inversion.

U

Use Case

Une opération métier que le système sait réaliser. "Creer une commande", "Annuler un abonnement", "Generer un rapport". Un use case orchestre le domaine et les ports sortants. C'est le point d'entree pour les adaptateurs entrants. Synonyme : Application Service.

V

Value Object

Un objet du domaine défini par ses attributs, pas par une identité. Deux value objects avec les memes attributs sont identiques. Exemples : une adresse, un montant en euros, une periode de dates. Immutable par nature.

typescriptclass Money {
  constructor(readonly amount: number, readonly currency: string) {}
  equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}

Vertical Slice Architecture

Une alternative a l'architecture hexagonale proposee par Jimmy Bogard. Au lieu de découper par couche (domain, ports, adapters), on decoupe par fonctionnalité (chaque feature contient tout : controller, logique, acces DB). Ca réduit le couplage horizontal mais augmente la duplication. Bonne approche pour les CRUD simples, moins adaptee quand la logique métier est complexe.

Sources

Retrouve d'autres articles techniques sur paltemps.fr.

Article précédent : 07 - Quand utiliser l'hexa

Début de la serie : 00 - Introduction