Ports & Adapters, ou la frontière qu'on dessinePorts & Adapters, or the boundary you draw

Des « couches » bien empilées — et toutes les flèches pointent vers la base.Neatly stacked "layers" — and every arrow points to the database.

Au numéro précédent, on a retourné une flèche. Une vraie application en a des dizaines : base, paiement, mail, file de messages, horloge. On dessine alors des « couches » — Controller, Service, Repository, DB — et on se sent propre. Mais empiler n'est pas isoler : la couche métier importe encore l'ORM et Stripe. Le cœur, transitivement, connaît Postgres.Last issue we flipped one arrow. A real application has dozens: database, payment, mail, message queue, clock. So we draw 'layers' — Controller, Service, Repository, DB — and feel tidy. But stacking isn't isolating: the business layer still imports the ORM and Stripe. The core, transitively, knows Postgres.

# « couche domaine » — censée être le cœur stable
from sqlalchemy import Session     # ← déjà de l'infra
import stripe                      # ← déjà de l'infra

class BookingService:
    def confirm(id, db: Session):
        b = db.query(Booking).get(id)        # SQL ici
        stripe.Charge.create(amount=b.total) # Stripe ici
        db.commit()

Un seul point d'entrée câblé en dur, et l'application ne sait faire qu'une chose.One hardwired entry point, and the application can only do one thing.

Le couplage du #1 était local : une règle, un détail. Ici la douleur est systémique. Le métier vit au milieu d'un empilement, donc il hérite de tout ce qui est en dessous — et il se moule sur ce qui est au-dessus. Le jour où le même cas d'usage doit être déclenché autrement, ou testé sans le monde réel, on découvre qu'il n'a jamais été indépendant.The #1 coupling was local: one rule, one detail. Here the pain is systemic. The business lives in the middle of a stack, so it inherits everything below — and it molds to whatever sits above. The day the same use case must be triggered differently, or tested without the real world, you discover it was never independent.

def test_confirm_charges_customer():
    BookingService.confirm(id, db)   # ← exige Postgres + Stripe live
    # rien ici n'est métier : tout est plomberie

L'empilement se replie : le métier au centre, l'infra aux bords.The stack folds: the business at the center, infra at the edges.

Ports & Adapters, c'est le retournement du #1 appliqué à toutes les frontières d'I/O d'un coup. On cesse d'empiler et on dessine une frontière fermée autour du domaine. Ce qui la traverse passe par un port — un contrat que le cœur possède. Côté pilote (gauche), des adapters appellent le cœur ; côté piloté (droite), des adapters l'implémentent. Dans les deux cas, la dépendance pointe vers le centre. L'animation replie les couches en hexagone.Ports & Adapters is the #1 flip applied to every I/O boundary at once. Stop stacking and draw a closed boundary around the domain. What crosses it goes through a port — a contract the core owns. On the driving side (left), adapters call the core; on the driven side (right), adapters implement it. Either way, the dependency points to the center. The animation folds the layers into a hexagon.

# --- le cœur : aucun import d'infra ---
interface BookingStore:           # port piloté (le cœur appelle)
    get(id) -> Booking
    save(b: Booking)
interface PaymentPort:            # port piloté
    charge(customer, amount)
▸ à toiyour turn — le cas d'usage — de quoi dépend-il, des ports ou de l'infra concrète ?the use case — what does it depend on, ports or concrete infra? · cliquer pour révélerclick to reveal    def run(id):
        b = store.get(id); pay.charge(b.customer, b.total); store.save(b)

# --- les bords : ils dépendent du cœur, pas l'inverse ---▸ à toiyour turn — les bords — qui se conforme à quoi ? l'infra implémente…the edges — what conforms to what? infra implements… · cliquer pour révélerclick to reveal
# composition root : le seul endroit qui connaît tout le monde▸ à toiyour turn — le seul endroit qui connaît tout le monde — comment câble-t-on les adapters ?the only place that knows everyone — how do you wire the adapters? · cliquer pour révélerclick to reveal

Dessiner l'hexagone ne suffit pas. Le port qui fuit, l'adapter qui décide.Drawing the hexagon isn't enough. The port that leaks, the adapter that decides.

On a vu le piège du #1 : injecter sans inverser. À l'échelle du système, il prend deux formes jumelles. Le port fuit un type d'infra (l'ORM, le format HTTP) — la flèche ressort du cœur. Ou bien une décision métier migre dans l'adapter — le cœur se vide. Dans les deux cas, l'hexagone est dessiné mais creux. Bascule le toggle : suis le type que le contrat laisse passer, et cherche le if.We saw #1's trap: injecting without inverting. At system scale it takes two twin forms. The port leaks an infra type (the ORM, the HTTP shape) — the arrow escapes the core. Or a business decision migrates into the adapter — the core hollows out. Either way the hexagon is drawn but empty. Flip the toggle: follow the type the contract lets through, and hunt the if.

# le port parle le vocabulaire du domaine, point.
interface BookingStore:
    get(id: BookingId) -> Booking      # type métier
    save(booking: Booking)

# l'adapter TRADUIT — il ne décide jamais.
class PostgresStore implements BookingStore:
    def get(id):
        row = db.query(Booking).get(id)
        return to_domain(row)          # SQL → métier, ici seulement

Le métier au milieu d'un empilement, ou au centre d'une frontière.The business in the middle of a stack, or at the center of a boundary.

Trois noms, une idéeThree names, one idea

Hexagonal (Cockburn), Onion (Palermo), Clean (Martin) décrivent la même topologie : le métier au centre, l'infra aux bords, les dépendances qui pointent vers l'intérieur. Hexagonal insiste sur la symétrie pilote/piloté ; Onion sur les anneaux concentriques ; Clean sur la « règle de dépendance » (rien de l'intérieur ne connaît l'extérieur). Choisis le vocabulaire que ton équipe lira le mieux — ne collectionne pas les trois.Hexagonal (Cockburn), Onion (Palermo), Clean (Martin) describe the same topology: business at the center, infra at the edges, dependencies pointing inward. Hexagonal stresses the driving/driven symmetry; Onion the concentric rings; Clean the 'dependency rule' (nothing inside knows the outside). Pick the vocabulary your team reads best — don't collect all three.

Quand ne pas tracer la frontièreWhen not to draw the boundary

L'hexagone a un loyer plus lourd que le simple DIP : des ports des deux côtés, une couche de traduction, une composition root à tenir, un domaine qui doit exister pour valoir d'être protégé. On l'évite quand :The hexagon's rent is heavier than plain DIP: ports on both sides, a translation layer, a composition root to maintain, a domain that must exist to be worth protecting. Avoid it when:

• le « domaine » n'est que du CRUD : si confirmer une réservation ne fait que copier des champs en base, le cœur est vide et l'hexagone n'entoure que du translateur. Laisse le framework piloter.the 'domain' is just CRUD: if confirming a booking only copies fields to a table, the core is empty and the hexagon wraps nothing but a translator. Let the framework drive.
• le service EST l'intégration : un connecteur dont la raison d'être est de parler à Stripe n'a pas de métier à isoler de Stripe. Le détail est le produit.the service IS the integration: a connector whose whole purpose is to speak to Stripe has no business to isolate from Stripe. The detail is the product.
• le prototype doit prouver une idée avant la prochaine démo : la frontière se trace quand le métier se stabilise, pas avant. C'est le YAGNI du Vol 0 #3 — on attend le point où le coût du changement dépasse le coût de l'indirection.the prototype must prove an idea before the next demo: the boundary gets drawn when the business stabilizes, not before. It's Vol 0 #3's YAGNI — wait for the point where the cost of change exceeds the cost of indirection.

Le réflexe n'est donc pas « hexagone partout ». C'est : « ai-je un métier qui survivra à son infra, et plusieurs frontières d'I/O qui changeront indépendamment ? Si oui, je trace la frontière ; sinon, je laisse les couches et j'économise la cérémonie. »So the reflex isn't 'hexagon everywhere'. It's: 'do I have a business that will outlive its infra, and several I/O boundaries that will change independently? If yes, draw the boundary; if not, keep the layers and save the ceremony.'

Mot de l'éditeurFrom the editor

Ports & Adapters n'invente rien que le #1 n'ait montré : c'est Dependency Inversion qu'on arrête de faire à la main et qu'on inscrit dans la forme du système. Le débutant range son code en couches parce que c'est l'ordre d'exécution. L'architecte le range autour d'une frontière parce que c'est l'ordre des dépendances — et les deux ordres ne coïncident presque jamais.Ports & Adapters invents nothing #1 didn't show: it's Dependency Inversion you stop doing by hand and inscribe into the system's shape. The beginner arranges code in layers because that's execution order. The architect arranges it around a boundary because that's dependency order — and the two almost never coincide.

La fonctionnalité est identique dans les deux topologies — mêmes requêtes, mêmes octets sur le réseau. Ce qui change, c'est ce qu'on peut tester sans le monde réel, et ce qui reste immobile quand le monde réel bouge. Le couplage était la racine ; on a appris à le casser et à l'inverser. Reste à organiser ce qui vit à l'intérieur de la frontière — c'est le prochain volume.Functionality is identical in both topologies — same queries, same bytes on the wire. What changes is what you can test without the real world, and what stays still when the real world moves. Coupling was the root; we learned to break it and flip it. What remains is organizing what lives inside the boundary — that's the next volume.

Les voisins que ce numéro débloqueThe neighbors this issue unlocks

• Onion · Clean Architecture — les deux autres noms de la même topologie ; mêmes dépendances vers l'intérieur, accent différent (anneaux concentriques, règle de dépendance).the same topology's other two names; same inward dependencies, different emphasis (concentric rings, the dependency rule).
• Repository — le cas particulier le plus courant d'un port piloté : un contrat de persistance possédé par le domaine, dont l'adapter SQL ou en mémoire se conforme.the most common special case of a driven port: a persistence contract owned by the domain, with a SQL or in-memory adapter conforming to it.
• Anti-Corruption Layer — l'adapter qui ne traduit pas seulement les types mais protège le domaine d'un modèle externe hostile. On y revient quand on parlera des frontières entre contextes.the adapter that doesn't just translate types but shields the domain from a hostile external model. More when we cover boundaries between contexts.

Le kata — écris-le, ne le relis pasThe kata — write it, don't reread it

# test_hexagon.py — la spec EST le harnais : fais-le passer au vert.
# un cas d'usage qui ne connaît QUE ses ports. doublures en mémoire, zéro réseau.

def test_confirme_via_les_ports():
    store = InMemoryStore({7: Booking(id=7, customer=alice, total=100)})
    pay = FakePayment()
    ConfirmBooking(store, pay).run(7)
    assert pay.charged == [(alice, 100)]           # le cœur a facturé via le port

def test_le_coeur_ignore_l_infra():
    uc = ConfirmBooking(InMemoryStore({}), FakePayment())
    assert "sqlalchemy" not in modules_touched(uc.run)   # aucun import d'infra dans le cas d'usage

def test_changer_d_adapter_ne_touche_pas_le_coeur():
    pay_a, pay_b = FakePayment(), FakePayment()
    ConfirmBooking(InMemoryStore(seed), pay_a).run(7)
    ConfirmBooking(PostgresStore(fake_conn(row_7)), pay_b).run(7)   # même cœur, autre bord
    assert pay_a.charged == pay_b.charged          # même comportement, use case non rouvert

def test_l_adapter_traduit_ne_decide_pas():
    booking = PostgresStore(fake_conn(row_7)).get(7)
    assert isinstance(booking, Booking)            # SQL → métier, et aucune règle ici
    # l'adapter mappe Row→Booking ; « faut-il facturer ? » n'est PAS son affaire

def test_le_port_ne_nomme_que_du_metier():
    # la signature n'expose que Booking, BookingId — jamais Row ni Query.
    assert port_types(BookingStore) <= {Booking, BookingId}   # une fuite d'infra = un test rouge