Notes pratiques : Maintenir la synchronisation des types frontend et backend avec TypeScript
Guide pratique pas à pas : Maintenir les types frontend et backend en synchronisation avec TypeScript – contrats, vérifications et emplacements de code prêts à l’emploi pour les équipes qui utilisent ce modèle.
Sources: Keeping Frontend and Backend Types in Sync with Typescript Magic
Utilisez ceci comme une version révisée destinée aux opérateurs des idées présentées dans « Maintenir les types frontend et backend en synchronisation grâce aux fonctionnalités de TypeScript » : étapes claires, emplacements de code ordonnés, ainsi que des notes de récupération qui survivent au transfert de responsabilités.
Le bug sans trace d’erreur
Ce type de bug fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un enregistrement exemplaire, un cas d’échec et les notes de réversion avant d’élargir le périmètre. Enregistrez également les temps d’exécution ainsi que le coût en tokens ou requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des factures inattendues lorsque le processus passe d’une démonstration à des environnements partagés. Gardez les opérations de rendu peu coûteuses et reportez les calculs coûteux à l’après-mémoisation, uniquement après avoir effectué des mesures. Une mémoisation prématurée peut cacher des bugs liés à des props obsolètes.
// backend/src/topics/topics.service.ts
async findAll(): Promise<TopicRow[]> {
return this.prisma.topic.findMany({ select: TOPIC_SELECT });
}
// frontend/src/types.ts
export interface TopicRow {
id: string;
code: string;
requiresKey: boolean;
// ...
}
Pourquoi cela est devenu urgent
Aborder l’étape « Pourquoi c’est urgent » de la meilleure manière consiste à le traiter comme une surface mesurable. Capturez un transcript exemplaire, un cas d’échec et la note de réversion avant d’élargir le périmètre. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Maintenez le traitement de rendu peu coûteux et reportez les calculs coûteux à la mise en mémoire uniquement après avoir effectué des mesures. Une mise en mémoire prématurée peut cacher des erreurs liées à des données obsolètes.
L’idée
La phase d’idéation fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple réussi, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez en même temps le parcours optimal et celui de récupération. Les tentatives répétées, les contrôles humains et le traitement des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure. Gardez les opérations de rendu peu coûteuses et reportez les calculs coûteux à l’après-mémoisation, uniquement après avoir effectué des mesures. Une mémoisation prématurée peut cacher des bugs liés à des données obsolètes.
// backend/contract/assert.ts
/** The wire shape of a server value: JSON.stringify turns Date into string. */
export type Jsonify<T> = T extends Date
? string
: T extends (infer U)[]
? Jsonify<U>[]
: T extends object
? { [K in keyof T]: Jsonify<T[K]> }
: T;
/** Invariant (not merely assignable) equality - catches widened optionals. */
export type Equal<A, B> =
(<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
? true
: false;
export type Expect<T extends true> = T;
/** The element type of a service method that resolves to an array. */
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
/** The resolved wire shape of a service method. */
export type ResultOf<T> = Jsonify<Awaited<T>>;
/** The row type of a paginated `{ rows, total }` service method. */
export type PagedRowOf<T> =
Jsonify<Awaited<T>> extends { rows: (infer U)[] } ? U : never;
// backend/contract/api-contract.ts
import type { Equal, Expect, PagedRowOf, RowOf } from './assert';
import type { TopicsService } from '../src/topics/topics.service';
import type { ContactRequestsService } from '../src/contact-requests/contact-requests.service';
import type { TopicRow, ContactRequestRow } from '../../frontend/src/types';
// GET /topics
export type _Topics = Expect<
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
// GET /contact-requests (paginated)
export type _ContactRequests = Expect<
Equal<PagedRowOf<ReturnType<ContactRequestsService['findAll']>>, ContactRequestRow>
>;
La magie de la saisie, expliquée
La méthode de « magie de la saisie » fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple réussi, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Maintenez les opérations de rendu peu coûteuses et reportez les calculs onéreux à la mise en mémoire uniquement après avoir effectué des mesures. Une mise en mémoire prématurée peut cacher des bugs liés à des données obsolètes.
export type _Topics = Expect<
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
type Equal<A, B> = A extends B ? (B extends A ? true : false) : false; // too loose
(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
Connectez-le à la méthode, pas à la requête
La phase de connexion à l’interface fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définites des critères de succès et refusez toute mise en œuvre partielle silencieuse. Maintenez les coûts de rendu faibles et reportez les calculs coûteux à la mise en mémoire uniquement après avoir effectué des mesures. Une mise en mémoire prématurée peut cacher des erreurs liées à des données obsolètes. La phase de connexion à l’interface fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du système.
// Wrong: misses everything the method does after the query
Equal<Jsonify<TopicSelectResult>, TopicRow>
// Right: whatever the method actually resolves to
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
Faire en sorte qu’il fonctionne
Pour l’étape « Making it run », définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie du produit, et non d’une mise en forme ultérieure. Placez l’état au même endroit que le composant responsable de la mutation. Mettre tout dans un stockage global rend les erreurs de synchronisation plus difficiles à détecter.
// backend/tsconfig.contract.json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"noEmit": true,
"rootDir": "..", // program spans both packages
"module": "preserve",
"moduleResolution": "bundler" // resolve the way the frontend's bundler does
},
"include": ["src/**/*", "contract/**/*", "../frontend/src/types.ts"]
}
{ "scripts": { "check:contract": "tsc -p tsconfig.contract.json" } }
Lecture d’une erreur
Pour l’étape de détection d’échec lors de la lecture, définissez les entrées, le responsable de l’étape et les critères de sortie avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Placez l’état au même endroit que le composant qui gère la mutation. Mettre tout dans un stockage global rend les erreurs de synchronisation plus difficiles à détecter.
type P1 = A extends B ? true : false; // false => server is narrower / has extra
type P2 = B extends A ? true : false; // false => frontend is wider
type Extra = Exclude<keyof A, keyof B>; // fields the server sends, frontend lacks
type Missing = Exclude<keyof B, keyof A>; // fields the frontend invented
Quel en est le coût, et où cela ne fonctionne pas
Pour la section « Ce que cela coûte » et la phase correspondante, définissez les entrées, le responsable de l’étape ainsi que les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définites des vérifications de succès et refusez les terminaisons partielles silencieuses. Placez l’état au même endroit que le composant responsable de la mutation. Mettre tout dans un stockage global rend les erreurs liées aux délais plus difficiles à détecter. Pour la section « Ce que cela coûte » et la phase correspondante, définissez les entrées, le responsable de l’étape ainsi que les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans avoir à lire l’ensemble du système.
L’essentiel
Lors de l’étape « L’essentiel », notez d’abord les conditions du contrat : entrées requises, signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code.
Liste de contrôle opérationnelle
Lors de l’étape « Liste de contrôle opérationnelle », notez d’abord les conditions du contrat : entrées requises, signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code.
Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les surprises financières lorsque le processus passe de la démonstration aux environnements partagés.
Considérez les effets comme une synchronisation avec le monde extérieur, et non comme un substitut aux valeurs dérivées lors du rendu.
Fixez les versions des dépendances et enregistrez le résumé de l’image utilisée pour la démonstration. La reproductibilité vaut mieux que les connaissances propres à un groupe.
Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les administrateurs peuvent auditer sans devoir lire l’ensemble du schéma.
Considérez les effets comme une synchronisation avec le monde extérieur, et non comme un substitut aux valeurs dérivées lors du rendu.
Au préalable de promouvoir la pile technologique, figez les versions, capturez un enregistrement complet du chemin critique et confirmez les étapes de rollback. Les environnements partagés nécessitent des limites de vitesse, des vérifications d’attribution et un responsable clair pour la rotation des secrets. Préférez une fiabilité banale à des démonstrations ingénieuses ponctuelles.
Note de lot pour 99a16b87e27d : ne pas inclure les clés du fournisseur dans le répertoire, fixer un plafond pour les tokens par session, et stocker les transcriptions à côté des fichiers d’évaluation afin que les remplacements ultérieurs de modèles restent comparables.