YamlBox

Générateurs de codes · 6 minutes de lecture

JSON à TypeScript : types qui correspondent à la réalité

Le moyen le plus rapide d'obtenir des types TypeScript corrects pour un API est de les générer à partir d'une réponse que le API a réellement renvoyée. Les interfaces écrites à la main décrivent la charge utile que vous attendez ; une conversion JSON en TypeScript décrit la charge utile dont vous disposez, et l'écart entre ces deux est l'endroit où l'exécution se bloque.

Mis à jour

Pourquoi les caractères manuscrits dérivent

Les interfaces écrites à partir de la documentation ou de la mémoire ont tendance à être optimistes. Ils marquent tout ce qui est présent, supposent qu'un champ nullable est toujours là et manquent discrètement l'objet imbriqué qui n'apparaît que sur les comptes premium. TypeScript applique ensuite une forme que le serveur n'a jamais promise, et les `undefined` premiers apparaissent en production plutôt qu'au moment de la compilation. Générer à partir de réponses réelles inverse le processus : le compilateur vérifie une forme observée au lieu d'une forme espérée.

Lecture du fichier généré

Une conversion utile nomme les objets imbriqués d'après leurs clés, conserve les types d'éléments du tableau intacts et exprime explicitement l'incertitude. Surveillez les trois marqueurs qui portent toute la signification :

                export interface Order {
  id: string;
  total: number;
  coupon?: string;            // absent in some responses
  shippedAt: string | null;   // present but null until shipped
  items: Array<OrderItem>;
}

La différence entre `coupon?: string` et `shippedAt: string | null` n’est pas esthétique. Facultatif signifie que la clé peut être manquante ; null signifie que la clé est là sans valeur. Les API font les deux, souvent dans la même charge utile, et leur fusion envoie une vérification nulle dans le code qui supposait une chaîne.

Utiliser plus d'un échantillon

Une seule réponse marque tout ce qui est requis. Collez deux ou trois réponses — idéalement une d'un compte vide et une d'un compte complet — et les clés facultatives se révèlent : un champ manquant dans tout échantillon devient `?`, et un champ parfois nul devient une union avec `null`. Il s'agit de la mise à niveau d'exactitude la moins chère disponible, et c'est la raison pour laquelle les types générés doivent être régénérés lorsque le API change plutôt que d'être écrits une seule fois.

Ne laissez jamais une interface générée être la seule description de votre API. Conservez un test de schéma ou de contrat à côté, afin qu'un changement de serveur fasse échouer une construction plutôt qu'une session utilisateur.

Où appartiennent les types

  • Un dossier `types/` ou `api/` dédié, non dispersé dans les composants.
  • Un fichier par point de terminaison ou par ressource, avec un commentaire nommant le point de terminaison et la date à laquelle il a été capturé.
  • Une note de régénération : quel appel a produit la charge utile, afin que la personne suivante puisse la répéter.
  • Une exportation consommée à la fois par la couche de récupération et par les composants, donc une modification interrompt exactement un endroit.

Activer le mode strict

Les types générés ne sont payants qu'avec `strict` activé, car c'est ce qui fait d'une clé facultative une véritable erreur lorsqu'elle est accessible directement. Associez les interfaces générées avec `unknown` à la limite de récupération et rétrécissez avant utilisation : `JSON.parse` renvoie `any`, donc un cast vers l'interface générée devrait être le point où vous avez validé, pas là où vous l'espérez.

Générez à partir de charges utiles que vous ne téléchargeriez pas

Les réponses API sont les JSON les plus sensibles que la plupart des développeurs gèrent : données de compte, commandes, jetons. L'exécution de la conversion JSON en TypeScript dans le navigateur signifie que la charge utile est analysée localement et n'est jamais transmise, vous pouvez donc coller une vraie réponse sans la rédiger au préalable, et l'outil continue de fonctionner hors ligne.

JSON à TypeScript — questions fréquemment posées

Comment rendre un champ généré facultatif ?

Incluez un deuxième échantillon où cette clé est absente et régénérez-le — le convertisseur émet alors `key?: type`. L'inférence ne rend un champ facultatif que lorsqu'il contient une preuve d'absence, c'est pourquoi un échantillon n'est jamais suffisant pour un contrat.

Dois-je utiliser interface ou type pour les types JSON générés ?

Les deux fonctionnent pour les formes d’objets ; les interfaces sont classiques pour les modèles API car elles peuvent être étendues et produire des messages d'erreur plus clairs. Le choix important est le mode `strict`, et non le mot-clé que vous choisissez.

Puis-je convertir JSON en TypeScript sans envoyer de données à un serveur ?

Oui. Le convertisseur de ce site génère les interfaces dans la page elle-même, de sorte que la réponse ne quitte jamais votre navigateur et que la conversion continue de fonctionner lorsque le réseau est désactivé.

Outils mentionnés dans cet article

JSON à emporter Générez des structures Go avec des balises json et une omitempty à partir de JSON. Schéma JSON à JSON Déduisez un schéma JSON prêt pour la validation à partir de n’importe quel exemple de charge utile. JSON Formateur Imprimez joliment, réduisez et validez JSON avec les emplacements exacts des erreurs. JSON à YAML Générez un YAML lisible à partir de JSON avec des contrôles d'indentation et de guillemets.

Parcourez la liste complète des 19 outils

Plus d'articles à lire

Tous les 19 messages →