Aller au contenu
English

Cycle de vie d'une requête

  • Leçon 9
  • 60 min
  • Module 3 : Récupération des données et gestion de l'état

Où nous en sommes

Dans la leçon précédente, un cache a commencé à garder les données de l'API, et une copie de moins de 30 secondes s'affiche sans requête. Mais une copie vieillit aussi, doit être récupérée de nouveau, peut devenir périmée après un changement et peut échouer quand le serveur est occupé. Dans cette leçon, nous suivons une copie pendant toute sa vie, et nous contrôlons chaque étape. Un carton de lait dans un réfrigérateur partagé a la même vie.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité

Ce que vous saurez faire

Une copie en cache naît, vieillit, est récupérée à nouveau, puis supprimée. Contrôlez chaque étape. Ainsi, le bureau n’affiche jamais la réponse à une ancienne recherche. Il se rétablit aussi tout seul quand le serveur est occupé un moment.

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

Ce que vous devez savoir

  • L’état local, l’état serveur, le cache, les clés, staleTime et useTicket, dans État local et état serveur.
  • La course entre réponses périmées et le nettoyage de l’effet avec un AbortController, dans Rendu et effets.
  • Les codes d’état HTTP 404 et 503, et la structure des erreurs de l’API des billets, dans Validation et réponses d’erreur du cours Créer et déployer votre première API.

Ce qu’il vous faut sur votre ordinateur

  • Votre ticket-desk à la fin de la leçon précédente, avec TanStack Query installé. npm test réussit les 14 tests Vitest.
  • Deux terminaux : un pour l’API simulée, un pour le bureau.

Testé avec Node.js 24.18.0 sur macOS (Apple silicon), dans Chromium. Les commandes Windows et Linux sont fournies, mais n’ont pas été testées. Les temps de réponse des listes de l’API simulée sont simulés : 60 ms, plus 0,1 ms par billet correspondant à la recherche.

Pensez à un carton de lait dans le réfrigérateur partagé d’un bureau. À l’achat, il est frais. Pendant quelques jours, vous l’utilisez sans vous poser de questions. Après la date sur le carton, vous ne le jetez pas tout de suite. Vous l’utilisez encore, mais vous le vérifiez et achetez bientôt un nouveau carton.

Parfois, un collègue y colle une note : « Celui-ci est fini, achetez-en un nouveau. » Dès ce moment, le carton est périmé, peu importe sa date. Et si personne ne touche à un carton pendant des semaines, quelqu’un le retire du réfrigérateur.

Une copie dans le cache du bureau suit le même cycle. Elle a une date et vieillit. D’autres événements peuvent la marquer comme périmée. On la supprime quand personne ne l’utilise.

La leçon précédente donnait à chaque copie une durée de fraîcheur de 30 secondes. Voici toute la vie d’une copie, avec les noms de ses étapes :

  1. Aucune copie. Un écran demande une clé que le cache n’a jamais vue.
  2. Récupération. Le cache exécute la fonction de requête, et l’écran affiche « Loading… » (chargement).
  3. Fraîche. La réponse arrive. Pendant 30 secondes (staleTime), chaque écran qui demande cette clé reçoit la copie immédiatement, sans requête.
  4. Périmée. Après 30 secondes, la copie s’affiche encore immédiatement. Mais le cache la récupère à nouveau quand un écran l’ouvre ou quand la fenêtre du navigateur reçoit le focus. La copie redevient alors fraîche.
  5. Invalidée. Après un changement sur le serveur, le bureau marque immédiatement les copies concernées comme périmées. C’est l’invalidation : la note sur le carton de lait. La fonction de TanStack Query s’appelle invalidateQueries. Les écrans qui affichent ces copies les récupèrent à nouveau.
  6. Supprimée. Une copie qu’aucun écran n’a utilisée pendant 5 minutes (gcTime) est supprimée.

Deux choses peuvent arriver à une requête pendant la récupération de la copie. Elle peut échouer : le cache peut alors réessayer. L’agent peut aussi la rendre inutile, par exemple en tapant une lettre de plus : le cache l’annule alors. Le reste de cette leçon porte sur ces deux cas.

Un diagramme d'états d'une entrée du cache. Aucune copie, la clé est nouvelle; un écran la demande avec useQuery; récupération, la requête s'exécute; la réponse arrive; fraîche pendant 30 s, affichée immédiatement, sans requête; 30 s passent ou invalidateQueries; périmée, affichée immédiatement, avec une nouvelle requête quand un écran l'ouvre; une flèche revient à récupération quand un écran l'ouvre ou que la fenêtre reçoit le focus; une flèche pointillée mène à supprimée après 5 minutes sans utilisation par un écran. Deux notes : la requête échoue, aucune réponse ou 503 : réessayer après Retry-After ou 1 s, 2 s, au plus 2 nouvelles tentatives, jamais pour 4xx, puis une erreur avec Try again (réessayer). La clé change pendant l'exécution, l'agent a tapé une lettre de plus : l'ancienne requête est annulée.
La vie d'une copie dans le cache du bureau, avec ses réglages : fraîche pendant 30 secondes, conservée 5 minutes sans utilisation, au plus 2 nouvelles tentatives.
Description textuelle du diagramme

Une copie commence sans données. Quand un écran demande sa clé avec useQuery, le cache lance la récupération. Quand la réponse arrive, la copie reste fraîche pendant 30 secondes : chaque écran la reçoit immédiatement, sans requête. Après 30 secondes, ou immédiatement après invalidateQueries, la copie est périmée. Elle s’affiche encore immédiatement. Le cache la récupère toutefois à nouveau quand un écran l’ouvre ou quand la fenêtre reçoit le focus. Une copie qu’aucun écran n’utilise pendant 5 minutes est supprimée. Deux notes décrivent une requête en cours. Si elle échoue sans réponse ou avec un code 503, le cache réessaie après le délai Retry-After. Sinon, il attend 1 seconde, puis 2 secondes. Il réessaie au plus deux fois, et jamais pour une réponse 4xx. Ensuite, l’écran affiche une erreur avec Try again (réessayer). Si la clé change pendant l’exécution, l’ancienne requête est annulée.

L’équipe du cours a ouvert le bureau dans Chromium. Elle a compté les requêtes reçues par l’API simulée après chaque étape. Il s’agit du bureau à la fin du module, avec un staleTime de 30 secondes :

Étape Requêtes de billet Requêtes de liste Pourquoi
Ouvrir le bureau sur T-80008 1 1 aucune copie pour les deux clés : récupération
Ouvrir T-80007 2 1 une nouvelle clé : récupération
Revenir à T-80008 avant 30 s 2 1 la copie est fraîche : aucune requête
Envoyer une réponse à T-80008 3 2 la réponse invalide le billet et les listes
Taper « parcel » dans la recherche 6 envoyées, 5 fermées avant la fin chaque lettre crée une nouvelle clé; les anciennes requêtes sont annulées

Lisez attentivement les deux dernières lignes. Une réponse change les messages du billet, et la liste affiche le nombre de messages. Les deux copies sont donc maintenant périmées. Le bureau les marque comme périmées, et les écrans les récupèrent à nouveau. Cela ajoute une requête de billet et une requête de liste. Vous écrirez cette invalidation dans Pagination et formulaires. La dernière ligne est le sujet de la prochaine section.

La liste utilise encore useApi. Sa clé doit contenir tout ce qui change la réponse : le texte de recherche et les deux filtres. Chaque recherche a alors sa propre copie :

Ce que l’agent a tapé Clé de la liste
(rien) ['tickets', 'list', { status: '', team: '', q: '' }]
p ['tickets', 'list', { status: '', team: '', q: 'p' }]
parcel ['tickets', 'list', { status: '', team: '', q: 'parcel' }]

TanStack Query compare les clés selon leur contenu. Un nouvel objet ayant les mêmes valeurs représente donc la même clé. Toutes les clés des billets commencent par 'tickets', et toutes les clés de liste par 'tickets', 'list'. Un seul appel pourra donc invalider toutes les listes à la fois, peu importe leur filtre.

  1. Dans src/features/tickets/queries.ts, ajoutez les clés de liste et un hook (fonction React) pour la première page de la liste :

    src/features/tickets/queries.ts
    // Server state of the tickets: the cache keys and the queries.
    import { useQuery } from '@tanstack/react-query';
    import { getTicket } from '../../api/tickets';
    import { getTicket, listTickets } from '../../api/tickets';
    import type { TicketFilter } from '../../api/types';
    export const PAGE_SIZE = 50;
    /** One place for the cache keys: every key of the tickets starts with 'tickets'. */
    export const ticketKeys = {
    all: ['tickets'] as const,
    lists: () => [...ticketKeys.all, 'list'] as const,
    list: (filter: TicketFilter) => [...ticketKeys.lists(), filter] as const,
    detail: (id: string) => [...ticketKeys.all, 'detail', id] as const,
    };
    /** The first page of the list. A new filter is a new key, so it has its own cache entry. */
    export function useTicketList(filter: TicketFilter) {
    return useQuery({
    queryKey: ticketKeys.list(filter),
    queryFn: ({ signal }) => listTickets(filter, PAGE_SIZE, null, signal),
    placeholderData: (previous) => previous, // keep showing the old results while the new ones load
    });
    }
    export function useTicket(id: string) {

    placeholderData répond à une question soulevée par une nouvelle clé : qu’affiche la liste pendant le chargement de « parcel »? Sans cette option, la liste disparaîtrait et afficherait « Loading tickets… » (chargement des billets) après chaque lettre. Avec elle, les anciens résultats restent à l’écran, et isPlaceholderData vaut vrai jusqu’à l’arrivée de la nouvelle réponse.

  2. Dans src/features/tickets/TicketList.tsx, utilisez le hook :

    src/features/tickets/TicketList.tsx
    import { useState } from 'react';
    import { listTickets } from '../../api/tickets';
    import type { TicketFilter } from '../../api/types';
    import { useApi } from '../../lib/useApi';
    import { ErrorMessage } from '../../ui/ErrorMessage';
    import { useTicketList } from './queries';
    import { TicketFilters } from './TicketFilters';
    import { TicketRow } from './TicketRow';
    …
    const [filter, setFilter] = useState<TicketFilter>(NO_FILTER);
    const tickets = useApi((signal) => listTickets(filter, 50, null, signal), [filter.status, filter.team, filter.q]);
    const list = useTicketList(filter);
    const tickets = list.data?.items ?? [];
    …
    {tickets.status === 'loading' && <p className="muted">Loading tickets…</p>}
    {tickets.status === 'error' && <ErrorMessage error={tickets.error} />}
    {tickets.status === 'success' && (
    {list.isPending && <p className="muted">Loading tickets…</p>}
    {list.isError && <ErrorMessage error={list.error} onRetry={() => list.refetch()} />}
    {list.isSuccess && (
    <>
    <p className="muted">{tickets.data.items.length === 0 ? 'No ticket matches.' : `Showing ${tickets.data.items.length} tickets.`}</p>
    <p className="muted" aria-live="polite">
    {tickets.length === 0 ? 'No ticket matches.' : `Showing ${tickets.length} tickets.`}
    {list.isPlaceholderData && ' Updating…'}
    </p>
    <ul className="rows">
    {tickets.data.items.map((t) => (
    {tickets.map((t) => (

    aria-live="polite" demande au lecteur d’écran de lire la ligne quand elle change, après avoir terminé sa lecture actuelle. Camille, qui utilise un lecteur d’écran, entend alors « Showing 50 tickets. Updating… » (50 billets affichés. Mise à jour…), puis le nouveau nombre.

  3. Les tests des composants ont aussi besoin d’un cache. Créez src/test/render.tsx :

    src/test/render.tsx
    // Renders a component inside a fresh cache, as main.tsx does, without retries (tests are fast).
    import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
    import { render } from '@testing-library/react';
    import type { ReactElement } from 'react';
    export function renderWithCache(ui: ReactElement) {
    const client = new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: Infinity } } });
    return { client, ...render(<QueryClientProvider client={client}>{ui}</QueryClientProvider>) };
    }

    Chaque test reçoit son propre cache vide. Aucun test ne voit donc les copies d’un autre.

  4. Dans src/features/tickets/TicketList.test.tsx, remplacez render par renderWithCache dans les trois tests. Remplacez ensuite le dernier test pour qu’il vérifie aussi Try again (réessayer) :

    src/features/tickets/TicketList.test.tsx
    test('shows the API’s error and can try again', async () => {
    let calls = 0;
    installFakeApi(() => (++calls === 1 ? apiError(503, 'unavailable', 'The ticket service is not available.') : json(200, { items: [ticket(1)], next: null })));
    renderWithCache(<TicketList selectedId={null} />);
    expect(await screen.findByRole('alert')).toHaveTextContent('The ticket service is not available.');
    await userEvent.click(screen.getByRole('button', { name: 'Try again' }));
    expect(await screen.findByText('Ticket number 1')).toBeInTheDocument();
    });

    La ligne d’importation devient import { screen } from '@testing-library/react';, avec en plus import { renderWithCache } from '../../test/render';.

Vous avez rencontré ce problème, la course entre réponses périmées, dans Rendu et effets. Le champ de recherche envoie une requête par lettre. La recherche courte « p » est la plus lente : environ 907 ms de temps serveur simulé, contre 167 ms pour « parcel ». La réponse pour « p » arrive donc en dernier. Si l’écran affiche chaque réponse à son arrivée, il finit par montrer les résultats pour « p ». Pourtant, le champ contient « parcel ».

Le bureau propose une page de laboratoire pour ce problème. Elle présente la même recherche en trois versions, à choisir avec un bouton radio. Un effet sans nettoyage, notre useApi avec son nettoyage, et TanStack Query.

  1. Copiez le dossier src/labs/ de l’instantané end-of-m03 dans votre src/. Il contient trois fichiers : LabsPage.tsx (la liste des laboratoires), RaceLab.tsx (le laboratoire) et RaceLab.test.tsx (ses tests).

    Fenêtre de terminal
    cp -R ../nextia-learning-labs/C22/snapshots/end-of-m03/src/labs src/

    La commande suppose que le dépôt des laboratoires se trouve à côté de ticket-desk. Changez le chemin si le vôtre est ailleurs.

  2. Ouvrez src/labs/RaceLab.tsx et lisez les trois hooks. Le premier contient volontairement l’erreur :

    src/labs/RaceLab.tsx (part)
    /** The mistake: an effect without cleanup. Every answer is shown when it arrives, also an old one. */
    function useNaiveSearch(q: string): Answer | null {
    const [answer, setAnswer] = useState<Answer | null>(null);
    useEffect(() => {
    search(q).then(setAnswer, () => {});
    }, [q]);
    return answer;
    }
    function useCleanupSearch(q: string): Answer | null {
    return useApi((signal) => search(q, signal), [q]).data;
    }
    function useLibrarySearch(q: string): Answer | null {
    return useQuery({ queryKey: ['race', q], queryFn: ({ signal }) => search(q, signal) }).data ?? null;
    }

    Chaque réponse garde en mémoire la recherche à laquelle elle appartient. Le laboratoire peut donc afficher « but the box says » (mais le champ contient) si la réponse ne correspond pas au champ.

  3. Ajoutez la route et le lien dans src/App.tsx. Le routeur connaît déjà #/labs :

    src/App.tsx
    import { TicketView } from './features/tickets/TicketView';
    import { LabsPage } from './labs/LabsPage';
    import { useRoute } from './router';
    …
    New ticket
    </a>
    <a href="#/labs" aria-current={route.page === 'labs' ? 'page' : undefined}>
    Labs
    </a>
    </nav>
    </header>
    <main className="layout">
    {route.page === 'new' ? (
    <NewTicketForm />
    ) : (
    {route.page === 'new' && <NewTicketForm />}
    {route.page === 'labs' && <LabsPage lab={route.lab} />}
    {route.page === 'tickets' && (
    <>
    <TicketList selectedId={route.page === 'tickets' ? route.ticketId : null} />
    <TicketList selectedId={route.ticketId} />
    <div className="detail">
    {route.page === 'tickets' && route.ticketId ? (
    <TicketView ticketId={route.ticketId} />
    ) : (
    <p className="muted">Choose a ticket in the list.</p>
    )}
    {route.ticketId ? <TicketView ticketId={route.ticketId} /> : <p className="muted">Choose a ticket in the list.</p>}
    </div>
    </>
    )}
  4. Démarrez l’API simulée et le bureau (npm run api, npm run dev). Ouvrez http://localhost:5173/#/labs/race.

  5. Gardez Effect without cleanup (effet sans nettoyage) sélectionné. Tapez parcel dans le champ à une vitesse normale. Attendez deux secondes.

La ligne sous le champ devient rouge :

La page de laboratoire Une ancienne réponse arrive en dernier. Le bouton radio Effect without cleanup (effet sans nettoyage) est sélectionné. Le champ de recherche contient parcel. En dessous, une ligne rouge : Results for p : 20 tickets, but the box says parcel (résultats pour p : 20 billets, mais le champ contient parcel). Cinq billets suivent, comme T-80010 Return label for my order LK-300210 (étiquette de retour pour ma commande LK-300210), qui ne contiennent pas le mot parcel.
L'effet sans nettoyage : la réponse pour « p » est arrivée en dernier. L'écran l'affiche donc sous le mot « parcel ». L’image est en anglais.

Pourquoi « p »? L’équipe du cours a enregistré chaque requête de la page pendant qu’un navigateur de test tapait « parcel ». Il attendait 120 ms entre les touches. Le diagramme représente chaque requête par une barre, de son envoi à sa fin :

Two timelines from 0 to 1,000 ms, one row per search. Effect without cleanup: p from 7 to 912 ms, pa from 162 to 632 ms, par from 288 to 508 ms, parc from 411 to 573 ms, parce from 535 to 699 ms, parcel from 661 to 827 ms; all answered; p ends last and is shown. TanStack Query: p, pa, par, parc and parce each end when the next letter is typed, cancelled; parcel from 626 to 792 ms is answered and shown.
Chaque requête de liste pendant la saisie de « parcel » (une exécution enregistrée; temps serveur simulés). Sans nettoyage, les six réponses arrivent, et « p » arrive en dernier. Avec la bibliothèque, chaque nouvelle lettre annule la requête précédente.
Description textuelle du diagramme

La chronologie du haut représente l’effet sans nettoyage. Six requêtes s’exécutent en même temps. La requête pour « p » commence à 7 ms et se termine à 912 ms. Les autres se terminent plus tôt : « par » à 508 ms, « parc » à 573, « pa » à 632, « parce » à 699 et « parcel » à 827. Chaque réponse remplace la précédente à l’écran. La dernière, « p », reste donc affichée. La chronologie du bas représente TanStack Query. Chaque requête se termine, annulée, à la saisie de la lettre suivante : « p » à 130 ms, « pa » à 254, et ainsi de suite. Seule « parcel », de 626 à 792 ms, reçoit une réponse, qui s’affiche. useApi avec son nettoyage donne le même résultat que la bibliothèque.

Sans nettoyage, l’écran affiche donc les bons résultats seulement par chance : tout dépend de l’ordre d’arrivée des réponses. Sur 10 exécutions dans Chromium, l’effet sans nettoyage a affiché les résultats pour « p » 10 fois sur 10. Les deux autres versions ont affiché « parcel » 10 fois sur 10.

  1. Ouvrez le panneau Network (réseau) des outils de développement, et tapez v1/tickets dans son filtre.
  2. Rechargez la page pour que le laboratoire démarre avec un champ vide et un cache vide.
  3. Choisissez TanStack Query, et tapez parcel. La ligne sous le champ est grise : Results for “parcel”: 20 tickets. (résultats pour « parcel » : 20 billets).
  4. Regardez les requêtes dont l’adresse se termine par q=p, q=pa, q=par, q=parc et q=parce. Dans Chrome et Edge, leur état est (canceled) (annulée). La requête pour q=parcel a l’état 200.

Comment la bibliothèque le sait-elle? Quand la clé passe de ['race', 'p'] à ['race', 'pa'], aucun composant n’utilise plus la copie pour « p ». Sa requête s’exécute encore, et la fonction de requête a reçu le signal. TanStack Query annule donc ce signal, et le navigateur ferme la requête. La réponse pour « p » ne peut jamais arriver. Cette annulation économise aussi du travail : le serveur arrête la recherche. Le navigateur ne télécharge pas une réponse dont personne ne veut.

Vous obtenez ce comportement sans travail supplémentaire dans la liste du bureau. Lors de l’exécution de l’équipe du cours, taper « parcel » dans la recherche du bureau a envoyé 6 requêtes de liste. Parmi elles, 5 ont été fermées avant la fin.

Quand le serveur est occupé : les nouvelles tentatives

Section intitulée « Quand le serveur est occupé : les nouvelles tentatives »

Imaginez que vous appelez un bureau occupé. Une voix enregistrée dit : « Toutes nos lignes sont occupées. Veuillez rappeler dans deux minutes. » Vous n’abandonnez pas, mais vous ne rappelez pas chaque seconde non plus. Vous attendez deux minutes et rappelez. Si les lignes restent occupées après quelques tentatives, vous écrivez plutôt un courriel.

Un serveur peut dire la même chose. Le statut 503 Service Unavailable (service indisponible) signifie « occupé maintenant, réessayez plus tard ». L’en-tête Retry-After: 2 indique combien de secondes attendre. L’API simulée propose un mode où une réponse de liste sur deux est une 503. Démarrez-la dans le premier terminal (arrêtez d’abord la version normale avec Ctrl+C) :

Fenêtre de terminal
node mock-api/server.mjs --list flaky

Trois requêtes de liste de suite, avec curl :

$ curl -s -i "http://127.0.0.1:8100/v1/tickets?limit=1" | head -1
HTTP/1.1 200 OK
$ curl -s -i "http://127.0.0.1:8100/v1/tickets?limit=1" | grep -E "^(HTTP|Retry-After)|error"
HTTP/1.1 503 Service Unavailable
Retry-After: 2
{"error":{"code":"unavailable","message":"The ticket service is not available. Try again in a few seconds.","request_id":"04a9a1a9-0ec0-4222-b1eb-ac35c35e9291","fields":[]}}
$ curl -s -i "http://127.0.0.1:8100/v1/tickets?limit=1" | head -1
HTTP/1.1 200 OK

Le request_id diffère à chaque exécution. Une deuxième tentative aurait fonctionné. Mais toutes les erreurs ne sont pas comme ça. Une 404 Not Found (introuvable) pour T-99999 restera une 404 à chaque tentative : le billet n’existe pas. Une 422 pour un filtre incorrect ne deviendra pas valide non plus. Réessayer fait seulement attendre l’agent plus longtemps pour la même erreur.

Voici donc la règle du bureau pour les nouvelles tentatives :

  • Réessayez si aucune réponse n’arrive (network_error, erreur réseau) ou si le serveur est occupé (503). Cela peut changer en une seconde.
  • Ne réessayez jamais pour toute autre réponse 4xx. Elle ne changera pas.
  • Attendez aussi longtemps que l’indique Retry-After. Si le serveur ne précise rien, attendez 1 seconde, puis 2 secondes.
  • Arrêtez après 2 nouvelles tentatives, et affichez l’erreur avec Try again (réessayer). L’agent décide de la suite.
  • Ne réessayez jamais une modification (un POST ou un PATCH) automatiquement. Un deuxième POST pourrait enregistrer une deuxième réponse. Pagination et formulaires montre comment un formulaire peut renvoyer une requête sans risque.
  1. Remplacez src/api/queryClient.ts par cette version. Les nouvelles lignes définissent la règle des nouvelles tentatives :

    src/api/queryClient.ts
    // The cache of server data (TanStack Query) and its rules for this app.
    import { QueryClient } from '@tanstack/react-query';
    import { ApiError } from './client';
    /** Try again only when trying again can help: no answer, or the server is busy (503). Never for 4xx. */
    export function shouldRetry(failureCount: number, error: Error): boolean {
    if (!(error instanceof ApiError)) return false;
    const temporary = error.code === 'network_error' || error.status === 503;
    return temporary && failureCount < 2;
    }
    export function makeQueryClient(): QueryClient {
    return new QueryClient({
    defaultOptions: {
    queries: {
    staleTime: 30_000, // an answer counts as fresh for 30 s: no new request in that time
    gcTime: 5 * 60_000, // an answer that no screen uses stays in the cache for 5 minutes
    retry: shouldRetry,
    retryDelay: (attempt, error) =>
    error instanceof ApiError && error.retryAfter ? error.retryAfter * 1000 : 500 * 2 ** attempt,
    refetchOnWindowFocus: true,
    },
    mutations: { retry: false }, // a change is never sent twice by itself
    },
    });
    }

    failureCount compte les échecs jusqu’ici, à partir de 0. ApiError, du module 2, lit déjà l’en-tête Retry-After dans retryAfter. 500 * 2 ** attempt donne 1 000 ms après le premier échec et 2 000 ms après le deuxième. refetchOnWindowFocus: true est la valeur par défaut de TanStack Query; cette ligne rend le choix visible.

  2. Testez la règle sans navigateur. Créez src/api/queryClient.test.ts :

    src/api/queryClient.test.ts
    import { expect, test } from 'vitest';
    import { ApiError } from './client';
    import { shouldRetry } from './queryClient';
    test('retries a busy server or a lost connection, at most twice', () => {
    expect(shouldRetry(0, new ApiError(503, 'unavailable', 'Busy.'))).toBe(true);
    expect(shouldRetry(1, new ApiError(0, 'network_error', 'No answer.'))).toBe(true);
    expect(shouldRetry(2, new ApiError(503, 'unavailable', 'Busy.'))).toBe(false);
    });
    test('never retries an answer that will not change: 4xx', () => {
    expect(shouldRetry(0, new ApiError(404, 'not_found', 'No ticket.'))).toBe(false);
    expect(shouldRetry(0, new ApiError(422, 'invalid_request', 'Not valid.'))).toBe(false);
    });
  3. Exécutez toutes les vérifications avec npm test. Après les 21 vérifications de l’API simulée, Vitest affiche :

    Test Files 8 passed (8)
    Tests 19 passed (19)

    Les 5 nouveaux tests couvrent la règle des nouvelles tentatives (2) et le laboratoire de concurrence (3). L’erreur affiche « p », et les deux corrections affichent « pa ».

Voyez maintenant la règle en action. Gardez l’API simulée en mode --list flaky, ouvrez le bureau et choisissez pending (en attente) dans le filtre Status (statut). Dans l’essai de l’équipe du cours, la première requête pour ce filtre a reçu une 503 après 82 ms. Le bureau a renvoyé la même requête à 2086 ms, deux secondes plus tard, comme le demandait Retry-After. Il a reçu une 200. Pendant tout ce temps, la liste affichait les anciens résultats avec « Showing 50 tickets. Updating… » (50 billets affichés. Mise à jour…). L’agent n’a vu aucune erreur.

Arrêtez ensuite l’API simulée et démarrez-la avec --list fail, où chaque réponse de liste est une 503. Choisissez de nouveau un filtre. Dans l’essai de l’équipe du cours, le bureau a envoyé trois requêtes : à 14 ms, 2079 ms et 4145 ms. Après la troisième 503, il s’arrête et affiche l’erreur :

La liste des billets avec le filtre Status (statut) réglé sur pending (en attente). Au lieu des lignes, un encadré rouge indique : The ticket service is not available. Try again in a few seconds. (Le service de billets est indisponible. Réessayez dans quelques secondes.) Sous le texte se trouve un bouton bleu, Try again (réessayer).
Après deux nouvelles tentatives, le bureau s'arrête et explique ce qui s'est passé, dans les mots de l'API. Un bouton permet de réessayer. L’image est en anglais.

Redémarrez l’API simulée sans mode avant de continuer : npm run api.

Quand utiliser les nouvelles tentatives et l’annulation, et à quel coût

Section intitulée « Quand utiliser les nouvelles tentatives et l’annulation, et à quel coût »

Les nouvelles tentatives aident pour les problèmes courts : un serveur qui redémarre, un moment occupé, un téléphone brièvement déconnecté. Elles coûtent du temps : avec --list fail, l’agent a attendu environ 4.2 secondes avant l’erreur. Elles augmentent aussi la charge d’un serveur déjà occupé. C’est pourquoi le bureau attend et s’arrête après deux nouvelles tentatives. Ne réessayez pas quand la réponse ne peut pas changer, et ne réessayez jamais une modification automatiquement.

L’annulation aide quand une nouvelle requête rend une ancienne inutile : champs de recherche, filtres, passage rapide entre les billets. Elle exige que la fonction de requête accepte le signal, comme toutes les fonctions dans api/tickets.ts. Elle ne peut pas annuler le travail que le serveur a déjà fait. Annuler un PATCH dans le navigateur n’annule pas la modification sur le serveur. Le bureau n’annule donc jamais les modifications.

L’API de billets peut aussi répondre 429 Too Many Requests (trop de requêtes) quand un bureau envoie trop de requêtes. Elle inclut alors un en-tête Retry-After. Une 429 est une réponse 4xx, mais elle est temporaire : une deuxième tentative après l’attente peut fonctionner. Modifiez shouldRetry pour réessayer aussi après une 429. Ajoutez une ligne de test qui le prouve. Avant d’exécuter les tests, prédisez : le test « never retries an answer that will not change : 4xx » réussit-il encore? Son nom signifie « ne réessaie jamais une réponse qui ne changera pas : 4xx ».

Afficher la réponse
src/api/queryClient.ts
const temporary = error.code === 'network_error' || error.status === 503;
const temporary = error.code === 'network_error' || error.status === 503 || error.status === 429;
src/api/queryClient.test.ts (a new test at the end)
test('retries 429 Too Many Requests', () => {
expect(shouldRetry(0, new ApiError(429, 'rate_limited', 'Too many requests.', [], 2))).toBe(true);
});

npx vitest run src/api/queryClient.test.ts --reporter=verbose affiche :

✓ src/api/queryClient.test.ts > retries a busy server or a lost connection, at most twice 1ms
✓ src/api/queryClient.test.ts > never retries an answer that will not change: 4xx 0ms
✓ src/api/queryClient.test.ts > retries 429 Too Many Requests 0ms
Test Files 1 passed (1)
Tests 3 passed (3)

Oui, le test 4xx réussit encore, car il vérifie seulement 404 et 422. Mais son nom et le commentaire sur shouldRetry en disent maintenant trop : « never for 4xx » (jamais pour les 4xx) n’est plus vrai. Remplacez-les par « never for other 4xx answers » (jamais pour les autres réponses 4xx). retryDelay n’a pas besoin de changer : il attend déjà le délai de Retry-After, ici 2 secondes. Cela ne fait pas partie de l’instantané du projet; gardez cette modification ou annulez-la, à votre choix.

Erreur courante

Chaque erreur entraîne une nouvelle tentative, et l'agent attend pour une 404

Symptôme : Tomás retire la règle des nouvelles tentatives du bureau : « La bibliothèque réessaie toute seule. Pourquoi écrire notre propre règle? » Un agent ouvre maintenant un lien vers un billet qui n’existe pas, http://localhost:5173/#/tickets/T-99999. L’écran affiche longtemps « Loading T-99999… » (chargement de T-99999…) avant d’indiquer « There is no ticket T-99999. » (le billet T-99999 n’existe pas).

L’équipe du cours a mesuré les deux versions dans Chromium, de l’ouverture du lien à l’erreur à l’écran :

Version Requêtes pour T-99999 Erreur à l’écran après
Nouvelles tentatives par défaut de TanStack Query 4 7.3 s
shouldRetry du bureau 1 0.1 s

Cause : Par défaut, TanStack Query réessaie chaque requête échouée 3 fois, avec des attentes de 1, 2 et 4 secondes. La bibliothèque ne peut pas savoir quelles erreurs sont temporaires. Une 404 ne l’est pas.

Correction : donnez à la bibliothèque la règle de votre API, comme le fait shouldRetry. Réessayez seulement pour network_error et 503 (et 429, si vous avez fait l’exercice), au plus deux fois. Ne réessayez jamais les autres réponses 4xx.

Conséquence en IA : Les points de terminaison d’IA répondent souvent 4xx pour une requête qui ne fonctionnera jamais. Par exemple : une requête trop longue, du contenu bloqué ou un quota quotidien épuisé. Réessayer fait perdre du temps à l’agent et, sur un service payant, de l’argent. Réessayez seulement ce qu’une deuxième tentative peut corriger.

Vérifiez votre compréhension

Prédisez : dans le laboratoire de concurrence, un réseau lent retarde chaque réponse de 1 seconde. Avec l'effet sans nettoyage, quels résultats l'écran affiche-t-il après que l'agent tape « parcel »? Et avec TanStack Query?

Afficher la réponse

Avec l’effet sans nettoyage, il affiche encore les résultats pour « p ». Chaque réponse arrive 1 seconde plus tard, mais l’ordre d’arrivée ne change pas. « p » demande encore environ 900 ms de traitement serveur, contre environ 170 ms pour « parcel ». Sa requête part en premier, mais arrive en dernier, et la dernière réponse reste à l’écran.

Avec TanStack Query, il affiche « parcel ». L’ordre d’arrivée n’a pas d’importance. Chaque nouvelle lettre crée une nouvelle clé, l’ancienne requête est annulée. Seule la copie associée à la clé du champ s’affiche.

Vérifiez votre compréhension

Pour chaque réponse, le bureau réessaie-t-il, et pourquoi? (a) aucune réponse, le Wi-Fi s'est déconnecté; (b) 503 avec Retry-After : 2; (c) 404 pour T-99999; (d) 422 parce que le filtre de statut est « urgent »; (e) une 503 pour le PATCH qui modifie un statut.

Afficher la réponse
  • (a) Oui, jusqu’à 2 nouvelles tentatives : le réseau peut revenir en une seconde.
  • (b) Oui, après 2 secondes, comme le demande le serveur; au plus 2 nouvelles tentatives, puis une erreur avec Try again (réessayer).
  • (c) Non : le billet n’existera pas à la prochaine tentative.
  • (d) Non : « urgent » n’est un statut valide à aucune tentative. Il faut corriger la requête, pas attendre.
  • (e) Non : c’est une modification, et le bureau ne l’envoie jamais deux fois automatiquement (mutations: { retry: false }). L’agent voit l’erreur et décide.

Vérifiez votre compréhension

Teodor construit la clé de la liste comme ['tickets', 'list'], sans le filtre. Que se passe-t-il quand l'agent tape « parcel »?

Afficher la réponse

Toutes les recherches partagent une copie. Quand le filtre change, la clé reste la même, donc le cache ne récupère rien. La copie reste fraîche pendant 30 secondes, et l’écran conserve les résultats de la première recherche. Même après une nouvelle récupération, la fonction de requête utilise le filtre qu’elle a vu. Rien n’annule une ancienne requête. Une clé doit contenir tout ce qui change la réponse : ici, le texte de recherche et les deux filtres.

Récapitulatif

  • Une copie dans le cache est récupérée, fraîche pendant 30 secondes, puis périmée. Elle s’affiche immédiatement. Elle est récupérée de nouveau quand un écran l’ouvre ou que la fenêtre reprend le focus. L’invalidation la rend périmée immédiatement après une modification. Une copie inutilisée est supprimée après 5 minutes.
  • Sans nettoyage, une ancienne réponse peut arriver en dernier et remplacer une réponse plus récente. Dans le laboratoire de concurrence, l’effet sans nettoyage affichait les résultats de « p » sous « parcel » 10 fois sur 10.
  • Une clé doit contenir tout ce qui change la réponse. Chaque recherche crée une nouvelle clé, et l’ancienne requête est annulée par son signal. La recherche du bureau a fermé 5 de ses 6 requêtes avant leur fin.
  • Réessayez seulement ce qu’une deuxième tentative peut corriger : aucune réponse et 503, après Retry-After, au plus deux fois. Ne réessayez jamais les autres réponses 4xx ni une modification. Les nouvelles tentatives par défaut de la bibliothèque ont fait durer une 404 7.3 secondes.
  • npm test : 19 tests Vitest, après les 21 de l’API simulée.

Ensuite, la liste charge une page à la fois, et le bureau modifie les billets. Il ajoute une réponse, change un statut et crée un nouveau billet qui n’est jamais enregistré deux fois.

Leçon suivante : Pagination et formulaires