Le problème que tout le monde connaît mais que personne ne résout vraiment
Dans la plupart des projets web modernes, le front-end et le back-end évoluent en parallèle, portés par des équipes différentes, des langages différents, des rythmes différents. Angular d'un côté, Symfony PHP de l'autre — ou Java Spring, .NET, Python. Et entre les deux : un no man's land de conventions informelles, de documentation qui dérive, d'interfaces TypeScript synchronisées à la main.
Le résultat ? Des bugs de désérialisation découverts en production, des réunions de synchronisation qui s'éternisent, et une dette technique silencieuse qui s'accumule à chaque sprint.
C'est précisément ce problème qu'adresse Benjamin Richard dans son article publié sur DEV Community, Contract-Driven Development: Architecting Zero-Friction between various ecosystems. Sa conclusion est nette : le Single Source of Truth n'est pas qu'un principe de modélisation de bases de données. C'est une stratégie d'architecture à part entière, applicable à l'ensemble de la chaîne de valeur d'un produit web.
OpenAPI 3.1 + JSON Schema : un contrat, pas une documentation
L'approche Contract-Driven Development (CDD) repose sur un principe simple : définir le contrat avant d'écrire le code. Ce contrat — un fichier OpenAPI 3.1 — devient la référence unique à partir de laquelle tous les artefacts sont générés :
- Les types TypeScript pour le client Angular
- Les DTOs PHP pour le back-end Symfony
- Les règles de validation côté serveur
- La documentation de l'API
OpenAPI 3.1 est ici un choix structurant : c'est la première version du standard à être pleinement compatible avec JSON Schema Draft 2020-12, ce qui ouvre la porte à une expressivité bien supérieure — compositions de schémas, polymorphisme, références croisées — sans sacrifier l'interopérabilité.
Le fichier de spécification cesse d'être un document annexe mis à jour après coup. Il devient le point de départ du développement, le livrable que les équipes négocient et valident ensemble avant la moindre ligne de code métier.
L'architecture BFF comme zone de contrôle
L'article propose une organisation en couches qui mérite attention. Entre le client Angular et les microservices métier, une couche Backend-for-Frontend (BFF) — ici implémentée en Symfony PHP — joue le rôle de passerelle typée.
Cette séparation n'est pas anodine. Elle permet de :
Isoler le client des complexités du back-end. Le BFF expose une API taillée pour les besoins du front-end, agrégeant et reformatant les réponses des services sous-jacents. Le client Angular ne connaît qu'un seul contrat, stable et maîtrisé.
Centraliser la validation de contrat. C'est au niveau du BFF que l'on vérifie la conformité des données au schéma OpenAPI, dans les deux sens — requêtes entrantes et réponses sortantes. Si un microservice métier retourne une structure inattendue, le problème est détecté au niveau architecture, pas en production.
Permettre l'évolution indépendante des couches. Un microservice Java peut évoluer sans impacter directement le client Angular, à condition que le BFF absorbe le changement et maintienne le contrat exposé.
Cette architecture est particulièrement pertinente dans les contextes polyglotes — et c'est l'un des points forts de l'approche CDD : le contrat est agnostique au langage. Peu importe que le service de paiement soit en .NET, que le service de catalogue soit en Python et que le BFF soit en Symfony. Tous parlent le même schéma.
Ce que cela change concrètement pour une équipe Symfony
Pour une équipe PHP/Symfony, adopter le Contract-Driven Development implique quelques changements de pratique qui méritent d'être anticipés.
La spécification OpenAPI doit être versionnée avec le code. Pas dans Confluence, pas dans un wiki séparé — dans le dépôt Git, au même niveau que le code source. C'est la condition pour que le contrat reste synchronisé avec les implémentations.
La génération de code devient un outil de build. Des outils comme openapi-generator permettent de générer automatiquement les classes PHP correspondant aux schémas définis. Cela réduit le risque d'écart entre la spécification et l'implémentation — mais cela suppose d'intégrer cette étape dans la pipeline CI/CD.
La validation devient déclarative. Plutôt que de multiplier les assertions dans les contrôleurs Symfony, la validation des payloads entrants peut être déléguée à une bibliothèque JSON Schema. Le schéma fait foi ; le code de validation est généré ou inféré depuis lui.
Les breaking changes deviennent visibles. Lorsque le contrat est la source de vérité, toute modification incompatible est immédiatement détectable — par diff de fichier, par outil de linting OpenAPI, ou par les tests de contrat (Pact, par exemple). Ce qui était auparavant une surprise en intégration devient un signal explicite lors de la revue de code.
Conclusion : un investissement d'architecture, pas un outil de plus
Le Contract-Driven Development ne se résume pas à adopter OpenAPI. C'est un changement de posture : le contrat d'API est un livrable de première classe, pas un sous-produit de l'implémentation.
Pour les équipes qui développent des applications web avec Symfony PHP en back-end et Angular (ou React, Vue) en front-end, cette approche offre un levier concret pour réduire les frictions d'intégration, fiabiliser les échanges inter-équipes et rendre les changements d'API explicites et traçables.
Le Single Source of Truth n'est pas qu'un principe pour votre base de données. Appliqué à vos interfaces API, il peut transformer la façon dont vos équipes collaborent — et la robustesse de ce que vous livrez.
📖 Article source : Contract-Driven Development: Architecting Zero-Friction between various ecosystems — Benjamin Richard, DEV Community
