Dependency Inversion, ou la flèche qu'on retourneDependency Inversion, or the arrow you flip

Une règle métier qui connaît un détail technique. Trace la flèche.A business rule that knows a technical detail. Trace the arrow.

Un OrderService doit notifier le client après une commande. La version qu'on écrit tous le premier jour marche très bien — et plante un clou qui coûtera cher. La règle métier, stable, qui décrit ce que fait l'entreprise, dépend maintenant d'un détail technique volatil : un client SMTP concret.An OrderService must notify the customer after an order. The version we all write on day one works fine — and drives a nail that'll cost dearly. The stable business rule, describing what the company does, now depends on a volatile technical detail: a concrete SMTP client.

class OrderService:
    def place(order):
        validate(order)
        save(order)
        EmailSender().send(order.customer_email, "Confirmée")  # ← ici

Le couplage direct ne coûte rien à l'écriture — tout au changement.Direct coupling costs nothing to write — everything to change.

Reprenons la flèche OrderService → EmailSender et regardons ce qu'elle déclenche. Le problème n'est pas la qualité d'EmailSender — il peut être impeccable. C'est la direction : le module qui porte la valeur est l'esclave du module qui porte un détail.Take the OrderService → EmailSender arrow again and watch what it triggers. The problem isn't EmailSender's quality — it can be flawless. It's the direction: the module that carries the value is enslaved to the module that carries a detail.

def test_place_saves_order():
    OrderService().place(valid_order)   # ← part en timeout SMTP en CI

On introduit une abstraction, et la flèche se retourne.Introduce an abstraction, and the arrow flips.

L'inversion ne déplace pas le code et ne change pas l'exécution : à l'exécution, OrderService appellera toujours du code d'envoi. Elle change qui connaît le type de qui à la compilation. Le port «Notifier» est exprimé dans le vocabulaire du métier, pas de l'infra — et soudain le métier ne connaît plus personne. L'animation fait pivoter la flèche.The inversion doesn't move code or change execution: at runtime, OrderService still calls sending code. It changes who knows whose type at compile time. The «Notifier» port speaks the business vocabulary, not infra — and suddenly the business knows no one. The animation pivots the arrow.

# port défini DANS le monde métier, à côté d'OrderService
interface Notifier:
    notify(customer, message)

class OrderService(notifier: Notifier):       # ne dépend que de l'idée
    self.notifier.notify(order.customer, "Confirmée")

class EmailNotifier implements Notifier:       # l'infra se conforme
    def notify(customer, message): smtp.send(customer.email, message)

# composition root : le seul endroit qui connaît tout le monde
service = OrderService(notifier = EmailNotifier())

Injecter n'est pas inverser. La fausse abstraction qui fuit le détail.Injecting isn't inverting. The fake abstraction that leaks the detail.

Le bug classique n'est pas d'oublier l'injection — c'est de croire qu'injecter une dépendance suffit à l'inverser. Les deux extraits injectent un Notifier de l'extérieur (c'est de la Dependency Injection). Mais l'un retourne la flèche, l'autre non. Bascule le toggle : regarde le vocabulaire du contrat.The classic bug isn't forgetting injection — it's believing injecting a dependency suffices to invert it. Both snippets inject a Notifier from outside (that's Dependency Injection). But one flips the arrow, the other doesn't. Flip the toggle: watch the contract's vocabulary.

# port métier : neutre, ignore tout de l'infra
interface Notifier:
    notify(customer, message)

class OrderService(notifier: Notifier):
    self.notifier.notify(order.customer, "Confirmée")
# le jour où l'on passe à une API HTTP : on écrit un nouvel adapter.
# OrderService ne bouge pas.

Le quoi appelle le comment, ou les deux pointent vers l'idée.The what calls the how, or both point to the idea.

Quand ne pas inverserWhen not to invert

Le pattern a un loyer : une interface de plus, une couche à lire, un saut au débogueur, une composition root à tenir. On l'évite quand :The pattern has rent: one more interface, a layer to read, a debugger hop, a composition root to maintain. Avoid it when:

• il n'y aura jamais qu'une implémentation et qu'elle ne franchit aucune frontière d'I/O (un calcul pur, un formateur de date). Inverser ici, c'est de la cérémonie : YAGNI.there will only ever be one implementation and it crosses no I/O boundary (a pure calculation, a date formatter). Inverting here is ceremony: YAGNI.
• le détail EST le métier. Un service de paiement dont le cœur est l'intégration Stripe n'a pas à cacher Stripe derrière une abstraction fantôme « au cas où ».the detail IS the business. A payment service whose core is the Stripe integration needn't hide Stripe behind a phantom 'just in case' abstraction.
• l'abstraction n'aurait qu'un seul appelant ET un seul implémenteur pour toujours : une interface 1-pour-1 perpétuelle ajoute un nom sans ajouter de liberté.the abstraction would have one caller AND one implementer forever: a perpetual 1-to-1 interface adds a name without adding freedom.

Le réflexe n'est donc pas « inverse tout ». C'est : « cette dépendance traverse-t-elle une frontière susceptible de changer (I/O, tiers, canal) ? Si oui, je retourne la flèche ; sinon, je laisse le couplage direct et j'économise l'indirection. »So the reflex isn't 'invert everything'. It's: 'does this dependency cross a boundary likely to change (I/O, third party, channel)? If yes, flip the arrow; if not, keep direct coupling and save the indirection.'

Mot de l'éditeurFrom the editor

Dependency Inversion n'est pas un problème de notification. C'est le numéro où l'on cesse de lire le code comme une liste d'instructions et où l'on commence à le lire comme un graphe de flèches. Le débutant demande « est-ce que ça marche ? ». L'architecte demande « dans quel sens pointent les dépendances, et est-ce que le stable dépend du volatil ? ».Dependency Inversion isn't a notification problem. It's the issue where you stop reading code as a list of instructions and start reading it as a graph of arrows. The beginner asks 'does it work?'. The architect asks 'which way do the dependencies point, and does the stable depend on the volatile?'.

La fonctionnalité ne change pas quand on inverse — l'exécution est identique. Ce qui change, c'est qui doit rouvrir quel fichier le jour où le monde bouge. Toute la série découle de là : une architecture, c'est une discipline sur le sens des flèches.Functionality doesn't change when you invert — execution is identical. What changes is who must reopen which file the day the world moves. The whole series flows from this: an architecture is a discipline over the direction of arrows.

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

• Dependency Injection — le mécanisme qui livre l'implémentation à la composition root (constructeur, conteneur). Souvent confondu avec DIP ; c'en est seulement la moitié visible.the mechanism that delivers the implementation to the composition root (constructor, container). Often confused with DIP; it's only the visible half.
• Ports & Adapters (Hexagonal) — le même retournement de flèche, généralisé à toutes les frontières d'I/O : le métier au centre, les adapters au bord. (Vol 1 #2.)the same arrow flip, generalized to all I/O boundaries: the business at the center, adapters at the edge. (Vol 1 #2.)
• Service Locator — l'anti-pattern voisin : au lieu d'injecter, le code va chercher sa dépendance dans un registre global. Il restaure le couplage qu'on venait de casser, en le cachant.the neighboring anti-pattern: instead of injecting, code fetches its dependency from a global registry. It restores the coupling you just broke, by hiding it.

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

# test_inversion.py — la spec EST le harnais : fais-le passer au vert.
# un OrderService qui ne connaît QUE le port Notifier. sans mock lib, sans réseau.

def test_confirme_notifie_via_le_port():
    notifier = FakeNotifier()
    svc = OrderService(notifier)                  # on injecte une doublure
    svc.confirm(Order(customer=alice, total=42))
    assert notifier.calls == [(alice, "Confirmée")]   # le métier a notifié via le port

def test_le_metier_ne_connait_pas_le_canal():
    svc = OrderService(FakeNotifier())
    assert "smtp" not in modules_touched(svc.confirm)  # aucune trace d'infra dans le cœur
    # OrderService n'importe ni SMTP ni HTTP : il ne parle que « Notifier »

def test_changer_de_canal_ne_touche_pas_le_metier():
    mails, sms = [], []
    OrderService(EmailNotifier(send=lambda *m: mails.append(m))).confirm(Order(customer=alice, total=42))  # même métier…
    OrderService(SmsNotifier(send=lambda *m: sms.append(m))).confirm(Order(customer=alice, total=42))      # …autre adapter
    assert mails and sms           # une seule classe OrderService, inchangée, deux canaux

def test_l_adapter_traduit_seulement():
    sent = []
    EmailNotifier(send=lambda to, msg: sent.append((to, msg))).notify(alice, "Confirmée")
    assert sent == [("alice@x.io", "Confirmée")]   # l'adapter mappe client→email, rien d'autre

def test_le_port_parle_metier_pas_smtp():
    # le contrat n'expose que notify(customer, message) — jamais send_smtp/host.
    assert port_methods(Notifier) == {"notify"}    # une fuite d'infra dans le port = un test rouge