Migration vers Huma v2 avec parité de 100 %
Migré l'API HTTP de Fiber vers Huma v2 — 649 chemins et 760
opérations — puis atteint et maintenu une correspondance de 100 %
entre les routes enregistrées par le serveur et la description
OpenAPI publiée.
2025

Situation. L'API a commencé sur Fiber, avec une validation des
requêtes écrite à la main, point de terminaison par point de
terminaison. Cela convient lorsqu'il n'y en a qu'une poignée. Ce
n'est plus le cas lorsque le périmètre grandit : cette validation
artisanale devient une charge de maintenance, et de petites
incohérences apparaissent, car les contrôles de chaque point de
terminaison constituent leur propre cas particulier. Il n'existait
par ailleurs aucune description unique de la structure de l'API.

Tâche. L'objectif était que la validation découle des types plutôt
que de contrôles écrits à la main, avec un véritable contrat
décrivant l'API — sans s'arrêter pour une réécriture globale d'un
seul coup.

Action. La couche HTTP est passée à Huma v2 au‑dessus de Fiber,
conservant ainsi le moteur d'exécution existant. Chaque point de
terminaison reçoit des structures d'entrée et de sortie, à partir
desquelles Huma génère la validation des requêtes et la modélisation
des réponses. Une description OpenAPI en découle sans travail
supplémentaire, ce qui permet à la documentation de suivre le code
au lieu de dépérir dans un wiki. Tout nouvel élément a été écrit
avec Huma et les routes existantes migrées, avec exactement deux
points de terminaison restant directement sur Fiber — ceux des
WebSocket, où l'accès au socket est réellement nécessaire et où le
modèle requête/réponse de Huma ne convient pas. L'ensemble a atteint
649 chemins portant 760 opérations, avec un contrôle en CI comparant
les routes réellement enregistrées par le serveur à celles annoncées
dans la description OpenAPI. La correspondance est de 100 % et le
reste, car une route non décrite fait échouer la compilation.

Résultat. Les nouveaux points de terminaison bénéficient d'une
validation et d'une documentation à jour sans travail
supplémentaire, et toute une catégorie de défauts de traitement des
requêtes — du type « oh, ce champ n'a pas été vérifié ici » — a
disparu. Avec 760 opérations, la description est le seul moyen
pratique de consulter l'API, si bien que la garantie de son
exhaustivité compte davantage qu'à cinquante. Le contrat typé a
rendu l'API plus sûre à modifier et plus facile à transmettre, car
les types indiquent ce qu'attend un point de terminaison.

Catégories:
1Architecture de plateformes	/fr/categories/platform-architecture/	advisory.engineer.company	70
1Ingénierie backend	/fr/categories/backend/	advisory.engineer.company	70
1API et intégration	/fr/categories/api/	advisory.engineer.company	70
1Migrations et modernisation	/fr/categories/migration/	advisory.engineer.company	70
1Tests et assurance qualité	/fr/categories/testing/	advisory.engineer.company	70
1Documentation	/fr/categories/documentation/	advisory.engineer.company	70

Prestations:
1Architecture de plateformes et de solutions	/fr/services/platform-architecture/	advisory.engineer.company	70
1Développement backend et API	/fr/services/backend-development/	advisory.engineer.company	70
1Outils pour agents d'IA et serveurs MCP	/fr/services/ai-tools/	advisory.engineer.company	70
1Documentation technique	/fr/services/technical-documentation/	advisory.engineer.company	70

hCette page sur le Web	URL:https://advisory.engineer.company/fr/portfolio/migrated-the-api-to-huma-v2-at-100-parity/	advisory.engineer.company	70
