Aller au contenu
English

Recherche rapide dans un jeu de données public

  • Étude de cas 1
  • 150 min
  • Facultative · 1 étude de cas requise pour le certificat

Où nous en sommes

Cette étude de cas applique les pages sur le serveur, la correction de la course entre réponses et la liste virtuelle des modules 3 et 5 à 9 051 vrais aéroports. Vous créez une page de recherche sur une petite API, mesurez chaque étape avec une seule mesure et décidez à partir des chiffres.

Ce que vous saurez faire

Créez une page de recherche parmi 9 051 aéroports réels, servis par une petite API que vous écrivez. Mesurez d’abord un prototype rapide. Déplacez ensuite la recherche vers le serveur. Corrigez la course entre réponses périmées que cela entraîne, affichez seulement les lignes visibles et divisez le code. Mesurez chaque étape avec une seule mesure, puis décidez à partir des chiffres.

Étude de casPièce de portfolio

Durée
Environ 2,5 h
S’exécute dans
VS Code, Node.js 24, Chromium (Playwright)
Compétences utilisées
  • Pagination et filtrage côté serveur
  • La course entre réponses périmées
  • Clés et annulation avec TanStack Query
  • Listes virtuelles
  • Division du code avec lazy()
  • Mesurer avec Playwright
  • Une comparaison équitable avec une seule mesure

Décompressez le projet de départ, ouvrez le dossier dans VS Code et suivez les étapes ci-dessous. Elles commencent par l’installation des paquets du projet avec npm.

Le projet de départ est un prototype fonctionnel : une petite API en Node.js sans paquets, et une page React. Le projet terminé présente le résultat, pour vous aider si vous bloquez. Le code est sous licence MIT; les données et la carte du monde sont dans le domaine public.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 150 minutes

Ce que vous devez savoir

Cette étude de cas applique tout le cours à un projet autre que le bureau des tickets. Elle s’appuie surtout sur Rendu et effets (la course et le nettoyage), Cycle de vie d’une requête (clés et annulation), Pagination et formulaires (pages avec un curseur), Mesurer dans le navigateur et Charger moins de travail (premières lignes, profil semblable à un téléphone, listes virtuelles, division du code).

Ce qu’il vous faut sur votre ordinateur

  • Node.js 24 (LTS), npm, VS Code et curl, comme dans Installer le bureau des tickets.
  • Une connexion Internet pour un npm install (environ 130 Mo) et pour Chromium de Playwright (environ 100 Mo, une fois).
  • Environ 2,5 h, dont environ 20 minutes de mesures qui occupent votre ordinateur.

Testé sur macOS (Apple M4, 16 Go) avec Node.js 24.18.0 et Chromium 156. Sur Windows (PowerShell) et Linux, les commandes npm et node sont les mêmes; elles n’ont pas été exécutées. Tous les temps de cette page viennent du portable de l’équipe du cours, pendant que d’autres tâches s’exécutaient. Vos temps seront différents; ce sont les écarts qui comptent.

Brightway Travel est une petite agence de voyages. Nadia dirige son équipe téléphonique. Pendant qu’un client parle, un agent cherche un aéroport : « Orly est à Paris? » « Quel aéroport correspond à LCY? » Leo, le seul développeur de l’agence, a créé une page de recherche en un après-midi. Elle fonctionne, mais elle semble lourde. La même recherche sera bientôt sur le site de l’agence, où la plupart des visiteurs utilisent un téléphone. Les personnes et l’agence sont inventées; les aéroports sont réels.

La règle de Nadia est simple : « Quand je tape, je veux les lignes pour ce que j’ai tapé. Pas pour ce que j’ai tapé il y a une seconde. »

L’objectif. Une personne ouvre la page et tape un mot. La page doit afficher les bonnes lignes, jamais celles d’une recherche précédente. Elle doit le faire rapidement, sur un ordinateur de bureau et sur un téléphone. Une seule mesure départage les versions : le temps entre l’ouverture de la page et l’affichage stable des lignes correspondant au mot tapé. Quatre autres chiffres l’expliquent : les premières lignes, le temps après la dernière touche, les éléments de la page et le temps entre un clic sur une ligne et ses détails.

Deux rangées. Projet de départ : la page s'ouvre avec un fichier JavaScript de 101 ko compressé avec gzip, incluant la carte. Elle demande GET /v1/airports/all pour 9 051 aéroports (380 ko compressés avec gzip, en rouge). Elle les recherche dans le navigateur à chaque frappe et affiche toutes les correspondances : jusqu'à 54 338 éléments (en rouge). Projet terminé : la page s'ouvre avec un premier fichier de 88 ko compressé avec gzip. Elle demande GET /v1/airports?q=…&limit=50 pour une page (environ 3 ko compressés avec gzip, en vert). TanStack Query conserve une clé par recherche et ferme les anciennes requêtes. Une liste virtuelle affiche seulement les lignes visibles, soit environ 140 éléments (en vert). Après les premières lignes, les détails et la carte (31 ko compressés avec gzip) sont chargés.
Le projet de départ télécharge tout et affiche tout. La page terminée demande au serveur une page à la fois et affiche seulement ce qui est visible.
Description textuelle du diagramme

À gauche, le projet de départ demande les 9 051 aéroports, les recherche dans le navigateur et affiche toutes les correspondances. À droite, le serveur effectue la recherche et la pagination, et TanStack Query sépare chaque recherche. Une liste virtuelle affiche seulement les lignes visibles, et le code des détails arrive après les premières lignes.

Partie Ce qui change Mesure après cette étape
1 rien : la mesure et les chiffres du projet de départ oui
2 l’API recherche et pagine; la page l’interroge à chaque frappe oui : la course
3 TanStack Query : une clé par recherche, les anciennes requêtes fermées oui
4 une liste virtuelle qui charge la page suivante près de la fin oui
5 les détails et la carte dans leur propre fichier oui, deux fois
6 la comparaison équitable, avec l’autre approche bien réalisée –
7 une nouvelle saisie, de bout en bout oui

Les données viennent d’OurAirports, un site où des bénévoles tiennent une liste des aéroports du monde. Il précise : « Toutes les données sont dans le domaine public, sans garantie d’exactitude ni d’adéquation à un usage. » Le fichier complet contient 86 236 aéroports, héliports et terrains fermés, et il change chaque nuit.

Le projet conserve donc une copie fixe, data/airports.csv : les 9 051 lieux qui ne sont pas fermés et possèdent un code IATA, les trois lettres sur les bagages et les billets. Ce nombre de lignes suffit à ralentir l’affichage de chaque ligne, tout en permettant un téléchargement en une fois. DATASET.md est la fiche du jeu de données : la source, les modifications exactes, la somme de contrôle et les limites.

Une ligne représente un aéroport. La page utilise ces colonnes :

Colonne Signification Exemple
iata le code IATA, unique dans ce fichier ORY
name le nom de l’aéroport Paris-Orly Airport
type large_airport (grand aéroport), medium_airport (aéroport moyen), small_airport (petit aéroport), seaplane_base (base d’hydravions) ou heliport (héliport) large_airport
municipality, country la ville desservie et le pays Paris, France
latitude, longitude sa position, pour la carte 48.7233, 2.3794

Deux vérifications précèdent tout code. D’abord, le fichier doit être celui qui a servi aux chiffres de cette page; le projet vérifie donc son SHA-256. Ensuite, examinez ce qu’une courte recherche trouve. La recherche cherche les lettres tapées partout dans le code, le nom, la ville et le pays :

Recherche Aéroports correspondants
p 8 741
pa 1 680
par 160
pari 12
paris 8

Ce que cela nous apprend. Une lettre correspond à presque tout : presque chaque nom contient « Airport » (aéroport), et « Airport » contient un p. Un vrai moteur de recherche présente le même comportement : une recherche courte demande beaucoup plus de travail qu’une longue. Gardez ce tableau en tête pour la partie 2.

  1. Téléchargez le projet de départ depuis l’encadré en haut de cette page. Décompressez-le dans votre dossier de projets, par exemple ~/projects. Vous obtenez le dossier airport-search.

  2. Dans VS Code, choisissez File > Open Folder (fichier, ouvrir un dossier) et ouvrez airport-search. Ouvrez un terminal : Terminal > New Terminal (terminal, nouveau terminal).

  3. Installez les paquets, vérifiez les données et lancez les tests. Les commandes sont les mêmes sur macOS, Linux et Windows (PowerShell) :

    Fenêtre de terminal
    npm install
    npm run check:data
    npm test
    Output of the last two commands (parts)
    data/airports.csv: 9,051 airports, 883,430 bytes, SHA-256 15c19f931828… is correct
    …
    ℹ tests 6
    ℹ pass 6
    ℹ fail 0
    …
    Test Files 1 passed (1)
    Tests 2 passed (2)

    package.json contient déjà les paquets du projet terminé. Ce sont les versions du cours : React 19.3.0, TanStack Query 5.104.1, TanStack Virtual 3.14.15, Vite 8.3.4 et @playwright/test 1.64.0.

  4. Démarrez l’API dans ce terminal. --slow ajoute un temps serveur simulé, expliqué ci-dessous :

    Fenêtre de terminal
    npm run api -- --slow
    Sortie
    Airport search API on http://127.0.0.1:8200 (slow: 60 ms + 0.1 ms per match, simulated)
    Data: OurAirports (public domain), 9,051 airports with an IATA code.
  5. Ouvrez un deuxième terminal et démarrez la page avec npm run dev. Ouvrez http://localhost:5173/ et tapez paris.

Pourquoi simuler le temps serveur. Sur votre ordinateur, l’API cherche dans 9 051 lignes en moins de 10 ms. Un vrai serveur est plus lent, et son temps augmente avec le travail : davantage de correspondances à trier, compter et envoyer. --slow fait attendre chaque réponse 60 ms, plus 0,1 ms par aéroport correspondant. Ainsi, « p » attend 934 ms et « paris », 61 ms. C’est la règle de l’API simulée de billets du cours. Elle est construite, et chaque chiffre ci-dessous qui en dépend le précise. Tout le reste est réel : les données, le navigateur, les tailles et le rendu.

La page de Leo est courte. À l’ouverture, elle demande tous les aéroports en une fois. Ensuite, elle les recherche dans le navigateur à chaque frappe et affiche toutes les correspondances :

src/search/useAllAirports.ts (part)
useEffect(() => {
const controller = new AbortController();
allAirports(controller.signal).then(
(all) => setState({ status: 'success', airports: all.items, error: null }),
(error: Error) => {
if (!controller.signal.aborted) setState({ status: 'error', airports: null, error });
},
);
return () => controller.abort();
}, []);
src/search/ResultList.tsx (part)
const all = useAllAirports();
const airports = useMemo(() => (all.airports ? matchAirports(all.airports, filter) : []), [all.airports, filter]);
// … then every match is drawn: {airports.map((a) => <li key={a.iata}>…</li>)}

Cette conception a un vrai point fort : après le téléchargement, une recherche n’a pas besoin du réseau. Elle a aussi des coûts que personne n’a encore mesurés.

measure/measure.mjs suit la même structure que les scripts de mesure du cours. Il ouvre la page dans Chromium de Playwright, comme un nouveau visiteur avec un cache vide. Il lit deux marques laissées par la page :

  • performance.mark('search:first-rows') quand les premières lignes sont affichées, comme dans Mesurer dans le navigateur;
  • data-results-for="paris" sur la ligne de résultats : la recherche à laquelle répondent les lignes à l’écran. Un petit observateur dans la page note chaque changement et son heure.

Il comporte quatre groupes. Chacun utilise une connexion rapide et le profil du cours semblable à un téléphone : 150 ms aller-retour, 1,6 Mbit/s en téléchargement et un processeur quatre fois plus lent.

Groupe Ce qu’il fait Ce qu’il rapporte
open ouvre la page, 5 fois premières lignes, JavaScript et données téléchargés, éléments dans la page
type ouvre la page, attend, tape paris avec 120 ms entre les touches, 10 fois recherche correspondant aux lignes 3 s plus tard, temps après la dernière touche, tâches longues, requêtes envoyées et fermées avant la fin
session la seule mesure : ouvre la page et tape immédiatement paris, 5 fois temps entre l’ouverture et l’affichage stable des lignes pour paris
click charge 2 000 lignes, puis clique sur deux lignes, 3 fois éléments dans la page et temps entre chaque clic et ses détails à l’écran

Mesurez une version de production, jamais npm run dev : le mode développement ajoute des vérifications qui ralentissent beaucoup React. Installez Chromium une fois, puis construisez et servez la page :

Fenêtre de terminal
npx playwright install chromium
npm run build
npm run preview

Dans un troisième terminal, lancez les quatre groupes. L’API continue de fonctionner avec --slow :

Fenêtre de terminal
npm run measure -- open --label starter
npm run measure -- type --label starter
npm run measure -- session --label starter
npm run measure -- click --label starter

Chaque exécution affiche ses médianes et écrit results/starter-<group>.json avec chaque passage, la machine et la charge. Voici les exécutions de l’équipe du cours (médianes; temps serveur simulé) :

Mesure Rapide Semblable à un téléphone
Premières lignes 1,348 ms 5,224 ms
Données téléchargées 381 ko identique
JavaScript (un fichier) 101.4 ko compressés avec gzip identique
Éléments dans la page 54,338 identique
Saisie de paris : dernière touche jusqu’aux bonnes lignes 3.3 ms 8.7 ms
Saisie de paris : tâches longues pendant la saisie 263 ms 1,245 ms
Ouverture et saisie de paris : les bonnes lignes 1,041 ms 3,758 ms

Ce que cela nous apprend. Le prototype réussit sur un point et échoue sur trois autres.

  • Réussite : après le téléchargement, la recherche est instantanée. Les lignes pour paris étaient à l’écran 3.3 ms après la dernière touche. Aucun réseau ne peut faire mieux.
  • Échec : les premières lignes. Rien n’apparaît avant l’arrivée des 381 ko d’aéroports et l’affichage des 9 051 lignes. Avec le profil semblable à un téléphone, cela a pris 5.2 secondes.
  • Échec : la page se fige pendant la saisie. La première touche, p, correspond à 8 741 aéroports, et React affiche une ligne pour chacun. Une tâche longue occupe le navigateur plus de 50 ms, l’empêchant de répondre à une touche ou à un clic. Pendant la saisie de paris, les tâches longues ont totalisé 263 ms, et 1,245 ms avec le processeur semblable à celui d’un téléphone.
  • Échec : la page est énorme. Elle contient 54,338 éléments pour un écran qui affiche environ dix lignes.

Une bibliothèque ne vous remet pas toutes les fiches du catalogue. Vous demandez « Paris », et la bibliothécaire vous donne les premières fiches, avec un signet pour les suivantes. Pagination et formulaires a créé cela pour la liste de billets : le serveur filtre et pagine. La page demande une page de 50, avec un curseur pour la suivante.

  1. Ajoutez search() et page() à api/airports.mjs. search() conserve les aéroports dont le code, le nom, la ville ou le pays contient les mots, puis classe les meilleurs en premier. Le code lui-même vient en premier, puis les noms et les villes qui commencent par les mots. Le fichier src/search/match.ts du projet de départ contient déjà les mêmes règles. page() extrait une page et crée le curseur :

    api/airports.mjs (part)
    export function page(matches, limit, after = '') {
    const start = after ? Number.parseInt(Buffer.from(after, 'base64url').toString(), 10) : 0;
    if (!Number.isInteger(start) || start < 0) return null;
    const items = matches.slice(start, start + limit);
    const end = start + items.length;
    return { items, next: end < matches.length ? Buffer.from(String(end)).toString('base64url') : null, total: matches.length };
    }

    Ici, le curseur contient une position. C’est sûr uniquement parce que ces données ne changent jamais pendant que l’API fonctionne. Avec des données qui changent, utilisez la clé de la dernière ligne, comme le fait l’API de billets.

  2. Ajoutez la route GET /v1/airports à api/server.mjs. Elle vérifie limit (1 à 100), type, country et after. Si une valeur est incorrecte, elle répond 400 avec la structure d’erreur. Copiez la route et api/server.test.mjs (cinq vérifications supplémentaires) depuis le projet terminé.

  3. Redémarrez l’API (Ctrl+C, puis npm run api -- --slow) et essayez-la :

    Fenêtre de terminal
    curl -s "http://127.0.0.1:8200/v1/airports?q=paris&limit=2"
    curl -s "http://127.0.0.1:8200/v1/airports?limit=500"
    Output (the first answer shortened)
    {"items":[{"iata":"CDG","ident":"LFPG","name":"Charles de Gaulle International Airport","type":"large_airport","municipality":"Paris (Roissy-en-France, Val-d'Oise)","country_code":"FR","country":"France",…},{"iata":"LBG",…}],"next":"Mg","total":8}
    {"error":{"code":"invalid_parameter","message":"limit must be a whole number from 1 to 100."}}

    Une page de 2 représente quelques centaines d’octets. En comparaison, /v1/airports/all représente 2 323 446 octets de JSON, ou 380 168 octets avec gzip.

La liste interroge maintenant le serveur à chaque changement de la recherche, dans un effet. Un bouton Load 50 more (charger 50 lignes de plus) demande la page suivante. C’est le premier essai évident, celui contre lequel Rendu et effets vous mettait en garde :

src/search/ResultList.tsx (part, a first try)
useEffect(() => {
searchAirports({ q, type: filter.type }).then(
(page: AirportPage) => setShown({ q, airports: page.items, next: page.next, total: page.total }),
setError,
);
}, [q, filter.type]);

Copiez src/api/airports.test.ts et src/search/ResultList.test.tsx depuis le projet terminé, puis lancez npm test. Deux des six tests de la page échouent, comme prévu à cette étape :

Sortie (fin)
FAIL src/search/ResultList.test.tsx > draws only the rows in view, not every loaded airport
FAIL src/search/ResultList.test.tsx > an old answer that arrives late does not replace the new one, and its request is closed
…
Tests 2 failed | 4 passed (6)

Construisez, servez et mesurez cette version avec l’étiquette paged-naive. Ensuite, tapez vous-même paris, rapidement :

La page de recherche d'aéroports. Le champ de recherche indique paris. La ligne de résultats indique : Showing 50 of 8,741 airports (affichage de 50 aéroports sur 8 741). Les premières lignes sont de grands aéroports dont la ville commence par P : Abruzzo Airport à Pescara, Antonio Agostinho-Neto International Airport à Pointe-Noire, Bacha Khan International Airport à Peshawar. Aucun n'est à Paris.
Le champ indique « paris », mais les lignes répondent à « p » : 8 741 aéroports. La page ne sait pas qu'elle se trompe. L’image est en anglais.
  • réponse reçue
  • « p », réponse reçue
  • fermée avant la fin
Une saisie de « paris » avec un effet sans nettoyage, sur le portable de l'équipe du cours (temps serveur simulé). La requête pour « p » part en premier, et sa réponse arrive en dernier.
Description textuelle du graphique

Chaque barre va de l’envoi d’une requête à l’arrivée de sa réponse : "p" from 6 to 949 ms; "pa" from 129 to 362 ms; "par" from 252 to 334 ms; "pari" from 375 to 440 ms; "paris" from 497 to 562 ms. La réponse pour « p » arrive après celle pour « paris »; ses lignes les remplacent donc.

Ce que cela nous apprend. C’est la course entre réponses périmées de Rendu et effets, avec des données réelles. La réponse pour p demande environ 934 ms de temps serveur; paris, envoyé en dernier, demande 61 ms. Donc p arrive en dernier, et ses lignes restent. Dans les exécutions de l’équipe du cours, les lignes étaient incorrectes 10 fois sur 10, sur les deux profils, toujours pour p. Dans la mesure de session, le résultat était incorrect aux 5 passages sur les deux profils. Parfois, la première réponse, pour la recherche vide avec les 9 051 correspondances, arrivait après toutes les autres. Aucune erreur n’apparaît nulle part.

Les premières lignes sont toutefois arrivées plus tôt : 1,010 ms sur le profil rapide et 1,929 ms sur celui semblable à un téléphone, contre 1,348 et 5,224 ms. La page a téléchargé 3.1 ko de données au lieu de 381 ko, et contenait 333 éléments au lieu de 54,338.

Le bureau des billets a corrigé cette course deux fois : avec un nettoyage dans un effet, puis avec TanStack Query, dans Cycle de vie d’une requête. Utilisez la bibliothèque ici, car elle conserve aussi les pages et ferme les anciennes requêtes. Enveloppez l’application dans un QueryClientProvider dans src/main.tsx (staleTime de 30 s, une nouvelle tentative), puis ajoutez une fonction personnalisée (hook) :

src/search/useAirportSearch.ts
export function useAirportSearch(filter: SearchFilter) {
const q = filter.q.trim();
return useInfiniteQuery({
queryKey: ['airports', { q, type: filter.type }],
queryFn: ({ pageParam, signal }) => searchAirports({ q, type: filter.type }, pageParam, signal),
initialPageParam: '',
getNextPageParam: (last) => last.next ?? undefined,
});
}

Trois détails assurent la correction :

  • La clé contient toute la recherche. Chaque recherche a sa propre entrée dans le cache. La liste montre seulement les données de la clé actuelle. Les lignes de p ne peuvent donc jamais apparaître pour paris.
  • Le signal. TanStack Query donne un signal à chaque requête, et apiGet le transmet à fetch. Quand la recherche change, plus personne ne lit l’ancienne requête. La bibliothèque la ferme donc.
  • useInfiniteQuery garde ensemble les pages d’une recherche et demande la suivante avec last.next.

Dans ResultList.tsx, lisez les lignes dans search.data.pages. Faites appeler fetchNextPage() par Load 50 more (charger 50 lignes de plus). Exécutez npm test : seul le test de la liste virtuelle échoue maintenant. Mesurez ensuite avec l’étiquette paged-query :

Mesure (temps serveur simulé) Effet sans nettoyage TanStack Query
Lignes incorrectes après avoir tapé paris (rapide / semblable à un téléphone) 10 sur 10 / 10 sur 10 0 sur 10 / 0 sur 10
Requêtes envoyées, fermées avant la fin (rapide) 5, 0 5, 2
Requêtes envoyées, fermées avant la fin (semblable à un téléphone) 5, 0 5, 4
Dernière touche jusqu’aux bonnes lignes (rapide / semblable à un téléphone) jamais correct 65 ms / 164 ms
Ouvrir et taper paris (rapide / semblable à un téléphone) jamais correct 614 ms / 1,661 ms
  • réponse reçue
  • « p », réponse reçue
  • fermée avant la fin
La même saisie avec TanStack Query (une exécution, portable de l'équipe du cours, temps serveur simulé). Une requête fermée avant la fin se termine au moment où le navigateur l'a fermée.
Description textuelle du graphique

"p": sent at 5 ms, closed early at 128 ms; "pa": sent at 127 ms, closed early at 250 ms; "par": sent at 250 ms, answered at 330 ms; "pari": sent at 372 ms, answered at 436 ms; "paris": sent at 495 ms, answered at 558 ms.

Ce que cela nous apprend. La course a disparu : 0 erreur à chaque exécution. Le navigateur ferme la requête lente pour p peu après la saisie de pa. Sa réponse n’arrive donc jamais. Le profil semblable à un téléphone a fermé plus de requêtes, car chacune restait ouverte plus longtemps. Les bonnes lignes sont arrivées 65 ms après la dernière touche. C’est le temps serveur pour paris (61 ms, simulé), plus le trajet. La version de départ a pris 3.3 ms, après sa longue attente initiale. Chaque touche coûte maintenant une requête : c’est le compromis.

Le serveur envoie 50 lignes à la fois. La page commence donc avec peu d’éléments : 333. Mais les agents de Nadia font défiler la liste. Chaque clic sur Load 50 more ajoute 50 lignes qui restent dans la page. Après 39 clics, elle contient 2 000 lignes. Charger moins de travail a présenté la correction : une liste virtuelle conserve toutes les lignes chargées comme données. Elle place dans la page seulement les lignes visibles dans la zone de défilement, plus quelques lignes au-dessus et en dessous.

Remplacez la liste dans ResultList.tsx par la version terminée. Elle utilise useVirtualizer, avec des lignes de 56 px et une marge de rendu (overscan) de 8 lignes. Le bureau des billets fait de même. Elle demande aussi automatiquement la page suivante quand la dernière ligne affichée est à moins de 10 lignes de la fin. La liste continue donc à défiler sans clic. Le bouton reste pour les personnes qui utilisent le clavier. Exécutez npm test : les 17 vérifications passent, soit 11 pour l’API et 6 pour la page. Mesurez avec l’étiquette virtual. Le groupe click charge d’abord 2 000 lignes; la version de départ conserve toujours les 9 051 lignes :

Mesure Version de départ (9 051 lignes) Toutes les lignes chargées (2 000) Liste virtuelle (2 000)
Éléments dans la page 54,338 12,033 141
Du clic sur une ligne à ses détails, rapide 30 ms 16 ms 15 ms
Même mesure avec le processeur semblable à celui d’un téléphone 119 ms 45 ms 14 ms

(Le deuxième clic de chaque passage; le premier était un peu plus lent dans chaque version.)

Ce que cela nous apprend. La liste virtuelle a maintenu la page à 141 éléments, peu importe la distance de défilement. Sur un ordinateur rapide, afficher 2 000 lignes ne posait pas encore de problème. Un clic prenait environ le même temps dans les deux cas. Avec le processeur semblable à celui d’un téléphone, la différence apparaissait : 45 ms contre 14 ms. Un clic refait le rendu de la liste pour marquer la ligne choisie. Les 9 051 lignes de la version de départ demandaient 119 ms. Cela dépasse les 100 ms sous lesquelles un clic semble instantané. C’est encore la règle du cours : virtualisez pour des milliers de lignes, pas des centaines.

Le problème : une carte que personne n’a encore demandée

Section intitulée « Le problème : une carte que personne n’a encore demandée »

Le panneau de détails affiche une petite carte du monde avec un point sur l’aéroport. Son contour est un long tracé SVG provenant de la carte du domaine public de Natural Earth. Il compte 72 485 caractères, soit 31.4 ko avec gzip. Il se trouve dans l’unique fichier JavaScript. Chaque personne le télécharge donc avant les premières lignes, même sans jamais ouvrir un aéroport.

Charger moins de travail a présenté lazy() et <Suspense>. Chargez le panneau quand la personne ouvre un aéroport :

src/App.tsx (part, first try)
const DetailPanel = lazy(() => import('./details/DetailPanel').then((m) => ({ default: m.DetailPanel })));
// …
{selected === null ? (
<p className="muted">Choose an airport to see where it is.</p>
) : (
<Suspense fallback={<p className="muted">Loading the map…</p>}>
<DetailPanel airport={selected} />
</Suspense>
)}

npm run build && npm run size affiche maintenant deux fichiers JavaScript :

Output of npm run size
File Size Gzip
assets/index-CSERPEPP.js 286.9 kB 87.6 kB
assets/DetailPanel-Lq4YUBTY.js 73.7 kB 31.4 kB
assets/index-D-9IoiRQ.css 2.3 kB 1.0 kB
index.html 0.4 kB 0.3 kB
JavaScript: 2 files, 118.9 kB gzip in all

Les empreintes dans les noms de fichiers (CSERPEPP) changent à chaque modification du code.

Mesurez avec l’étiquette split-naive :

Mesure Un seul fichier (virtual) Séparation, premier essai
JavaScript avant les premières lignes 120 ko 87.6 ko
Premières lignes, rapide 1,015 ms 1,012 ms
Premières lignes, semblable à un téléphone 2,008 ms 1,851 ms
Premier clic sur une ligne (rapide / semblable à un téléphone) 15 / 29 ms 331 / 347 ms
Deuxième clic (rapide / semblable à un téléphone) 15 / 14 ms 13 / 14 ms

Ce que cela nous apprend. Le premier fichier est plus petit de 32.4 ko. Sur le profil rapide, le délai des premières lignes n’a pas changé. Sur celui semblable à un téléphone, elles sont arrivées 157 ms plus tôt. C’est encore le constat du cours : séparer le code rapporte sur les réseaux lents. Mais le premier clic prenait maintenant plus de 300 ms, même sur le profil rapide. Pourtant, le fichier de 31 ko y arrive en quelques millisecondes. Pourquoi?

Pourquoi le premier clic attendait : la pause de React après un contenu de remplacement

Section intitulée « Pourquoi le premier clic attendait : la pause de React après un contenu de remplacement »

Quand le code du panneau manque encore, <Suspense> affiche son contenu de remplacement : « Loading the map… » (chargement de la carte…). Quand le code arrive, React ne remplace pas ce contenu immédiatement. Il attend qu’au moins 300 ms se soient écoulées depuis son affichage. Cela empêche la page de clignoter quand plusieurs parties chargent l’une après l’autre. (La constante est FALLBACK_THROTTLE_MS = 300 dans le code source de React 19.) Le premier clic coûte donc environ 300 ms, peu importe le réseau. L’équipe du cours a vérifié que le téléchargement n’était pas la cause. Une version qui charge le fichier après les premières lignes, sans la correction suivante, prenait encore 332 ms.

La correction : charger tôt et garder l’ancien panneau pendant l’attente

Section intitulée « La correction : charger tôt et garder l’ancien panneau pendant l’attente »

Deux changements, dans src/App.tsx du projet terminé :

src/App.tsx (part)
const loadDetails = () => import('./details/DetailPanel');
const DetailPanel = lazy(() => loadDetails().then((m) => ({ default: m.DetailPanel })));
// …
// Load the details' file while the visitor reads the first rows, not when they click.
useEffect(() => afterFirstRows(() => void loadDetails()), []);
// A transition: if the file is not there yet, React keeps the old panel until it is.
const select = (airport: Airport) => startTransition(() => setSelected(airport));
// …
<Suspense fallback={<p className="muted">Loading the map…</p>}>
{selected === null ? <p className="muted">Choose an airport to see where it is.</p> : <DetailPanel airport={selected} />}
</Suspense>
  • Charger après les premières lignes. afterFirstRows() (dans src/search/marks.ts) exécute la fonction une fois les premières lignes affichées. Le fichier ne concurrence donc jamais les premières lignes. Il est généralement présent avant le premier clic.
  • Une transition. startTransition() marque le changement d’aéroport choisi comme non urgent. Si le code manque encore, React garde le panneau déjà à l’écran jusqu’à ce que le nouveau soit prêt. Il n’affiche donc jamais le contenu de remplacement et n’attend jamais ses 300 ms. Pour que cela fonctionne, la limite <Suspense> doit déjà être à l’écran. Elle enveloppe donc maintenant aussi le texte « Choose an airport » (choisissez un aéroport).

Mesurez à nouveau avec l’étiquette finished :

Mesure Un seul fichier Séparation, premier essai Séparation, version terminée
Premières lignes, semblable à un téléphone 2,008 ms 1,851 ms 1,853 ms
Premier clic (rapide / semblable à un téléphone) 15 / 29 ms 331 / 347 ms 48 / 46 ms
Deuxième clic (rapide / semblable à un téléphone) 15 / 14 ms 13 / 14 ms 48 / 47 ms

Ce que cela nous apprend. Les premières lignes ont gardé le gain. Le premier clic est passé de plus de 300 ms à environ 48 ms. Mais lisez aussi la dernière ligne : chaque clic prend maintenant environ 48 ms, contre environ 15 ms avec un seul fichier. Une transition est un travail moins urgent. React lui donne une priorité plus faible. Les deux durées sont sous 100 ms, donc une personne ne sent pas la différence. La séparation du code a quand même un coût à chaque clic. Elle a permis de gagner 156 ms au premier chargement sur un téléphone. Pour un site surtout consulté sur téléphone, ce compromis en vaut la peine. Pour un outil de bureau seulement, un seul fichier serait aussi bon.

Erreur courante

Une séparation qui a ralenti la page

Symptôme : après la séparation du code, le premier clic sur un aéroport affiche « Loading the map… » pendant environ un tiers de seconde. Cela arrive sur tous les réseaux. Les tests passent.

Cause : un nouveau contenu de remplacement <Suspense>, puis la pause de React pouvant atteindre 300 ms avant d’afficher le contenu réel.

Correction : chargez le fichier avant d’en avoir besoin, après les premières lignes. Changez l’état dans startTransition(), à l’intérieur d’une limite déjà à l’écran. Mesurez ensuite le clic à nouveau. Une séparation est un changement comme un autre et peut aggraver une chose.

Le serveur est-il vraiment meilleur, ou la version de départ était-elle simplement mal construite? Une comparaison équitable oppose le serveur à la meilleure version de l’approche « tout télécharger ». Cette version se trouve dans le projet à l’étape client-virtual. Elle conserve le téléchargement et la recherche dans le navigateur de la version de départ. Elle ajoute la liste virtuelle et le chargement tardif du fichier de la carte. Seule la stratégie de données diffère de la page terminée. L’équipe du cours l’a construite et mesurée comme les autres. Le graphique l’appelle « Tout ».

Chaque version a exécuté les mêmes groupes sur le même portable, l’une après l’autre. Elles avaient les mêmes données, la même API et sa règle simulée, le même outil de construction et la même saisie. Le cache était vide chaque fois. La charge de l’ordinateur sur 1 minute avant les exécutions se situait entre 4.6 et 16. D’autres tâches étaient en cours. Ne retenez donc que les différences plus grandes que l’étendue des passages. Chaque fichier JSON contient tous les passages.

  • Rapide
  • Semblable à un téléphone
La mesure unique : de l'ouverture de la page jusqu'à l'affichage stable des lignes pour « paris ». Médiane de 5 passages sur le portable de l'équipe du cours; temps serveur simulé. Départ; Tout : tout téléchargé, avec une liste virtuelle; Finale : la page terminée. L'effet sans nettoyage n'est pas montré : il n'a jamais affiché les bonnes lignes.
Description textuelle du graphique

Sur le profil rapide, les bonnes lignes sont arrivées après 1,041 ms pour la version de départ. Tout télécharger avec une liste virtuelle (« Tout ») a pris 1,058 ms, et la page terminée, 600 ms. Sur le profil semblable à un téléphone : 3,758, 3,674 et 1,555 ms.

Version Bonnes lignes, rapide Bonnes lignes, semblable à un téléphone Incorrectes Tâches longues pendant la saisie (semblable à un téléphone) Données au départ
Version de départ 1,041 ms 3,758 ms 0 1,245 ms 381 ko
Tout, bien fait 1,058 ms 3,674 ms 0 0 ms 381 ko
Serveur, effet sans nettoyage jamais jamais 5 sur 5 0 ms 3.1 ko
Serveur, TanStack Query 614 ms 1,661 ms 0 0 ms 3.1 ko
Version terminée 600 ms 1,555 ms 0 0 ms 3.1 ko

Ce que cela nous apprend.

  • Le serveur gagne sur la mesure unique. La page terminée a affiché les bonnes lignes 42 % plus tôt que la version de départ sur le profil rapide. Sur celui semblable à un téléphone, le gain était de 59 %.
  • « Tout, bien fait » a corrigé le blocage, pas l’attente. Avec une liste virtuelle, la saisie ne causait aucune tâche longue. Une recherche après le téléchargement prenait 4.3 ms. Mais la personne attend encore 381 ko avant la première réponse : 3.7 s sur le profil semblable à un téléphone. Le téléchargement, pas le rendu, détermine cette mesure.
  • Les deux dernières étapes ont à peine changé cette mesure. La liste virtuelle et la séparation comptaient pour le défilement, les clics et les premières lignes sur téléphone. Pas pour « ouvrir et taper ». Chaque étape répondait à sa propre mesure.

Les versions ont été construites et ajustées en tapant paris. Le résultat tient-il pour une recherche que personne n’a essayée? L’équipe du cours a repris la mesure de session avec un nouveau mot, osaka. Sa première lettre, o, correspond à 8 899 aéroports. C’est donc une autre première réponse lente :

Version Bonnes lignes pour osaka, rapide Semblable à un téléphone Incorrectes
Version de départ 1,037 ms 3,746 ms 0 sur 10
Tout, bien fait 1,046 ms 3,646 ms 0 sur 10
Version terminée 611 ms 1,548 ms 0 sur 10

Suivez ensuite une recherche à travers tout le système, dans la page terminée :

Étape Ce qui se passe Ce qui le prouve
La personne ouvre la page une requête pour la première page de la recherche vide, environ 3 ko le groupe open : une requête API, 141 éléments
Les premières lignes sont affichées le fichier des détails commence à charger search:first-rows, puis un deuxième fichier JavaScript dans le groupe open
Elle tape o, os … osaka une requête par touche; les anciennes sont fermées les requêtes envoyées et fermées avant la fin dans le groupe type
La réponse pour osaka arrive ses lignes remplacent celles de la recherche vide et restent data-results-for="osaka" 3 s plus tard
Elle ouvre un aéroport le panneau et la carte apparaissent, sans « Loading the map… » le groupe click : moins de 50 ms
La page terminée de recherche d'aéroports sur un ordinateur de bureau. Le champ de recherche contient paris; la ligne de résultats indique Showing 8 of 8 airports (affichage de 8 aéroports sur 8). La première ligne est sélectionnée : CDG Charles de Gaulle International Airport, Paris (Roissy-en-France, Val-d'Oise), France, Large airport (grand aéroport). À droite, les détails : Place (lieu) Paris (Roissy-en-France, Val-d'Oise), France; Type (type) Large airport, scheduled flights (grand aéroport, vols réguliers); ICAO or local code (code OACI ou local) LFPG; position et altitude; et une carte du monde avec un point dans le nord de la France.
La page terminée : les lignes pour « paris », et la première ouverte avec sa carte. L’image est en anglais.

Ce que cela nous apprend. Le nouveau mot a donné le même portrait que paris. Aucune ligne incorrecte dans les versions serveur, et le même classement des versions. Le résultat n’est pas une particularité d’une seule recherche.

Utilisez la conception terminée pour le site Web et le bureau des agents. Le serveur cherche et pagine. TanStack Query sépare les recherches et ferme les anciennes requêtes. Une liste virtuelle affiche les lignes visibles. Le code de la carte arrive après les premières lignes. Sur le portable de l’équipe du cours, le délai jusqu’aux bonnes lignes est passé de 1,041 à 600 ms. Sur le profil semblable à un téléphone, il est passé de 3.8 à 1.6 s, sans ligne incorrecte.

Son coût, expliqué simplement à Nadia et Leo :

  • Une requête par touche. Une recherche après la dernière touche prenait environ 65 ms au lieu de quelques millisecondes. Une courte pause avant l’envoi, une temporisation (debounce) d’environ 150 ms, réduirait le nombre de requêtes. Elle ne remplacerait pas l’annulation. Une réponse lente peut encore arriver en retard après une pause.
  • L’API doit rester disponible. « Tout, bien fait » fonctionne hors ligne une fois chargé. La conception serveur ne le permet pas.
  • Une transition de plus par clic. Environ 48 ms par clic au lieu d’environ 15 ms : invisible pour une personne, mais visible dans les chiffres.

Quand l’autre approche convient. « Tout, bien fait » est un choix raisonnable quand les données sont petites et fixes. La page reste ouverte toute la journée, et le réseau est rapide. Il y a alors une attente le matin, puis des recherches instantanées. Un outil de bureau pour 300 fournisseurs est un tel cas. Le site Web des aéroports ne l’est pas.

  • Mesurez la version que vous construiriez, pas une version volontairement faible. La version de départ a perdu de beaucoup. « Tout, bien fait » a perdu de moins, et a gagné sur une mesure. Seule cette comparaison est juste.
  • Corrigez la condition de concurrence dans le code, pas sur votre portable. À pleine vitesse, elle n’est apparue dans aucun des 10 essais. Un test qui répond dans le désordre (ResultList.test.tsx) la détecte chaque fois.
  • Un changement, une mesure. La pagination serveur a amélioré les premières lignes et les données. La bibliothèque a corrigé la condition de concurrence. La liste virtuelle a réduit les éléments et accéléré les clics sur le téléphone. Le fractionnement a accéléré le premier chargement sur le téléphone. Aucun changement n’a tout réglé.
  • Une correction peut avoir un coût ailleurs. Le premier fractionnement a rendu le premier clic dix fois plus lent. Le fractionnement final coûte environ 30 ms à chaque clic.
  • Limites de cette étude. Un portable partagé, Chromium seulement, un téléphone simulé et un temps serveur simulé, 9 051 lignes, un mot puis un nouveau mot. Le serveur fonctionnait sur le même ordinateur, donc aucun vrai réseau ne les séparait. Nous n’avons pas testé Windows, Linux, Firefox, Safari ni de vrais téléphones.
  • Les données n’offrent aucune garantie. OurAirports le précise, et des bénévoles les modifient chaque jour. Affichez la source et sa date sur la page. N’utilisez pas la liste pour planifier un vol.
  • Mentionnez la source, même quand la licence ne l’exige pas. L’en-tête de la page nomme OurAirports et contient un lien vers le site.
  • Mesurez seulement vos propres services. Le script de mesure envoie beaucoup de requêtes. Dirigez-le vers votre propre API sur votre ordinateur. Jamais vers OurAirports ni vers un service que vous n’exploitez pas.
  • Un champ de recherche est une entrée. L’API vérifie chaque paramètre et répond 400 si un paramètre est invalide. React échappe les noms qu’il affiche. Un nom contenant du HTML apparaît donc comme du texte, sans exécution.
  • Clavier et lecteurs d’écran. Chaque ligne est un bouton portant son nom. La liste est une région avec une étiquette, accessible avec la touche Tab. Une liste virtuelle a un coût ici : la recherche du navigateur trouve seulement les lignes présentes dans la page. Interactions accessibles et l’étude de cas Rendre accessible une interface de chat d’IA montrent comment tester cela.

Ce projet montre ce que les employeurs recherchent chez un ingénieur frontend (interface utilisateur). Une mesure choisie avant le code, des chiffres honnêtes, une condition de concurrence trouvée et corrigée grâce à un test. Et une décision qui précise ses coûts.

Quoi mettre dans le dépôt :

airport-search/
README.md what it is, how to run, test and measure it, your results table
DATASET.md the source, the licence, the checksum, the changes, the limits
LICENSE MIT, for the code
docs/results.md your numbers: the computer, the build, the API mode, the medians
api/ the search API and its 11 checks
src/ the page and its 6 tests
measure/ measure.mjs and its four groups
data/airports.csv the fixed copy (public domain)
  1. Créez un dépôt Git à partir de votre dossier de projet, puis envoyez-le sur GitHub. .gitignore exclut node_modules/, dist/ et results/.
  2. Remplissez docs/results.md avec vos propres essais et les détails de votre ordinateur. Ajoutez un lien vers ce fichier dans le README.
  3. Décrivez le projet en deux phrases : « Une page de recherche parmi 9 051 aéroports, avec une petite API Node.js. J’ai comparé les versions avec une seule mesure et corrigé une condition de concurrence liée aux réponses périmées, présente 10 fois sur 10. Le temps pour obtenir les bonnes lignes sur un profil simulant un téléphone a diminué de plus de moitié. »

Allez plus loin : ajoutez une temporisation (debounce) et mesurez les requêtes qu’elle évite. Ajoutez le filtre par pays que l’API possède déjà. Faites les mesures sur un vrai téléphone connecté au Wi-Fi, avec le débogage à distance de Chrome.

Vérifiez votre compréhension

Avec l'API à pleine vitesse, l'effet sans nettoyage a affiché les bonnes lignes dans 10 essais sur 10. Un collègue dit que la condition de concurrence n'est pas un vrai problème. Que répondez-vous?

Afficher la réponse

La condition de concurrence est dans le code : l’effet affiche la réponse qui arrive en dernier. À pleine vitesse, chaque réponse prenait quelques millisecondes et arrivait dans l’ordre. Le bogue restait donc caché. Avec un temps serveur qui augmente selon le nombre de correspondances, la réponse pour « p » arrivait en dernier, 10 fois sur 10. Un vrai serveur, une période chargée ou un réseau mobile peut produire le même résultat. La correction repose sur un nettoyage, ou sur la clé et le signal de TanStack Query. Un test qui répond dans le désordre le prouve.

Vérifiez votre compréhension

Après son téléchargement, la version de départ affichait les lignes pour « paris » environ 3 ms après la dernière touche. La page finale prenait environ 65 ms. Pourquoi recommande-t-on quand même le serveur?

Afficher la réponse

Parce que la mesure choisie commence à l’ouverture de la page. La version de départ doit d’abord télécharger 380 ko et afficher chaque ligne. Les bonnes lignes arrivaient après environ 1 s sur le profil rapide, et 3,8 s sur celui simulant un téléphone. La page finale prenait environ 0,6 s et 1,6 s. Même « tout, bien fait », avec une liste virtuelle, attendait 3,7 s sur le profil simulant un téléphone. Les 65 ms après la dernière touche sont le prix du serveur. Ce délai est beaucoup plus court que le téléchargement.

Vérifiez votre compréhension

Le premier essai de fractionnement du code faisait prendre plus de 300 ms au premier clic sur un aéroport. Même sur un réseau rapide. Quelles étaient les causes, et quels deux changements ont réglé le problème?

Afficher la réponse

Le code du panneau n’était pas encore chargé. La nouvelle limite <Suspense> affichait donc son contenu de remplacement. Ensuite, React attendait que 300 ms se soient écoulées depuis son apparition avant d’afficher le panneau. La correction comporte deux parties. Chargez le fichier après les premières lignes, pour qu’il soit disponible avant le clic. Et changez l’aéroport choisi dans startTransition(), à l’intérieur d’une limite déjà à l’écran. React garde alors l’ancien panneau au lieu d’afficher le contenu de remplacement. Le premier clic est passé à environ 48 ms.

Récapitulatif

  • Vous avez d’abord choisi une mesure : le temps entre l’ouverture de la page et les bonnes lignes pour un mot saisi. Vous l’avez mesuré sur un profil rapide et un profil simulant un téléphone.
  • Le prototype téléchargeait 380 ko et affichait jusqu’à 54 338 éléments. Ses recherches étaient instantanées après le téléchargement, mais la page gelait pendant la saisie.
  • La pagination serveur a réduit la première réponse et introduit une condition de concurrence liée aux réponses périmées. Les lignes étaient incorrectes 10 fois sur 10. La clé et le signal de TanStack Query ont réglé le problème.
  • Une liste virtuelle a maintenu la page à environ 140 éléments. Le fractionnement du code a accéléré le premier chargement sur le téléphone, après une correction de la pause de React.
  • La page finale affichait les bonnes lignes en environ 0,6 s au lieu de 1 s. Sur le profil simulant un téléphone, elle prenait 1,6 s au lieu de 3,8 s. « Tout, bien fait » restait lent au démarrage.

La deuxième étude de cas rend ensuite une interface de chat d’IA utilisable avec un clavier et un lecteur d’écran.

Leçon suivante : Rendre accessible une interface de chat d'IA