Anti-Corruption Layer (ACL)

Comment protéger votre domaine de la contamination par des systèmes externes, legacy ou tiers grâce à une couche de traduction qui isole les modèles incompatibles.

Quel problème résout-il

Lorsque votre système doit s’intégrer à un système externe (legacy, tiers ou d’une autre équipe), les modèles de données et les concepts métier sont souvent très différents. Sans protection, le modèle du système externe contamine votre domaine :

Sin ACL:
  Tu Servicio de Pedidos
  ┌──────────────────────────────────┐
  │ createOrder(legacyCustomerCode,  │
  │   legacyProductSKU,              │  ← Conceptos del sistema legacy
  │   legacyPriceFormat,             │     infiltrados en tu dominio
  │   legacyTaxCalculation)          │
  └──────────────────────────────────┘
         │
         ▼
  Sistema Legacy ERP (modelo incompatible)

Les problèmes concrets sont les suivants :

Contamination du modèle : votre domaine adopte les noms, structures et règles du système externe
Couplage fort : les changements dans le système externe imposent des changements dans votre domaine
Complexité croissante : votre code mélange logique métier et logique de traduction
Tests difficiles : vous ne pouvez pas tester votre domaine sans simuler le système externe

Comment ça fonctionne

L’Anti-Corruption Layer est une couche de traduction qui s’intercale entre votre système et le système externe. Elle traduit concepts, formats et protocoles dans les deux directions, tout en préservant la propreté de votre domaine.

Con ACL:
  Tu Servicio de Pedidos
  ┌──────────────────────────────┐
  │ createOrder(customerId,      │
  │   productId,                 │  ← Tu modelo de dominio limpio
  │   price,                     │
  │   tax)                       │
  └──────────┬───────────────────┘
             │
  ┌──────────▼───────────────────┐
  │    Anti-Corruption Layer     │
  │                              │
  │  customerId → legacyCustCode │
  │  productId → legacySKU       │  ← Traducción bidireccional
  │  price → legacyPriceFormat   │
  │  tax → legacyTaxCalc         │
  └──────────┬───────────────────┘
             │
             ▼
  Sistema Legacy ERP

Composants de l’ACL

Composant	Responsabilité	Exemple
Translator	Convertit les données entre les modèles	`LegacyCustomer → Customer`
Adapter	Adapte l’interface du système externe	REST → SOAP, JSON → XML
Facade	Simplifie l’API du système externe	5 appels legacy → 1 méthode propre
Mapper	Mappe champs et valeurs entre les modèles	`status: "A"` → `status: "active"`

Exemple de traduction

Tu modelo (dominio limpio):
  Order {
    id: "ORD-001"
    customer: { id: "C-123", name: "María García" }
    items: [{ product: "Laptop", quantity: 1, price: 1500 }]
    status: "confirmed"
  }

Modelo del sistema legacy:
  LEGACY_ORDER {
    ORDER_NUM: "00000001"
    CUST_CODE: "CUST00123"
    CUST_NM: "GARCIA, MARIA"
    LINE_ITEMS: "LAPTOP|1|150000"  (precio en centavos, pipe-separated)
    STAT_CD: "CF"
  }

El ACL traduce entre ambos modelos:
  OrderACLTranslator.toExternal(order) → LEGACY_ORDER
  OrderACLTranslator.fromExternal(legacyOrder) → Order

Emplacement de l’ACL

L’ACL peut être implémenté à différents niveaux :

En tant que service indépendant :

Tu Servicio ──► ACL Service ──► Sistema Externo

En tant que module au sein de votre service :

Tu Servicio
  ├── Domain Layer (limpio)
  ├── Application Layer
  └── ACL Module ──► Sistema Externo

En tant que partie de l’API Gateway :

API Gateway (con ACL) ──► Sistema Legacy

Avantages

Domaine propre : votre modèle métier n’est pas contaminé par des concepts externes
Découplage : les changements dans le système externe sont absorbés par l’ACL, et non par votre domaine
Tests isolés : vous pouvez tester votre domaine sans le système externe (mock de l’ACL)
Migration progressive : vous pouvez remplacer le système externe sans modifier votre domaine
Clarté : la logique de traduction est centralisée et explicite
Intégrations multiples : vous pouvez avoir des ACL différents pour différents systèmes externes

Compromis / Inconvénients

Code supplémentaire : l’ACL est du code qu’il faut écrire, tester et maintenir
Latence : une couche de traitement de plus à chaque appel
Synchronisation des changements : lorsque le système externe modifie son API, l’ACL doit être mis à jour
Complexité du mapping : certains mappings sont complexes (données sans équivalent direct)
Risque d’ACL obèse : si l’ACL grossit trop, il peut devenir un problème en soi
Double maintenance : les changements dans votre modèle ou dans le modèle externe imposent de mettre à jour l’ACL

Quand l’utiliser

Intégration avec des systèmes legacy dotés de modèles de données incompatibles
Consommation d’API tierces dont les modèles diffèrent de votre domaine
Migration progressive d’un monolithe vers des microservices
Lorsque plusieurs bounded contexts doivent communiquer sans contaminer leurs modèles
Intégration avec des systèmes utilisant des protocoles ou formats différents (SOAP, XML, fichiers plats)
Lorsque le système externe change fréquemment et que vous voulez isoler l’impact

Quand l’éviter

Intégration avec des systèmes qui partagent le même modèle de domaine
API externes simples où la traduction est triviale (un mapping de 2 à 3 champs)
Prototypes où la rapidité de développement prime sur la pureté du modèle
Lorsque le système externe est temporaire et sera bientôt remplacé

Technologies et implémentations courantes

Catégorie	Options
Patterns de conception	Adapter, Facade, Translator, Mapper
Bibliothèques de mapping	MapStruct (Java), AutoMapper (.NET), class-transformer (TS)
Intégration	Apache Camel, Spring Integration, MuleSoft
API Translation	GraphQL comme ACL, API Gateway avec transformations

Relation avec d’autres patterns

DDD (Bounded Context) : l’ACL protège les frontières entre les bounded contexts
API Gateway : peut implémenter des fonctions d’ACL pour les systèmes externes
BFF : le BFF agit comme un ACL entre le frontend et les microservices
Shared Kernel : alternative à l’ACL lorsque deux contextes partagent délibérément un modèle commun
Microservices : chaque microservice peut avoir son propre ACL pour les intégrations externes

Prochaines étapes

L’Anti-Corruption Layer est essentiel pour préserver l’intégrité de votre domaine. Pour comprendre comment gérer les défaillances dans la communication avec des systèmes externes, explorez le pattern Retry. Pour partager des modèles de manière contrôlée entre contextes, consultez le Shared Kernel.