Forward compatible : quand c'est au vieux code de survivre au nouveau

2026-07-16T00:00:00+00:00
Je pense qu'on connait tous ce qu'est la Backward Compatibility</code>. Quand on fait des api REST c'est quelque chose qu'on entend souvent. Faire des api compatibles avec le passé, c'est bien ancré dans nos têtes. En revanche, faire des api compatibles avec le futur, rarement. La Forward Compatibility</code> c'est produire du code capable de résister au futur. Je vais détailler ici ce que je connais du sujet, comment j'y ai été confronté et ce qu'il est possible de faire.</p>
Mise en situation</h2>
J'ai été amené dans mon parcours professionnel à créer tout un système de webhooks. Jusqu'à présent le produit n'avait que des api REST, ce qui est bien pratique mais pas suffisant notamment pour les cas où le client (enfin son SI) souhaite savoir quand un objet est supprimé par exemple. Sans entrer trop dans les détails, l'infra des webhooks consiste en plusieurs instances d'une même application déployée dans un cluster kubernetes. C'est résilient, on peut faire des déploiements sans interruption de service. Bref c'est le FUTUR, ou le passé si vous me lisez depuis le futur...</p>
Les autres applications vont envoyer des évènements aux webhooks et le message sera distribué à une seule des instances. Si on schématise ça donnerait quelque chose comme ceci:</p>


On va garder cet exemple des webhooks tout le long de l'article pour illustrer et mieux comprendre ce dont on va parler. Pimentons un peu cette histoire avec une évolution dans les évènements:</p>

v1: état initial, un seul évènement ORDER_CREATED</code> avec les deux champs amount</code> et orderId</code>.</li>
v2: ajout du champ currency</code>.</li>
v3: nouvel évènement ORDER_REFUNDED</code></li>
v4: renommage du champ orderId</code> en id</code></li>
</ul>
Backward compatible</h2>
Le backward compatible, comme je le disais en introduction, on le connait bien. Même si on ne fait pas d'api REST, on le rencontre assez rapidement sur d'autres sujets, notamment avec les base de données. Supprimer une colonne dans une table est un breaking change</code>. Si on ne déploie pas dans le même temps une nouvelle version de l'applicatif qui n'utilise plus cette colonne, on va avoir des erreurs! Même sanction si on renomme un champ. Habituellement ce qu'on fait c'est qu'on fait des petites versions itératives pour éviter le souci. Prenons l'exemple d'un renommage de colonne, de nom</code> vers full_name</code> : ça donnerait quelque chose comme ceci, étalé sur quatre petites versions :</p>
Version</th> Application</th> Base de données</th></tr></thead>

v1.0</td> lit et écrit nom</code></td> colonne nom</code></td></tr>
v1.1</td> lit nom</code>, écrit nom</code> et full_name</code></td> + colonne full_name</code></td></tr>
v1.2</td> lit et écrit full_name</code> (n'utilise plus nom</code>)</td> nom</code> et full_name</code> (mais nom</code> n'est plus lu)</td></tr>
v2.0</td> lit et écrit full_name</code></td> colonne nom</code> supprimée</td></tr>
</tbody></table>
Chaque étape mineure permet de s'assurer qu'on n'aura pas de soucis de version entre l'application et la base de données. C'est un classique de migration. Même dans le cas où on aurait plusieurs instances de l'application, ces déploiements par étapes mineures permettent d'éviter toute erreur.</p>
Si on reprend notre exemple des webhooks et de l'évolution des évènements, la v2 ajoute un champ, ce n'est pas un breaking change en théorie. Il faut juste faire attention à la modélisation pour s'assurer que la lecture de l'évènement ne tombe pas en erreur. En Java, avec Jackson, par défaut si un champ présent dans le JSON ne l'est pas dans le modèle, on aura une erreur. Deux options: soit on change ce comportement, soit on modélise de façon à ce que l'ajout d'un champ ne soit pas un breaking change. Alors évidemment on peut faire les deux, protocole bretelle-ceinture</code>!</p>
Ce qu'on peut faire donc c'est éviter ce type de modélisation:</p>
{
</span>  "</span>eventType</span>": "</span>ORDER_CREATED</span>",
</span>  "</span>id</span>": "</span>v1-order-1</span>",
</span>  "</span>occurredAt</span>": "</span>2026-01-01T10:00:00Z</span>",
</span>  "</span>orderId</span>": "</span>ord-1</span>",
</span>  "</span>amount</span>": </span>42.50
</span>}
</span></code></pre>
Il y a trois soucis avec ce modèle:</p>

tout ajout de champ provoque une erreur si on a le comportement par défaut de Jackson</li>
toute suppression de champ provoquera une erreur</li>
si on a plusieurs évènements il faudra soit plusieurs endpoints (si on fait du REST), soit gérer intelligemment la sérialisation</li>
</ul>
Le plus simple est d'adopter une modélisation de ce type:</p>
{
</span>  "</span>eventType</span>": "</span>ORDER_CREATED</span>",
</span>  "</span>id</span>": "</span>v1-order-1</span>",
</span>  "</span>occurredAt</span>": "</span>2026-01-01T10:00:00Z</span>",
</span>  "</span>data</span>": {
</span>    "</span>orderId</span>": "</span>ord-1</span>",
</span>    "</span>amount</span>": </span>42.50
</span>  }
</span>}
</span></code></pre>
Avec cette modélisation, on sépare les métadonnées des données et on peut donc gérer aussi bien les changements de modèle que plusieurs évènements! Le champ eventType</code> permet de savoir ce qu'on aura dans data</code>.
On pourra même ajouter un champ version</code> pour lire plusieurs versions d'un même évènement dans le même code, avec ou sans breaking changes.</p>
Et en Java on aurait ceci:</p>
@</span>JsonIgnoreProperties</span>(</span>ignoreUnknown </span>= </span>true</span>)
</span>public</span> record </span>EventEnvelope</span>(
</span>        </span>String</span> version,
</span>        </span>EventType</span> eventType,
</span>        </span>String</span> id,
</span>        </span>Instant</span> occurredAt,
</span>        </span>Map</span><</span>String</span>, </span>Object</span>> data
</span>) {
</span>}
</span></code></pre>
Ok donc en modélisant intelligemment, ajouter un champ ne casse rien. Pour être backward compatible, il faut donc que le code lié à la v2 dans les webhooks lise les champs v1 et ne plante pas s'il y a des champs v2 absents. Ça donnerait quelque chose comme ça:</p>
    </span>private</span> void </span>handleOrderCreated</span>(</span>EventEnvelope</span> envelope) {
</span>        </span>Object</span> orderId = envelope.</span>data</span>().</span>get</span>("</span>orderId</span>");
</span>        </span>if </span>(orderId == </span>null</span>) {
</span>            </span>throw new </span>MissingRequiredFieldException</span>("</span>orderId</span>", envelope.</span>id</span>(), envelope.</span>eventType</span>().</span>name</span>());
</span>        }
</span>        </span>Object</span> amount = envelope.</span>data</span>().</span>get</span>("</span>amount</span>");
</span>        </span>if </span>(amount == </span>null</span>) {
</span>            </span>throw new </span>MissingRequiredFieldException</span>("</span>amount</span>", envelope.</span>id</span>(), envelope.</span>eventType</span>().</span>name</span>());
</span>        }
</span>
</span>        </span>Object</span> currency = envelope.</span>data</span>().</span>getOrDefault</span>("</span>currency</span>", "</span>EUR</span>");
</span>
</span>        log.</span>info</span>("</span>Order {} created, amount={} {}</span>", orderId, amount, currency);
</span>    }
</span></code></pre>
Ainsi, avec du v1, on aura Order ord-1 created, amount=42.5 EUR</code> et avec du v2 Order ord-1 created, amount=42.5 USD</code> par exemple. On aurait également pu, à la place d'avoir une valeur par défaut, ne rien afficher.</p>
Alors pour l'ajout de champ ça fonctionne, cependant que se passe-t-il si on a nos webhooks en v1 et les producteurs d'évènements passent en v2? Sans l'annotation Jackson @JsonIgnoreProperties(ignoreUnknown = true)</code>, des erreurs. Avec, pas d'erreur, mais c'est uniquement parce que ce n'est pas un vrai breaking change. Si nos producteurs passaient directement en v4 (le renommage de orderId</code> en id</code>), ce serait la catastrophe... Il faut donc faire une migration coordonnée. On migre d'abord toutes les instances de webhooks pour être en v4 (gérer donc l'ancien et le nouveau nom de champ) puis seulement on migre les producteurs pour qu'ils puissent envoyer du v4. Cela ressemble un peu aux migrations itératives présentées précédemment.</p>


Dans le cas réel que j'ai rencontré, c'était ce qu'on avait fait. Tout simplement parce que nous avions peu de producteurs d'évènements (un seul gros monolithe) et qu'on pouvait déployer bien plus vite sur nos instances webhooks. Cependant, si on ne fait pas attention et qu'on finit par déployer du v3 (nouvel évènement) ou du v4 (breaking change) sur nos apps et qu'on n'a pas fini de déployer sur les webhooks, on va avoir des erreurs! Et si jamais on n'avait pas été capable de coordonner nos déploiements, il aurait été plus compliqué de gérer ça. C'est là que le forward compatible devient intéressant.</p>
Forward Compatible</h2>
Le Forward Compatible, c'est l'idée d'être capable de lire des messages qui viennent du futur. Il y a deux types de changements: ceux qui sont backward compatible et ceux qui ont des breaking changes. Si demain on reçoit un évènement qui a toujours les champs que je connais et dont j'ai besoin, grâce à ma modélisation résiliente, je pourrai toujours les lire et les utiliser. Si on reprend le code Java d'exemple utilisé plus haut : le code écrit pour la v1, avant même de connaître l'existence de currency</code>, n'a jamais eu besoin d'être modifié pour survivre à son arrivée en v2 — il ignore tout simplement ce qu'il ne lit pas. Ce n'est pas grave puisqu'en v1 des webhooks on ne pouvait pas deviner que ce champ existerait un jour! Donc faire du backward compatible nous permet déjà d'être Forward Compatible pour les évolutions mineures!</p>
Pour ce qui est des nouveaux types d'évènements. Notre modélisation JSON faisant que peu importe le type de message, seule la map data</code> est différente, on n'aura pas d'erreur de sérialisation. En revanche on sera incapable de lire le nouveau type de message. Pour éviter les erreurs, on doit router</code> les types d'évènements et avoir un fallback</code> sur les évènements inconnus:</p>
    </span>public</span> void </span>process</span>(</span>EventEnvelope</span> envelope) {
</span>        </span>ProcessedEvent</span>.</span>Outcome</span> outcome = </span>switch </span>(envelope.</span>eventType</span>()) {
</span>            </span>case </span>ORDER_CREATED </span>-> </span>{
</span>                </span>handleOrderCreated</span>(envelope);
</span>                yield </span>ProcessedEvent</span>.</span>Outcome</span>.</span>PROCESSED</span>;
</span>            }
</span>            </span>case </span>UNKNOWN </span>-> </span>{
</span>                log.</span>warn</span>("</span>Ignoring event {} of unknown type (version {}) — nothing crashed</span>", envelope.</span>id</span>(), envelope.</span>version</span>());
</span>                yield </span>ProcessedEvent</span>.</span>Outcome</span>.</span>IGNORED_UNKNOWN_TYPE</span>;
</span>            }
</span>        };
</span>
</span>        store.</span>record</span>(</span>new </span>ProcessedEvent</span>(envelope.</span>id</span>(), envelope.</span>eventType</span>(), envelope.</span>version</span>(), outcome, </span>Instant</span>.</span>now</span>()));
</span>    }
</span></code></pre>
Mais alors, quid de la v4 avec un breaking change ? Eh bien pas le choix, si une des deux exceptions est levée (donc l'absence d'un champ obligatoire) on doit la traiter. Le plus simple est de log un warning indiquant qu'un message du futur est devenu "illisible". Dans le cas d'api REST on renvoie une 422 Unprocessable Entity</code>, si on fait du message queue on nack</code> le message pour qu'il soit rejoué plus tard. Je ne détaille pas la gestion de ces erreurs, notamment avec du message queue tel que Pub/Sub, ce n'est pas le propos de l'article.</p>
Ainsi on n'est plus obligé de coordonner les déploiements, nos webhooks v1 pourront recevoir des messages v1 et v2 sans erreurs. On pourra même recevoir du v3 (nouvel évènement inconnu) et log un warning. Pour la v4 on aura des logs de warning et des 422 (ou nack) le temps que le déploiement soit terminé.</p>


Exemple de code avec le poc</h2>
Pour mieux comprendre et illustrer tout ça, j'ai fait générer par Claude Code un repo d'exemple, que j'ai bien sûr revu et corrigé. Vous pourrez le trouver ici : 
On y trouve deux modules, un par application Spring Boot. Un producer et un consumer d'évènements. On peut réaliser des appels REST sur le producer pour lui faire générer des évènements v1, v2, v3 ou v4. Ces évènements seront envoyés au consumer par une requête REST émise par le producer. Une ligne de log est censée être écrite pour chaque évènement reçu avec les informations qu'il contient.</p>
Rentrons un peu dans le détail, du moins sur les parties qui nous intéressent. Pour la partie producer, il s'agit surtout de regarder les différents évènements envoyés. On les retrouve dans 
{
</span>  "</span>version</span>": "</span>1</span>",
</span>  "</span>eventType</span>": "</span>ORDER_CREATED</span>",
</span>  "</span>id</span>": "</span>v1-order-1</span>",
</span>  "</span>occurredAt</span>": "</span>2026-01-01T10:00:00Z</span>",
</span>  "</span>data</span>": {
</span>    "</span>orderId</span>": "</span>ord-1</span>",
</span>    "</span>amount</span>": </span>42.50
</span>  }
</span>}
</span></code></pre>
{
</span>  "</span>version</span>": "</span>3</span>",
</span>  "</span>eventType</span>": "</span>ORDER_REFUNDED</span>",
</span>  "</span>id</span>": "</span>v3-order-1</span>",
</span>  "</span>occurredAt</span>": "</span>2026-03-01T10:00:00Z</span>",
</span>  "</span>data</span>": {
</span>    "</span>orderId</span>": "</span>ord-3</span>",
</span>    "</span>reason</span>": "</span>customer_request</span>"
</span>  }
</span>}
</span></code></pre>
On a donc bien un modèle commun et uniquement la map data</code> qui diffère selon le eventType</code>. Le champ version étant ici uniquement cosmétique. On pourrait, pour aller plus loin, utiliser cette version pour faire cohabiter plusieurs versions d'un même type d'évènement et avoir plusieurs méthodes différentes handleOrderCreated(...)</code> et handleOrderCreatedV2(...)</code>.</p>
Pour ce qui est du consumer, on a beaucoup plus de choses à regarder. Déjà commençons par la modélisation en Java de ces évènements:</p>
public enum </span>EventType </span>{
</span>
</span>    </span>ORDER_CREATED</span>,
</span>
</span>    @</span>JsonEnumDefaultValue
</span>    </span>UNKNOWN
</span>}
</span>
</span></code></pre>
@</span>JsonIgnoreProperties</span>(</span>ignoreUnknown </span>= </span>true</span>)
</span>public</span> record </span>EventEnvelope</span>(
</span>        </span>String</span> version,
</span>        </span>EventType</span> eventType,
</span>        </span>String</span> id,
</span>        </span>Instant</span> occurredAt,
</span>        </span>Map</span><</span>String</span>, </span>Object</span>> data
</span>) {
</span>}
</span></code></pre>
On retrouve bien le EventEnvelope</code> déjà vu avec le @JsonIgnoreProperties(ignoreUnknown = true)</code> qui permet de ne pas avoir d'erreur en cas de champ inconnu. Mais on a cette fois aussi une petite subtilité nouvelle dans EventType</code> avec le @JsonEnumDefaultValue</code> qui mettra par défaut à UNKNOWN</code> toute valeur inconnue de l'enum. On évite donc l'erreur lors des nouveaux types d'évènements que l'enum ne connaitrait pas.</p>
Pour ce qui est du controller REST rien d'exceptionnel, on délègue la gestion de l'évènement à un service. On ne traite ici que la partie REST:</p>
    @</span>PostMapping
</span>    </span>public </span>ResponseEntity</span><</span>Void</span>> </span>receive</span>(@</span>RequestBody EventEnvelope</span> envelope) {
</span>        processingService.</span>process</span>(envelope);
</span>        </span>return </span>ResponseEntity</span>.</span>accepted</span>().</span>build</span>();
</span>    }
</span></code></pre>
Le service en question est lui plus intéressant. On a déjà vu quelques extraits, mais voici sa version complète (rien de neuf ici, c'est juste l'assemblage de ce qu'on a déjà vu) :</p>
@</span>Service
</span>public class </span>EventProcessingService </span>{
</span>
</span>    </span>private static final </span>Logger </span>log </span>= </span>LoggerFactory</span>.</span>getLogger</span>(</span>EventProcessingService</span>.</span>class</span>);
</span>
</span>    </span>private final </span>InMemoryEventStore </span>store;
</span>
</span>    </span>public </span>EventProcessingService</span>(</span>InMemoryEventStore </span>store</span>) {
</span>        </span>this</span>.store </span>=</span> store;
</span>    }
</span>
</span>    </span>public void </span>process</span>(</span>EventEnvelope </span>envelope</span>) {
</span>        </span>ProcessedEvent</span>.</span>Outcome</span> outcome </span>= </span>switch </span>(envelope.</span>eventType</span>()) {
</span>            </span>case </span>ORDER_CREATED </span>-> </span>{
</span>                </span>handleOrderCreated</span>(envelope);
</span>                yield </span>ProcessedEvent</span>.</span>Outcome</span>.</span>PROCESSED</span>;
</span>            }
</span>            </span>case </span>UNKNOWN </span>-> </span>{
</span>                </span>// A type this consumer has never heard of. Forward-compatible
</span>                </span>// means "safely ignored today", not "silently dropped forever" —
</span>                </span>// it's still recorded, just not acted upon.
</span>                log.</span>warn</span>(</span>"</span>Ignoring event {} of unknown type (version {}) — nothing crashed</span>"</span>, envelope.</span>id</span>(), envelope.</span>version</span>());
</span>                yield </span>ProcessedEvent</span>.</span>Outcome</span>.</span>IGNORED_UNKNOWN_TYPE</span>;
</span>            }
</span>        };
</span>
</span>        store.</span>record</span>(</span>new </span>ProcessedEvent</span>(envelope.</span>id</span>(), envelope.</span>eventType</span>(), envelope.</span>version</span>(), outcome, </span>Instant</span>.</span>now</span>()));
</span>    }
</span>
</span>    </span>private void </span>handleOrderCreated</span>(</span>EventEnvelope </span>envelope</span>) {
</span>        </span>Object</span> orderId </span>=</span> envelope.</span>data</span>().</span>get</span>(</span>"</span>orderId</span>"</span>);
</span>        </span>if </span>(orderId </span>== </span>null</span>) {
</span>            </span>throw new </span>MissingRequiredFieldException</span>(</span>"</span>orderId</span>"</span>, envelope.</span>id</span>(), envelope.</span>eventType</span>().</span>name</span>());
</span>        }
</span>        </span>Object</span> amount </span>=</span> envelope.</span>data</span>().</span>get</span>(</span>"</span>amount</span>"</span>);
</span>        </span>if </span>(amount </span>== </span>null</span>) {
</span>            </span>throw new </span>MissingRequiredFieldException</span>(</span>"</span>amount</span>"</span>, envelope.</span>id</span>(), envelope.</span>eventType</span>().</span>name</span>());
</span>        }
</span>
</span>        </span>// v2 field: absent on v1 events, so it's read with a default rather
</span>        </span>// than required — that's what makes it safe to adopt before every
</span>        </span>// producer (and every past event) is on v2.
</span>        </span>Object</span> currency </span>=</span> envelope.</span>data</span>().</span>getOrDefault</span>(</span>"</span>currency</span>"</span>, </span>"</span>EUR</span>"</span>);
</span>
</span>        log.</span>info</span>(</span>"</span>Order {} created, amount={} {}</span>"</span>, orderId, amount, currency);
</span>    }
</span>}
</span></code></pre>
Je l'ai déjà expliqué en grande partie mais on y retrouve les points importants:</p>

Gestion des évènements inconnus par un warning mais pas d'exception!</li>
Gestion des breaking changes par un 422.</li>
Backward Compatibility en n'ayant des erreurs uniquement lorsqu'il manque un champ obligatoire dans les données.</li>
Utilisation de valeur par défaut si besoin en cas d'absence de champ optionnel (v2).</li>
</ul>
Le reste de l'application c'est du détail qui n'apporte rien à l'article ici. On peut tester le poc en démarrant les deux applications et en envoyant des curls sur le producer pour tester les différents scénarios.
Pour les scénarios v1 et v2 on voit bien ces lignes dans les logs du consumer:</p>
Order ord-1 created, amount=42.5 EUR
</span>Order ord-2 created, amount=19.9 USD
</span></code></pre>
Pour la v3 on obtient bien le warning:
Ignoring event v3-order-1 of unknown type (version 3) — nothing crashed</code></p>
Enfin pour la v4 on a ceci:</p>
$</span> curl</span> -X</span> POST http://localhost:8081/publish/v4-breaking-rename
</span>Event</span> v4-order-1 (type ORDER_CREATED) </span>is</span> missing required field '</span>orderId</span>' — this is a breaking change, not a forward-compatible one
</span></code></pre>
L'application consumer est dans une version équivalente à ce qu'on avait décrit pour la v2</code>:</p>

rétro compatible v1</li>
gère le v2</li>
warning sur du v3</li>
422 sur du v4 breaking change</li>
</ul>
Bonnes pratiques</h2>

Séparer l'enveloppe des données métiers. La map data</code> dans l'exemple -> un champ additionnel ne casse rien. On peut également gérer plusieurs types d'évènements sans avoir à les connaitre à l'avance.</li>
Ignorer les champs inconnus, sinon ça ne marche pas. Comme avec le @JsonIgnoreProperties(ignoreUnknown = true)</code> de Jackson.</li>
Prévoir un type/enum ouvert avec un fallback explicite. Ici on a utilisé le @JsonEnumDefaultValue + UNKNOWN</code>.</li>
Lire les champs optionnels en étant défensif pour les nouvelles versions. Voire même utiliser des valeurs par défaut si ça a du sens.</li>
Ne rendre les champs obligatoires que s'ils le sont vraiment, ni plus ni moins. Ça ne rendra pas un vrai renommage comme la v4 moins breaking, mais ça évite d'en créer d'autres inutilement, en exigeant des champs dont le code n'a en réalité pas besoin.</li>
Distinguer les cas "je ne sais pas traiter ça" de "il me manque une donnée vitale". Le premier peut être retenté plus tard : l'évènement est peut-être inconnu simplement parce que le déploiement du support de cette version est encore en cours, pas parce qu'il ne le sera jamais. Le second doit échouer et informer immédiatement (ici une 422).</li>
Ne pas utiliser la Forward Compatibility pour faire n'importe quoi. On évitera autant que possible de faire des breaking changes!</li>
Un déploiement rapide du consommateur réduit la fenêtre de risque, il ne la supprime pas.</li>
</ol>
conclusion</h2>
On a donc vu ici ce qu'était la Backward Compatibility, le code nouveau qui lit de l'ancien. On a vu aussi ce qu'était la Forward Compatibility, l'ancien qui survit au nouveau. On a vu également que faire du Backward permet facilement le Forward. Il en est la suite logique, mais pas forcément nécessaire, après tout YAGNI</a>! Enfin on a vu que ce n'était pas un prétexte pour faire n'importe quoi, ainsi que plein d'autres bonnes pratiques. N'hésitez pas à cloner, tester ou modifier le POC si vous voulez : 
Il ne faut pas s'attacher à son code

2026-07-16T00:00:00+00:00
Nous les devs, souvent, on aime bien coder. On aime le beau code, et surtout on adore que notre code soit beau. Parfois on trouve des solutions astucieuses et belles à des problèmes. Et ce code on le trouve bien fait, élégant. Bref on est fier de notre code. Et c'est chouette! Cependant il ne faut pas s'attacher à son code parce que à tout moment on sera amené à le revert, le corriger. Souvent c'est même un autre dev qui va supprimer votre code. Ce sera sans doute pour mieux.</p>
S'attacher à son code est inutile pour plein de raison. Peut-être que le problème que vous vouliez résoudre n'en était pas un. Peut-être qu'il existe une solution bien plus simple et donc plus ennuyeuse. Votre code il est beau aujourd'hui, mais demain ? ou après demain? Il finira par devenir moche. Les bonnes pratiques d'aujourd'hui sont les mauvaises de demain. Je sais pas si vous avez déjà relu du code que vous avez produit il y a 5 ans ou plus, mais il y a de fortes chances que vous le trouviez moche. Pire même il se peut que vous retombiez sur votre code et ayez oublié que vous en êtes l'auteur! Peut-être même avez-vous prononcé ces funestes paroles: "mais qui a produit ce code tout pourri ??" et un git blame révèle le drame...</p>
Le code de qualité ce n'est pas le code parfait ou celui qui respecte toutes les bonnes pratiques possibles. C'est celui qui restera correct le plus longtemps possible!</p>


Code First vs Contract First: Pourquoi choisir ?
2026-07-07T00:00:00+00:00
Écrire 400 lignes de YAML, qui aime ça ? Eh bien certainement pas moi! C'est un enfer à écrire et une purge à relire. Et comme à chaque fois dans ce genre de situation, il faut que je trouve une solution.</p>
Code first</h2>
La plupart du temps lorsqu'on met en place des endpoints REST, on le fait pour un usage interne. Il y a donc rarement de la documentation sur ces endpoints. Lorsqu'on fournit ces endpoints pour une autre équipe, il arrive qu'on s'accorde sur un contrat d'interface, mais c'est rare et souvent on va simplement exposer un endpoint qui ne fait rien.
Pour les endpoints publics, on va finir par publier une documentation technique pour les intégrateurs. Souvent ce sera fait après avoir implémenté les endpoints. Ce que j'ai beaucoup vu, c'est d'utiliser une lib comme Swagger. On annote les endpoints et la documentation est générée automatiquement. C'est ce qu'on appelle du code first.</p>
Voici un exemple de ce qu'on peut faire en code first:</p>
@</span>RestController
</span>@</span>RequestMapping</span>("</span>/api/v1/products</span>")
</span>@</span>Tag</span>(</span>name </span>= "</span>Products</span>", </span>description </span>= "</span>Product catalog API</span>")
</span>public class </span>ProductController </span>{
</span>
</span>    </span>private final </span>ConcurrentHashMap</span><</span>Long</span>, </span>ProductResponse</span>> products </span>= </span>new </span>ConcurrentHashMap</span><>();
</span>    </span>private final </span>AtomicLong </span>sequence </span>= </span>new </span>AtomicLong</span>(</span>0</span>);
</span>
</span>    </span>public </span>ProductController</span>() {
</span>        </span>long</span> id </span>=</span> sequence.</span>incrementAndGet</span>();
</span>        products.</span>put</span>(id, </span>new </span>ProductResponse</span>(id, </span>"</span>Dell XPS 15 Laptop</span>"</span>, </span>new </span>BigDecimal</span>(</span>"</span>1299.99</span>"</span>)));
</span>    }
</span>
</span>    @</span>Operation</span>(</span>summary </span>= "</span>Get a product by id</span>"</span>, </span>description </span>= "</span>Returns the details of a single product</span>"</span>)
</span>    @</span>ApiResponses</span>(</span>value </span>= </span>{
</span>        @</span>ApiResponse</span>(
</span>            </span>responseCode </span>= "</span>200</span>"</span>,
</span>            </span>description </span>= "</span>Product found</span>"</span>,
</span>            </span>content </span>= </span>@</span>Content</span>(</span>schema </span>= </span>@</span>Schema</span>(</span>implementation </span>= </span>ProductResponse</span>.</span>class</span>))
</span>        ),
</span>        @</span>ApiResponse</span>(
</span>            </span>responseCode </span>= "</span>404</span>"</span>,
</span>            </span>description </span>= "</span>Product not found</span>"</span>,
</span>            </span>content </span>= </span>@</span>Content
</span>        )
</span>    })
</span>    @</span>GetMapping</span>(</span>"</span>/{id}</span>"</span>)
</span>    </span>public </span>ResponseEntity</span><</span>ProductResponse</span>> </span>getProductById</span>(
</span>            @</span>Parameter</span>(</span>description </span>= "</span>Product id</span>"</span>, </span>required </span>= </span>true</span>, </span>example </span>= "</span>42</span>"</span>)
</span>            @</span>PathVariable </span>Long </span>id</span>) {
</span>        </span>return </span>Optional</span>.</span>ofNullable</span>(products.</span>get</span>(id))
</span>                .</span>map</span>(</span>ResponseEntity</span>::</span>ok</span>)
</span>                .</span>orElseGet</span>(() </span>-> </span>ResponseEntity</span>.</span>notFound</span>().</span>build</span>());
</span>    }
</span>
</span>    @</span>Schema</span>(</span>description </span>= "</span>A product</span>"</span>)
</span>    </span>public</span> record </span>ProductResponse</span>(
</span>
</span>        @</span>Schema</span>(</span>description </span>= "</span>Product id</span>"</span>, </span>example </span>= "</span>42</span>"</span>)
</span>        </span>Long </span>id</span>,
</span>
</span>        @</span>Schema</span>(</span>description </span>= "</span>Product name</span>"</span>, </span>example </span>= "</span>Dell XPS 15 Laptop</span>"</span>)
</span>        </span>String </span>name</span>,
</span>
</span>        @</span>Schema</span>(</span>description </span>= "</span>Unit price</span>"</span>, </span>example </span>= "</span>1299.99</span>"</span>)
</span>        </span>BigDecimal </span>price
</span>    ) {}
</span>}
</span></code></pre>
Et voici ce qu'on obtient en générant la documentation:</p>
openapi</span>: </span>3.0.1
</span>info</span>:
</span>  </span>title</span>: </span>OpenAPI definition
</span>  </span>version</span>: </span>v0
</span>servers</span>:
</span>- </span>url</span>: </span>http://localhost:8099
</span>  </span>description</span>: </span>Generated server url
</span>tags</span>:
</span>- </span>name</span>: </span>Products
</span>  </span>description</span>: </span>Product catalog API
</span>paths</span>:
</span>  </span>/api/v1/products/{id}</span>:
</span>    </span>get</span>:
</span>      </span>tags</span>:
</span>      - </span>Products
</span>      </span>summary</span>: </span>Get a product by id
</span>      </span>description</span>: </span>Returns the details of a single product
</span>      </span>operationId</span>: </span>getProductById
</span>      </span>parameters</span>:
</span>      - </span>name</span>: </span>id
</span>        </span>in</span>: </span>path
</span>        </span>description</span>: </span>Product id
</span>        </span>required</span>: </span>true
</span>        </span>schema</span>:
</span>          </span>type</span>: </span>integer
</span>          </span>format</span>: </span>int64
</span>        </span>example</span>: </span>42
</span>      </span>responses</span>:
</span>        "</span>404</span>":
</span>          </span>description</span>: </span>Product not found
</span>        "</span>200</span>":
</span>          </span>description</span>: </span>Product found
</span>          </span>content</span>:
</span>            '</span>*/*</span>':
</span>              </span>schema</span>:
</span>                </span>$ref</span>: '</span>#/components/schemas/ProductResponse</span>'
</span>components</span>:
</span>  </span>schemas</span>:
</span>    </span>ProductResponse</span>:
</span>      </span>type</span>: </span>object
</span>      </span>properties</span>:
</span>        </span>id</span>:
</span>          </span>type</span>: </span>integer
</span>          </span>description</span>: </span>Product id
</span>          </span>format</span>: </span>int64
</span>          </span>example</span>: </span>42
</span>        </span>name</span>:
</span>          </span>type</span>: </span>string
</span>          </span>description</span>: </span>Product name
</span>          </span>example</span>: </span>Dell XPS 15 Laptop
</span>        </span>price</span>:
</span>          </span>type</span>: </span>number
</span>          </span>description</span>: </span>Unit price
</span>          </span>example</span>: </span>1299.99
</span>      </span>description</span>: </span>A product
</span>
</span></code></pre>
Ça fonctionne bien et c'est assez pratique. Maintenant je peux utiliser ce document OpenAPI où je veux. Soit dans un outil tiers (quasiment tous prennent en charge ce format), soit dans un Swagger UI. La documentation est à jour avec le code. Je peux envoyer ce document aux personnes qui vont intégrer mes endpoints. Ils pourraient ainsi commencer à les intégrer sans que mes endpoints soient en production. En revanche, si je fais des changements, je devrais leur envoyer la nouvelle version de ce document.</p>
Le code first, c'est vraiment la méthode la plus pratique et confortable. La plupart du temps c'est sans doute la méthode la plus simple et la plus utilisée. Cependant elle requiert d'implémenter l'endpoint pour générer la documentation. Alors oui, on peut écrire des endpoints vides qui ne font rien et ainsi générer la documentation pour finir ensuite l'implémentation. En revanche, là où c'est peu pratique, c'est si on souhaite avoir des échanges sur les contrats d'interfaces avec plusieurs utilisateurs. Que ce soit une autre équipe ou des intégrateurs extérieurs. Et c'est la raison pour laquelle il existe l'autre approche : le contract first.</p>
Contract first</h2>
C'est la méthode inverse du code first : on part des specifications (du document OpenAPI donc) et on génère le code qui correspond. L'intérêt de faire ça, je l'ai déjà évoqué un peu avant, c'est qu'il permet d'échanger sur le contrat d'interface AVANT d'engager du temps et de l'effort sur l'implémentation de l'endpoint. Le YAML, bien que je n'aime pas spécialement ce format, est "lisible" par des non devs. Un Product Owner peut le relire et y trouver des erreurs ou incohérences. L'autre intérêt est qu'on peut paralléliser la création des endpoints et ses usages. On crée la documentation, et une fois validée, on l'envoie aux équipes en charge de l'intégrer. Chacun peut donc travailler sans avoir besoin de l'autre. Un autre intérêt est qu'on peut mettre en place des tests automatisés qui vérifient que l'implémentation est bien conforme aux specs, contrairement au code first où si on change le code, les specs changent.</p>
Et donc pour cette méthode il suffit d'écrire et valider le document OpenAPI, et ensuite générer le code. Je ne détaillerai pas ici comment faire, je vous laisse regarder cet article qui le présente très bien: API First Development with Spring Boot and OpenAPI 3.0</a>.</p>
Toujours pas pleinement satisfaisant</h2>
Le principal problème avec le contract first, c'est qu'il nous demande d'écrire du YAML. Alors, pour un endpoint comme celui que j'ai donné en exemple, ça va. Mais quand on commence à en avoir beaucoup, qu'on a des références un peu partout, il faut le maintenir. Je trouve que le temps gagné pour paralléliser le travail de plusieurs équipes est complètement perdu lors de l'écriture et la relecture du fameux document OpenAPI. D'autant plus que tout doit être inclus dans ce document. Les exemples de requêtes, de réponses, d'erreurs etc.</p>
Démarche et POC</h2>
Pour les raisons que j'ai évoquées, chaque approche a ses avantages et inconvénients. Chacune répond à des besoins différents. Je pense qu'en dehors de dépendances avec d'autres équipes ou d'endpoints destinés à des intégrateurs externes, il faut privilégier le code first. </p>
Alors je sais que certains PO vont utiliser des outils en ligne pour générer du YAML à partir d'une interface graphique. Toutefois ils ne répondent pas à tous les soucis évoqués et créent une nouvelle dépendance envers un outil tiers.</p>
Ce que je me suis dit, c'est que l'approche contract first est, dans les cas où elle est pertinente, la bonne, mais il faut supprimer les frictions. Notamment en ce qui concerne la génération du document OpenAPI. Et donc pourquoi ne pas faire générer la documentation par du code mais seulement pour la partie contrat ? On ne fait pas de réelle implémentation, juste ce qu'il faut pour générer le document et le transmettre aux personnes concernées. L'idée serait donc non pas d'écrire un document OpenAPI en YAML mais d'écrire du code Java pour la faire générer. On pourrait donc écrire uniquement les DTOs (objets requests/responses et tout ce dont on a besoin pour les décrire) et les interfaces qui décriraient les endpoints. </p>
Le souci, c'est que pour faire générer la doc il faut avoir des controllers REST et pas uniquement des interfaces... Je n'ai rien trouvé sur internet pour résoudre ce problème. Je me suis donc dit qu'au lieu d'implémenter les interfaces avec des controllers, j'allais faire un truc qui les implémente à la volée. Après tout ces pseudo-contrôleurs juste pour implémenter une interface et qui ne retournent rien, ça ne doit pas être compliqué à faire.</p>
J'ai donc réalisé un POC qu'on peut trouver ici: Yagni/spec-from-skeleton</a></p>
Alors comment ça fonctionne ? Je ne détaillerai pas le projet entier, vous pouvez aller le voir si ça vous intéresse. Pour la partie "magique" tout est dans la classe ApiStubAutoConfiguration</code> qui se trouve ici</a>. C'est un BeanDefinitionRegistryPostProcessor</code> qui, comme son nom l'indique, démarre assez tôt dans le startup Spring, surtout avant que le context n'ait besoin des controllers. Et voici ce qu'il fait:</p>
    @</span>Override
</span>    </span>public</span> void </span>postProcessBeanDefinitionRegistry</span>(</span>BeanDefinitionRegistry</span> registry) throws </span>BeansException </span>{
</span>        log.</span>info</span>("</span>🔍 Scanning '{}' for @RequestMapping API interfaces...</span>", </span>CONTRACT_PACKAGE</span>);
</span>
</span>        </span>Set</span><</span>Class</span><?>> apiInterfaces = </span>findApiInterfaces</span>();
</span>
</span>        log.</span>info</span>("</span>✅ Found {} API interface(s) to register as stub controllers</span>", apiInterfaces.</span>size</span>());
</span>
</span>        </span>for </span>(</span>Class</span><?> apiInterface : apiInterfaces) {
</span>            </span>registerStubController</span>(registry, apiInterface);
</span>        }
</span>    }
</span></code></pre>
Il va trouver toutes les interfaces déclarées et pour chacune il va créer et enregistrer le bean en question. Ainsi, pour l'application Spring Boot, le controller existe vraiment.</p>
Concernant la génération du bean au démarrage, j'utilise ByteBuddy et je le fais à partir de l'interface:</p>
    </span>private </span>Class</span><?> </span>createStubControllerClass</span>(</span>Class</span><?> apiInterface) {
</span>        </span>String</span> className = apiInterface.</span>getSimpleName</span>() + "</span>StubImpl</span>";
</span>
</span>        </span>try </span>(</span>DynamicType</span>.</span>Unloaded</span><?> unloaded = </span>new </span>ByteBuddy</span>()
</span>            .</span>subclass</span>(</span>Object</span>.</span>class</span>)
</span>            .</span>implement</span>(apiInterface)
</span>            .</span>name</span>(apiInterface.</span>getPackage</span>().</span>getName</span>() + "</span>.generated.</span>" + className)
</span>            .</span>annotateType</span>(</span>AnnotationDescription</span>.</span>Builder</span>.</span>ofType</span>(</span>RestController</span>.</span>class</span>).</span>build</span>())
</span>            .</span>annotateType</span>(</span>Arrays</span>.</span>stream</span>(apiInterface.</span>getAnnotations</span>())
</span>                .</span>map</span>(</span>AnnotationDescription</span>.</span>ForLoadedAnnotation</span>::</span>of</span>)
</span>                .</span>toArray</span>(</span>AnnotationDescription</span>[]</span>::</span>new</span>))
</span>            .</span>method</span>(</span>ElementMatchers</span>.</span>any</span>())
</span>            .</span>intercept</span>(</span>InvocationHandlerAdapter</span>.</span>of</span>(</span>new </span>StubMethodHandler</span>()))
</span>            .</span>make</span>()) {
</span>
</span>            </span>return</span> unloaded.</span>load</span>(apiInterface.</span>getClassLoader</span>()).</span>getLoaded</span>();
</span>        }
</span>    }
</span></code></pre>
On ne fait que créer une classe qui implémente l'interface. On lui ajoute l'annotation @RestController</code> pour qu'elle soit bien détectée par Spring, et on lui fait hériter toutes les annotations de l'interface. </p>
J'ai également créé le script generate-spec.sh</code> pour générer la documentation sans devoir tout lancer à la main. </p>
Le nouveau workflow</h2>
Ok donc le POC nous montre qu'on peut générer la documentation à partir uniquement d'interface et de DTOs. Cela ressemble beaucoup au code first à ceci près qu'on n'a pas écrit le code métier. Si on met de côté le module spec-generator</code> (il s'agit de l'outil, on ne le crée qu'une fois), le code utilisé pour générer la documentation se trouve dans le module contract</code>. Il ne contient que des interfaces ou DTOs (request et response principalement). On obtient donc un module qui servira de contrat d'interface entre les équipes. On peut éventuellement décider de rendre ce module public aux intégrateurs extérieurs, mais c'est un autre débat. </p>
Ce module pourra donc être directement utilisé dans les autres projets aussi bien clients que ceux qui implémenteront réellement les interfaces. C'est une vraie différence avec le code first tel que je le décrivais plus haut : là où je devais renvoyer manuellement une nouvelle version du document OpenAPI à chaque changement, ici le contrat est une dépendance versionnée comme une autre. Un mvn dependency:update</code> (ou équivalent) suffit pour qu'une équipe consommatrice récupère la dernière version du contrat.
Il est maintenant également le support d'échange lors de la création du contrat entre les devs et le Product Owner. Si on reprend l'exemple présent dans mon POC, en voici un extrait :</p>
@</span>Tag</span>(</span>name </span>= "</span>Products</span>", </span>description </span>= "</span>Product catalog API</span>")
</span>@</span>RequestMapping</span>("</span>/api/v1/products</span>")
</span>public interface </span>ProductApi </span>{
</span>
</span>    @</span>Operation</span>(
</span>        </span>summary </span>= "</span>List products</span>"</span>,
</span>        </span>description </span>= "</span>Returns a paginated list of all products</span>"
</span>    )
</span>    @</span>ApiResponse</span>(
</span>        </span>responseCode </span>= "</span>200</span>"</span>,
</span>        </span>description </span>= "</span>Product list</span>"</span>,
</span>        </span>content </span>= </span>@</span>Content</span>(</span>schema </span>= </span>@</span>Schema</span>(</span>implementation </span>= </span>ProductListResponse</span>.</span>class</span>))
</span>    )
</span>    @</span>GetMapping
</span>    </span>ResponseEntity</span><</span>ProductListResponse</span>> </span>listProducts</span>(
</span>        @</span>Parameter</span>(</span>description </span>= "</span>Page number (zero-based)</span>"</span>, </span>example </span>= "</span>0</span>"</span>)
</span>        @</span>RequestParam</span>(</span>defaultValue </span>= "</span>0</span>"</span>) </span>int </span>page</span>,
</span>
</span>        @</span>Parameter</span>(</span>description </span>= "</span>Page size</span>"</span>, </span>example </span>= "</span>10</span>"</span>)
</span>        @</span>RequestParam</span>(</span>defaultValue </span>= "</span>10</span>"</span>) </span>int </span>size</span>,
</span>
</span>        @</span>Parameter</span>(</span>description </span>= "</span>Sort criterion</span>"</span>, </span>example </span>= "</span>name</span>"</span>)
</span>        @</span>RequestParam</span>(</span>defaultValue </span>= "</span>name</span>"</span>) </span>String </span>sort
</span>    );
</span>}
</span></code></pre>
Et son implémentation dans l'exemple fourni dans le POC:</p>
@</span>RestController
</span>public class </span>ProductController </span>implements </span>ProductApi </span>{
</span>    </span>// class fields && constructor here...
</span>
</span>    @</span>Override
</span>    </span>public </span>ResponseEntity</span><</span>ProductListResponse</span>> </span>listProducts</span>(</span>int </span>page</span>, </span>int </span>size</span>, </span>String </span>sort</span>) {
</span>        </span>return </span>ResponseEntity</span>.</span>ok</span>(</span>paginate</span>(</span>List</span>.</span>copyOf</span>(products.</span>values</span>()), page, size));
</span>    }
</span>}
</span>
</span></code></pre>
Ça a un intérêt qu'on n'a pas dans le contract-first pur : ici l'implémentation dépend du contrat au sens propre du terme. Si demain on modifie l'interface ProductApi</code> (un paramètre en plus, un type de retour différent), ProductController</code> ne compile plus tant qu'il n'est pas mis à jour en conséquence. On obtient donc, sans rien écrire de plus, l'équivalent des tests de conformité contrat/implémentation que je citais plus haut comme un des atouts du contract-first classique, sauf que là c'est le compilateur qui s'en charge.</p>
On peut voir également dans l'interface UserApi</code></a> qu'on peut découper les différents endpoints en catégories, comme ici avec UserReadOperations</code></a> et UserWriteOperations</code></a>. C'est une proposition de découpage, mais on peut faire comme on veut. L'intérêt de découper est qu'on peut ensuite implémenter tous les endpoints ou seulement une partie si besoin. Sachant qu'on n'est pas obligé d'implémenter ces interfaces directement tant qu'on crée les endpoints à la fin, mais je trouve plus propre et sécurisant de faire comme ça.</p>
Un avantage secondaire est qu'on sépare la documentation de l'implémentation, ce qui permet d'alléger grandement le RestController. </p>
Avec les interfaces et les DTOs associés, on peut co-construire entre le dev et le PO le contrat d'interface. Une fois le contrat validé, on peut merger la Pull Request dans la branche principale et avoir le contrat disponible pour tout le monde. Pour ce qui est de publier la documentation aux intégrateurs externes, on pourra se reposer sur la CI afin de générer la documentation après tout nouveau commit. Il pourra ensuite être partagé, voire même publié directement dans la documentation publique (que ce soit automatiquement ou non).</p>
On peut d'ailleurs pousser cette logique plus loin : la même mécanique CI peut tourner sur une branche en cours de travail, pas seulement après merge. Ça permet de déployer un environnement éphémère avec le Swagger UI à jour, accessible via un lien dans la Pull Request. Le PO peut donc relire et valider le contrat sur un rendu Swagger UI classique, exactement comme il le ferait avec du contract-first pur, sans qu'aucune ligne de code métier n'ait été écrite.</p>
Limites ?</h2>
Ce nouveau workflow apporte pas mal d'avantages, mais il n'est pas exempt de défauts ou limitations. Voici celles que j'ai identifiées:</p>

Dépendance à ByteBuddy. Encore une dépendance à surveiller et mettre à jour... </li>
Couplage fort à l'écosystème Java/Spring. Je travaille principalement dans cet écosystème, mais j'imagine qu'on pourrait trouver une solution similaire pour les autres.</li>
L'implémentation de l'interface est optionnelle. Il pourra donc subsister un risque de divergence entre les specs et l'implémentation réelle. Mais peut-on vraiment empêcher les humains de faire n'importe quoi ?</li>
Coût de complexité pour la CI. Pour vraiment tirer parti de tout l'intérêt de ce nouveau workflow, il faut mettre en place des nouveaux pipelines pour générer et intégrer la documentation. Il faudra bien sûr la maintenir.</li>
Coût de maintenance du module spec-generator</code>. Et oui on n'oublie pas les mises à jour de sécurité!</li>
Regrouper les APIs de plusieurs équipes dans un seul module contract</code> pose question : un changement cassant sur une seule API forcerait une montée de version majeure pour tout le monde, même les équipes non concernées.</li>
</ul>
Mais surtout, contrairement à ma "promesse" initiale, on n'écrit pas moins de descriptions qu'en YAML : les annotations Java restent verbeuses. Le vrai gain est ailleurs : autocomplétion IDE, refactoring sûr, erreurs détectées à la compilation et un artefact réutilisable comme dépendance plutôt qu'un simple document.</p>
Prochaines pistes</h2>
Ce projet reste un POC, et il y a plusieurs pistes qui mériteraient d'être creusées. Découper le module contract</code> en sous-modules par équipe ou bounded context permettrait de limiter le rayon d'impact des changements cassants évoqués plus haut. Et même si je reste concentré sur l'écosystème Spring pour l'instant, je serais curieux de voir si un mécanisme équivalent pourrait s'appliquer à d'autres frameworks. On pourrait aussi packager spec-generator</code> comme un vrai starter réutilisable, amortissant ainsi le coût de mise en oeuvre de l'outil.</p>
Il ne faut pas s'attacher à son code

Code First vs Contract First: Pourquoi choisir ?

~/journal

debugging tool: méthode du canard en plastique

avoid premature optimization

Pourquoi je m'embête à auto-héberger mes services cloud

YAGNI

Forward compatible : quand c'est au vieux code de survivre au nouveau
