Mises en ligne de mocks d'API contractuels

Pourquoi commencer par un contrat

J'ai créé MockDeck après avoir vu des équipes perdre des semaines à attendre un backend qui n'arrivait jamais à temps. La première étape que je prends avec chaque nouvelle fonctionnalité est d'écrire une courte description du point de terminaison que les ingénieurs frontend et backend peuvent examiner. Cette description devient le contrat. Lorsque le contrat est fixé, le frontend peut commencer à coder contre un mock qui se comporte exactement comme le service réel le fera, tandis que l'équipe backend travaille sur la mise en œuvre en parallèle. Cela élimine la période d'inactivité où les développeurs regardent un 404 ou un placeholder qui ne renvoie que des codes de succès. En ancrant le travail sur un artefact concret, nous réduisons la boucle de feedback de jours à heures et évitons le coûteux rétravail qui se produit lorsque les hypothèses sur la forme de la charge utile ou la gestion des erreurs s'avèrent incorrectes.

Lorsqu'un contrat existe tôt, les concepteurs peuvent créer des composants d'interface utilisateur qui consomment la forme de données exacte, les QA peuvent écrire des cas de test basés sur les réponses d'erreur définies, et DevOps peut configurer des serveurs de mock dans les environnements de staging sans attendre le service réel.

Rédaction du contrat

Un contrat doit capturer chaque comportement observable de l'endpoint. Je commence par le chemin HTTP et la méthode, puis note toute schéma d'authentification (clé API, jeton porteur, TLS mutuel). Ensuite, je liste les paramètres de requête : chaînes de requête, en-têtes et champs de corps, en les marquant comme requis ou facultatifs. Pour chaque champ, j'ajoute un type (chaîne, nombre, booléen, tableau, objet) et un format si nécessaire (e-mail, date-heure, uuid). Je définit ensuite la réponse de réussite : code de statut, en-têtes et forme complète de la charge utile avec les types et les formats. Enfin, j'ajoute des cas d'erreur que le frontend doit gérer : erreurs de validation (400), non trouvé (404), non autorisé (401), limité de taux (429) et erreurs de serveur (5xx). Pour chaque erreur, j'inclus un corps d'exemple qui montre la forme du message d'erreur.

Élément de contrat | Valeur exemple | Notes Chemin | /v1/orders | Ressource versionnée Méthode | POST | Crée une nouvelle commande Auth | Jeton porteur | En-tête Authorization requis Corps de requête – requis | customer_id (chaîne, uuid) | Doit exister dans la base de données Corps de requête – facultatif | note (chaîne, max 500) | Commentaire libre Réponse de réussite | 201, {order_id, created_at} | En-tête Location avec URL Erreur de validation | 400, {errors: [{field: "customer_id", message: "must be uuid"}]} | Aide le frontend à afficher des avertissements intégrés Non trouvé | 404, {error: "order not found"} | Se produit sur GET /v1/orders/:id lorsque l'ID est inconnu

Je conserve le contrat dans un fichier texte brut (YAML ou JSON) qui se trouve à côté de la branche de fonctionnalité. Cela facilite la différence des modifications lors de la revue de code et le stockage de l'artefact dans le contrôle de version aux côtés du code source. Lorsqu'un contrat change, la différence montre exactement quel champ a été ajouté, supprimé ou a vu son type modifié, ce qui déclenche une conversation entre les propriétaires du frontend et du backend avant que tout code soit écrit.

Génération de la spécification mock

Une fois que le contrat est écrit dans un fichier simple ou JSON, MockDeck le lit et produit trois artefacts : un document OpenAPI 3, une collection Postman et un fichier de routes brutes (JSON brut avec chemin, méthode et réponses d'exemple). Le résultat OpenAPI inclut les schémas exacts que vous avez définis, ainsi que des exemples générés automatiquement qui ressemblent à des données réelles - pensez à des noms qui suivent des modèles typiques, des nombres qui tombent dans des plages attendues et des chaînes qui atteignent des longueurs minimales et maximales. La collection Postman peut être importée directement dans le client API que vous utilisez pour les tests manuels, et le fichier de routes brutes peut être servi par un serveur mock léger (comme Mirage JS ou json-server) avec zero configuration.

L'étape de génération est déterministe : étant donné le même fichier de contrat, vous obtenez toujours le même résultat mock. Cela vous permet de consigner les artefacts générés à votre référentiel si vous voulez un mock statique, ou vous pouvez exécuter MockDeck comme partie de votre démarrage du serveur de développement pour garder le mock en mémoire. Puisque le mock est dérivé du contrat, vous n'avez jamais à maintenir deux sources de vérité distinctes ; tout changement dans le contrat se propage automatiquement au mock lors de la régénération.

MockDeck ajoute également quelques fonctionnalités de convenance prêtes à l'emploi : il définit les en-têtes CORS appropriés pour le développement local, il ajoute un curseur de latence pour simuler le délai réseau, et il enregistre chaque demande dans la console pour que vous puissiez vérifier que le frontend atteint le point de terminaison attendu avec la charge utile correcte.

Intégration de mocks dans le flux de travail frontend

Dans mes projets, j'ajoute un script de démarrage qui lance le serveur de mocks avant le serveur de développement frontend. Le script lit le dossier de contrat, exécute MockDeck pour produire le fichier de routes, puis démarre un serveur node-express qui sert ces routes sur http://localhost:3001. Le proxy frontend est configuré pour transférer toutes les requêtes /api vers ce port, de sorte que la base de code voit une couche API fluide sans aucun changement dans le code source.

- Ajoutez un répertoire de contrats à la racine du référentiel. - Pour chaque point de terminaison, créez un fichier.yaml qui suit la structure décrite précédemment. - Ajoutez un script start:mock dans package.json qui exécute mockdeck build./contracts --out./mock, puis node./mock/server.js. - Configurez le serveur de développement frontend (par exemple, Vite, CRA) pour proxy /api vers http://localhost:3001. - Exécutez npm run start:mock dans un terminal et npm run dev dans un autre.

Lorsqu'un contrat change, vous n'avez besoin de redémarrer que le script de mocks ; le frontend adopte le nouveau comportement instantanément car le proxy transfère vers le serveur de mocks mis à jour. Cette boucle serrée encourage les développeurs à traiter le contrat comme le premier artefact qu'ils modifient lorsqu'une fonction évolue.

J'écris également un test Jest simple qui importe le document OpenAPI généré et vérifie que la forme de la requête correspond aux appels d'API de la composante.

Versionning des contrats et gestion du décalage

Les contrats évoluent tout comme le code. Je traite chaque fichier de contrat comme une version aux côtés de la branche de fonctionnalité. Lorsqu'une modification de rupture est nécessaire - comme la renommage d'un champ ou la modification d'un indicateur requis - je crée une nouvelle version du contrat (par exemple, v2/commande-create.yaml) et je met à jour le générateur OpenAPI pour inclure un bloc de serveurs qui pointe vers le chemin versionné. Le serveur de simulation sert alors les deux versions simultanément, permettant au frontend de choisir la nouvelle version du contrat en modifiant l'URL de base.

Pour détecter le décalage, je lance un travail nocturne qui compare la spécification OpenAPI du backend en direct (générée à partir du code réel) avec la spécification générée par le contrat. Toute différence est signalée comme un avertissement dans notre tableau de bord CI. Cette approche a détecté des cas où un développeur backend a ajouté un nouveau champ facultatif sans mettre à jour le contrat, ce qui aurait provoqué des erreurs de validation frontend en production.

Lorsqu'un contrat est déprécié, j'ajoute une date de fin de vie dans un commentaire en haut du fichier et je garde la simulation active pendant deux semaines après la date pour donner le temps aux équipes de migrer. Après cette période, le serveur de simulation renvoie une réponse 410 Gone avec une brève explication, rendant le cycle de vie du contrat explicite.

Test de contrat comme filet de sécurité

Le test de contrat vérifie que le mock et la mise en œuvre réelle parlent le même langage. J'utilise un outil comme Pact ou Dredd pour exécuter le contrat contre le serveur mock et le backend de staging. La suite de tests envoie chaque requête définie dans le contrat, vérifie le code de statut de réponse, les en-têtes et le schéma de corps, et enregistre les déviations.

L'intégration de cette étape dans le flux de demande de tirage signifie qu'un changement dans le backend qui casse le contrat fera échouer la construction avant qu'il n'atteigne le master. De même, si un développeur frontend met à jour la charge utile de la requête sans mettre à jour le contrat, le test échouera car le mock ne reconnaîtra pas la nouvelle forme.

Pour les équipes axées sur la sécurité, j'exécute également le contrat contre les directives de l'OWASP pour m'assurer que les mocks générés n'exposent pas involontairement des modèles dangereux tels que le téléchargement de fichiers non restreint ou la fuite excessive de données.

Ce que ce n'est pas

Cette approche ne garantit pas que le backend sera livré à temps. Un mock ne peut simuler que le comportement ; il ne peut pas remplacer la logique métier réelle, les interactions avec la base de données ou les appels de services externes que la mise en œuvre réelle effectuera.

Ce n'est pas un substitut à 100 % aux tests de bout en bout. Vous devez toujours vérifier que le système intégré fonctionne correctement avec des données authentiques, des caractéristiques de performances et des conditions d'erreur qui n'apparaissent qu'en charge.

Cela n'élimine pas la nécessité d'une communication claire entre les équipes. Le contrat est un outil pour faciliter la discussion, mais il ne remplace pas les synchronisations régulières, les examens de conception ou la documentation partagée.

Enfin, l'utilisation de mocks contractuels en premier lieu ne rendra pas votre produit immunisé contre les erreurs de spécification. Si le contrat lui-même est ambigu ou incomplet, le mock mettra fidèlement en œuvre ces lacunes, et le frontend sera construit sur une hypothèse erronée. Traitez le contrat comme un document vivant qui évolue avec les commentaires des deux côtés.

Références

- https://owasp.org/www-project-top-10-for-large-language-model-applications

- https://www.nist.gov/itl/ai-risk-management-framework

Questions fréquentes

S'agit-il d'un serveur mock en cours d'exécution?

Non. MockDeck génère la spécification d'API mock — OpenAPI 3, Postman ou routes brutes. Le service est une étape distincte.

Puis-il appeler notre backend réel?

Non. Il ne proxy ni n'exécute votre backend ; la sortie est une spécification et des réponses d'exemple.

Quels formats produit-il?

OpenAPI 3, collections Postman ou routes brutes.

Pourquoi se soucier des réponses d'erreur dans un mock?

Parce que c'est là que le code frontend se casse généralement. Un mock qui ne retourne que des 200 cache les états que vous avez le plus besoin de gérer.

Combien les données d'exemple sont-elles réalistes?

Elles sont générées pour ressembler à des charges utiles réelles, ce qui suffit pour détecter les bogues de formatage et d'état vide précocement. Ce ne sont pas des données de production.

Valide-t-il notre API existante contre le contrat?

Non. Les tests de contrat et la validation sont des outils distincts.

Oui, MockDeck prend en compte ces exigences pour garantir la sécurité et la conformité de vos API.

Références

- Spécification OpenAPI - Schéma JSON

Essayez le produit : MockDeck

2026-09-20 · sources primaires uniquement · pas de métriques de trafic fabriquées · prise de décision uniquement

Articles liés

- Serveurs Mock vs exemples OpenAPI - Explorez la matrice complète des sujets de micro-SaaS IA →