Une application TypeScript peut compiler sans erreur puis tomber en panne lorsqu’une API renvoie une valeur inattendue. Le type déclaré décrit ce que le développeur attend ; il ne prouve pas que les données reçues respectent ce contrat. La frontière entre réseau et logique métier doit donc être contrôlée explicitement. Cette validation protège aussi contre des erreurs plus discrètes qu’un plantage : montant mal interprété, date invalide ou statut inconnu traité comme un succès.
Distinguer vérification du code et vérification des données
Le manuel TypeScript explique le rôle de la vérification statique et le fait que les annotations de type sont retirées lors de la production du JavaScript. Une assertion de type ne transforme donc pas une réponse réseau en objet valide. Elle informe le compilateur de l’hypothèse retenue, sans ajouter nécessairement un contrôle à l’exécution.
Imaginez une API de livraison dont votre code attend un délai numérique. Un changement chez le fournisseur introduit la chaîne « sur demande » pour certains produits. Le compilateur ne consulte pas les futures réponses du fournisseur. Si vous traitez la valeur comme un nombre sans la contrôler, le résultat peut devenir incohérent. Le problème se situe à l’entrée des données, même si ses effets apparaissent beaucoup plus loin dans l’interface.
Définir ce qui est inconnu à la frontière
Considérez la réponse externe comme inconnue tant qu’elle n’a pas été examinée. Vérifiez d’abord sa structure générale, puis les champs nécessaires à votre usage. Une réponse HTTP réussie peut contenir un corps vide, une erreur applicative ou un objet partiel. Séparez ces situations dans le contrat de votre adaptateur réseau pour que le reste de l’application ne les découvre pas au hasard.
Cette approche vaut pour les API, mais aussi pour les formulaires, fichiers importés, paramètres d’URL et messages reçus d’autres systèmes. La confiance ne doit pas dépendre uniquement de l’origine supposée. Un système interne peut changer de version ou transmettre un enregistrement ancien. La validation permet de reconnaître ce qui est utilisable et de décider comment traiter ce qui ne l’est pas.
Valider les règles utiles au métier
Un contrôle de type primitif est nécessaire mais parfois insuffisant. Un montant peut être numérique tout en ayant une unité incorrecte. Une date peut être une chaîne bien formée sans correspondre à une échéance acceptable. Définissez les propriétés nécessaires : format, plage, présence, unité et cohérence entre champs. Ne rendez pas obligatoire une donnée que votre fournisseur ne garantit pas simplement pour faciliter un composant.
Dans un exemple fictif, une application reçoit une quantité disponible et un statut de vente. Elle doit décider quoi faire si la quantité est absente, négative ou accompagnée d’un statut inconnu. Le bon comportement peut être de masquer la disponibilité et de proposer une vérification, plutôt que d’afficher zéro. Cette décision influence l’expérience client ; elle doit être discutée avec le métier et documentée dans la validation.
Éviter les conversions silencieuses
Convertir automatiquement toutes les chaînes en nombres peut faire disparaître des erreurs de source. Une chaîne vide peut devenir une valeur trompeuse selon l’opération utilisée. Définissez les conversions autorisées et conservez une trace des cas rejetés. Lorsque la source accepte plusieurs formats, traitez-les explicitement. Le lecteur du code doit comprendre pourquoi une conversion existe et quelles entrées elle refuse.
Créer un modèle interne stable
Après validation, transformez la réponse en un modèle adapté à votre application. Vous pouvez renommer les champs, normaliser une unité et représenter les absences de façon cohérente. Cette couche d’adaptation évite de répandre les particularités du fournisseur dans tous les composants. Si son format change, le travail se concentre sur une frontière identifiable au lieu de nécessiter une recherche dans toute l’interface.
Ne conservez pas inutilement l’intégralité du corps externe dans les données utilisées par l’application. Sélectionnez ce qui est nécessaire et limitez ce qui apparaît dans les logs. Une erreur de validation peut indiquer le champ et la règle concernés sans recopier un dossier client entier. Le diagnostic reste utile tout en réduisant l’exposition de données qui n’aident pas à résoudre le problème.
Représenter clairement succès et échec
Le guide TypeScript sur le rétrécissement des types décrit notamment les unions discriminées. Elles permettent de distinguer plusieurs formes de résultat par une propriété commune. Une application peut ainsi représenter un succès, une donnée absente ou une erreur de validation avec des informations propres à chaque cas, au lieu d’un objet rempli de propriétés optionnelles ambiguës.
Ce modèle aide l’interface à proposer une réponse adaptée. Une absence de résultat peut afficher un état vide ; une panne réseau peut inviter à réessayer ; une réponse invalide peut déclencher une alerte technique. Ne présentez pas toutes ces situations comme « aucun élément trouvé ». L’utilisateur risquerait de croire que ses données n’existent plus alors que le système n’a simplement pas réussi à les lire.
Tester les variations plausibles de la réponse
Préparez des exemples de réponse valide, champ absent, valeur nulle, mauvais type, statut inconnu et tableau vide. Ajoutez une propriété supplémentaire pour vérifier la politique retenue face aux évolutions compatibles. Le contrat peut autoriser des champs inconnus tout en exigeant ceux nécessaires à l’application. Refuser toute nouveauté n’est pas toujours souhaitable ; accepter toute absence ne l’est pas davantage.
Les tests doivent vérifier le résultat métier ou l’erreur produite, et pas seulement appeler le validateur sans assertion précise. Conservez des exemples anonymisés issus des incidents réels quand cela est possible. Ils rendent les régressions reproductibles. Si vous utilisez une bibliothèque de validation, vérifiez sa configuration dans votre version et évitez de supposer que son comportement par défaut correspond à vos règles.
Faire évoluer le contrat sans rupture aveugle
Attribuez un propriétaire à chaque contrat externe et indiquez les usages qui en dépendent. Lorsqu’une erreur apparaît, cette personne peut décider si le nouveau format est acceptable ou si le fournisseur doit corriger sa réponse. La décision ne doit pas se limiter à ajouter une assertion pour faire disparaître une erreur du compilateur : elle doit préserver le sens des données utilisées.
Lorsqu’un fournisseur annonce un changement, comparez son nouveau format aux champs réellement utilisés. Préparez la compatibilité nécessaire, déployez les contrôles puis suivez les rejets. Une validation utile rend les écarts visibles assez tôt pour agir. Elle ne doit pas devenir une boîte noire qui renvoie simplement une erreur générale sans possibilité de comprendre le changement rencontré.
Notre expertise TypeScript aide à clarifier les contrats de données et à fiabiliser les évolutions. Pour examiner une intégration, apportez la forme attendue d’une réponse, un exemple anonymisé et les comportements souhaités en cas d’écart. Nous pourrons placer les contrôles à la bonne frontière et simplifier le modèle utilisé par votre application.
Pour approfondir : Python : contrôler un CSV avant de l’importer dans un outil métier.
Pour approfondir : React : concevoir les états d’un formulaire qui ne perd pas la saisie.
