Organiser par responsabilité
- Leçon 6
- 50 min
- Module 2 : Composants et structure de l'application
Où nous en sommes
Dans la leçon précédente, nous avons construit le bureau avec des composants React. Il fonctionne, mais tous ses fichiers sont côte à côte, et deux composants lisent chacun à leur façon les erreurs de l'API. Quand l'API change, il faut corriger à plusieurs endroits. Dans cette leçon, nous donnons une place à chaque responsabilité, avec un seul client API pour toutes les requêtes. Une cuisine de restaurant où une seule personne appelle les fournisseurs montre pourquoi.
Leçon 6 sur 19 · Architecture frontend et performance des applications d'IAOrganiser par responsabilité
1. Premiers pas avec le Web
2. Composants et structure de l'application
3. Récupération des données et gestion de l'état
4. États d'interaction propres à l'IA
5. Performance et capacité de croissance
6. Sécurité, accessibilité et remise du travail
Ce que vous saurez faire
Donnez à chaque partie du code du bureau une place bien définie. Les éléments réutilisables de l’écran, les écrans des fonctionnalités, le client API et les types de l’API ont chacun leur dossier. Ainsi, un changement dans la réponse de l’API demande une seule modification, dans un seul fichier.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les composants, les props, l’état et la remontée de l’état, vus dans Bases de React.
- La structure des erreurs de l’API des billets de soutien,
{"error": {"code", "message", "request_id", "fields"}}, vue dans Validation et réponses d’erreur et Installer le bureau des tickets. import(importer) etexport(exporter) entre fichiers, vus dans L’essentiel de JavaScript.
Ce qu’il vous faut sur votre ordinateur
- Le bureau à la fin de Bases de React :
npm testafficheTests 8 passed (8)(8 tests réussis). - L’API simulée dans le premier terminal (
npm run api), etnpm run devdans le deuxième.
Testé sur macOS (Apple silicon) avec Node.js 24.18.0. Les commandes de fichiers pour Windows (PowerShell) sont fournies, mais n’ont pas été exécutées.
Une seule personne appelle les fournisseurs
Section intitulée « Une seule personne appelle les fournisseurs »Imaginez la cuisine d’un restaurant. Les cuisiniers préparent les plats, les serveurs les servent, et une personne, l’acheteur, commande auprès des fournisseurs. Quand un fournisseur change son formulaire de commande, seul l’acheteur doit apprendre à l’utiliser. Quand une livraison arrive en retard, l’acheteur le dit aux cuisiniers avec les mêmes mots simples : « Pas de poisson avant jeudi. »
Imaginez maintenant que chaque cuisinier appelle les fournisseurs. Chacun pose ses questions et comprend les réponses à sa façon. Quand le poisson n’arrive pas, un cuisinier entend « erreur 503 », un autre n’entend rien. Un troisième écrit la mauvaise date au tableau.
Le problème : deux composants, deux façons de lire une erreur
Section intitulée « Le problème : deux composants, deux façons de lire une erreur »Le bureau de Bases de React ressemble à cette cuisine où chaque cuisinier appelle. TicketList et NewTicketForm appellent tous deux des fonctions dans src/api.ts. Mais ces fonctions traitent les erreurs de deux façons différentes. loadTickets lance une Error avec le code d’état. sendTicket renvoie une chaîne de caractères au lieu du billet. Les composants les transforment ensuite en deux textes différents.
Faites échouer la liste volontairement et observez. Arrêtez l’API simulée avec Ctrl+C, puis démarrez-la dans un mode qui fait échouer chaque requête de liste :
npm run api -- --list failLe -- transmet --list fail à l’API simulée. Demandez maintenant à l’API ce qu’elle répond, dans le deuxième terminal (Windows : curl.exe au lieu de curl) :
curl -i "http://127.0.0.1:8100/v1/tickets?limit=50"HTTP/1.1 503 Service UnavailableX-Request-ID: c80237ea-ca11-4e3f-a2c9-2702868cb8cbContent-Type: application/jsonRetry-After: 2…
{"error":{"code":"unavailable","message":"The ticket service is not available. Try again in a few seconds.","request_id":"c80237ea-ca11-4e3f-a2c9-2702868cb8cb","fields":[]}}L’API dit exactement ce qui s’est passé, dans une phrase qu’un agent comprend. Elle indique aussi quand réessayer. L’en-tête Retry-After: 2 signifie « réessayez dans 2 secondes ». Appuyez maintenant sur Search (rechercher) dans le bureau :

Les agents de Grace ne savent pas ce que signifie 503. loadTickets perd la phrase de l’API, son code unavailable (indisponible) et l’en-tête Retry-After. Vous pourriez corriger loadTickets. Mais sendTicket a sa propre copie du même travail. Chaque requête ajoutée dans les leçons suivantes (un billet, une réponse, un brouillon, une tâche) demanderait une copie supplémentaire. Chaque copie risque de lire l’erreur différemment.
Il y a un deuxième problème, moins visible. Tous les fichiers se trouvent côte à côte dans src/. Aujourd’hui, il y en a 13, plus le dossier test/. À la fin de ce cours, le projet compte 60 fichiers dans src/. Dans un seul dossier sans sous-dossiers, personne ne voit quels fichiers communiquent avec l’API et lesquels dessinent l’écran.
L’idée : une place pour chaque responsabilité
Section intitulée « L’idée : une place pour chaque responsabilité »Une responsabilité est un travail qu’une seule partie du code accomplit. Le bureau a quatre sortes de travaux, chacune dans son dossier :
| Dossier | Son travail | Ce qu’il connaît | Dans le bureau actuel |
|---|---|---|---|
api/ |
Communiquer en HTTP avec l’API des billets : l’adresse, le JSON, la structure des erreurs. Aussi les types partagés des données de l’API. | Le contrat de l’API. Rien sur l’écran. | client.ts, tickets.ts, types.ts |
ui/ |
Interface réutilisable : petits éléments de l’écran que toute fonctionnalité peut utiliser. | Seulement leurs props. | StatusBadge.tsx, ErrorMessage.tsx |
features/ |
Logique des fonctionnalités : les écrans qui font une chose pour l’utilisateur, avec leur état. Un dossier par fonctionnalité. | Billets, filtres, formulaires; utilise api/, ui/, lib/. |
tickets/, jobs/ |
lib/ |
Petits outils qui ne connaissent rien aux billets. | Seulement React et le navigateur. | vide jusqu’à la prochaine leçon |
Ajoutez ensuite une règle, le sens des importations : un fichier peut importer depuis un dossier plus bas dans l’image, jamais plus haut. features/ utilise api/, ui/ et lib/. ui/ utilise seulement les types de api/. api/ n’utilise rien dans l’application. Le client API est l’acheteur : c’est le seul code qui appelle l’API des billets.
Description textuelle du diagramme
En haut se trouve le cadre de l’application : main.tsx démarre React et App.tsx organise la page. Il utilise features/, qui contient les écrans des billets et le formulaire de création d’un billet. Les fonctionnalités utilisent trois dossiers plus bas : ui/ pour les éléments réutilisables comme StatusBadge et ErrorMessage. Elles utilisent aussi lib/ pour les outils généraux, et api/ pour le client, les requêtes et les types. ui/ utilise seulement les types de api/. Seul api/ appelle l’API des billets, avec fetch. Les importations ne remontent jamais : api/, ui/ et lib/ n’importent rien de features/.
Pourquoi ce sens? Un dossier inférieur ne doit pas dépendre d’un dossier supérieur. Vous pouvez ainsi modifier un écran sans casser le client API. Vous pouvez aussi tester api/ sans React et utiliser StatusBadge sur une page qui n’existe pas encore. La règle rend aussi les cycles impossibles. Si ui/ importait depuis features/ et features/ depuis ui/, un changement dans l’un pourrait casser l’autre.
Un petit exemple : une requête échouée passe par le client
Section intitulée « Un petit exemple : une requête échouée passe par le client »Le nouveau client a une fonction que chaque requête utilise, apiFetch, et une classe d’erreur, ApiError. Voici la partie qui lit une réponse d’erreur :
const body = await response.json().catch(() => null);if (!response.ok) { const e = body?.error; const retry = response.headers.get('Retry-After'); throw new ApiError( response.status, e?.code ?? 'unknown_error', e?.message ?? `The ticket service answered ${response.status}.`, e?.fields ?? [], retry ? Number(retry) : null, );}Suivez l’erreur 503 ci-dessus dans ce code, avec chaque valeur visible :
| Étape | Valeur |
|---|---|
response.ok |
false (faux; état 503) |
e |
{ code: "unavailable", message: "The ticket service is not available. Try again in a few seconds.", request_id: "c80237ea-…", fields: [] } |
retry |
"2" |
L’erreur que apiFetch lance |
ApiError avec status 503, code "unavailable", message contenant la phrase de l’API, fields [], retryAfter 2 |
Ce que fait TicketList |
conserve l’erreur dans l’état et affiche <ErrorMessage error={error} onRetry={search} /> |
| Ce que l’agent voit | la phrase de l’API et un bouton Try again (réessayer) |
?. et ?? protègent le client quand la réponse ne suit pas la structure d’erreur de l’API. Par exemple, un serveur mandataire peut répondre avec une page HTML. body?.error donne undefined (non défini) au lieu de provoquer un plantage, puis ?? choisit le texte de remplacement. Si le serveur ne répond pas du tout, fetch échoue lui-même. Le client transforme cet échec en ApiError avec le code network_error (erreur réseau) et une phrase pour l’agent. Chaque fonctionnalité reçoit maintenant le même type d’erreur, quel que soit le problème.
Organiser le bureau
Section intitulée « Organiser le bureau »-
Arrêtez
npm run devavec Ctrl+C. Gardez l’API simulée dans son mode--list fail. -
Créez les dossiers et déplacez les fichiers. Les déplacements ne modifient pas les fichiers; les importations ne fonctionnent plus jusqu’à l’étape 6.
Fenêtre de terminal mkdir -p src/api src/ui src/features/tickets src/features/jobsmv src/types.ts src/api/types.tsmv src/StatusBadge.tsx src/ui/mv src/TicketList.tsx src/TicketList.test.tsx src/TicketRow.tsx src/TicketFilters.tsx src/features/tickets/mv src/NewTicketForm.tsx src/NewTicketForm.test.tsx src/features/jobs/rm src/api.ts src/api.test.tsFenêtre de terminal New-Item -ItemType Directory -Force src/api, src/ui, src/features/tickets, src/features/jobsMove-Item src/types.ts src/api/types.tsMove-Item src/StatusBadge.tsx src/ui/Move-Item src/TicketList.tsx, src/TicketList.test.tsx, src/TicketRow.tsx, src/TicketFilters.tsx src/features/tickets/Move-Item src/NewTicketForm.tsx, src/NewTicketForm.test.tsx src/features/jobs/Remove-Item src/api.ts, src/api.test.ts -
Créez le client API
src/api/client.tset ses testssrc/api/client.test.ts: les fichiers de l’instantanéend-of-m02. Le client est présenté dans l’encadré ci-dessous. -
Créez
src/api/tickets.tsetsrc/api/tickets.test.tsà partir de l’instantané.tickets.tscontient une fonction pour chaque requête utilisée par le bureau. Il y en a cinq : la liste, un billet, un nouveau billet, une réponse et un changement d’état. Les écrans utilisent les trois dernières dans le module 3. -
Créez
src/ui/ErrorMessage.tsxà partir de l’instantané : une erreur en mots, avec un bouton Try again facultatif. -
Modifiez les importations. Dans
src/ui/StatusBadge.tsx, importez depuis'../api/types'. Danssrc/test/fakeApi.ts, importez depuis'../api/types'. Danssrc/App.tsx, importez depuis'./features/jobs/NewTicketForm'et'./features/tickets/TicketList'. Danssrc/features/tickets/TicketFilters.tsx, importez depuis'../../api/types'. -
Remplacez
src/features/jobs/NewTicketForm.tsxet son test par les fichiers de l’instantané. Le formulaire appelle maintenantcreateTicketet affiche le message de l’ApiError. -
Remplacez
src/features/tickets/TicketRow.tsx,TicketList.tsxetTicketList.test.tsxpar les versions dans l’encadré ci-dessous. -
Vérifiez les types :
npx tsc --noEmit. La commande n’affiche rien quand chaque importation est correcte. Un chemin incorrect afficheerror TS2307: Cannot find module(module introuvable), avec le fichier et la ligne. -
Exécutez les tests :
npm test. La fin afficheTest Files 4 passed (4)(4 fichiers de tests réussis) etTests 9 passed (9)(9 tests réussis). -
Relancez
npm run devet appuyez sur Search.
Le client et la liste après cette leçon
// The one place that talks HTTP to the ticket API: the address, JSON, and the error shape.
export const API_URL: string = import.meta.env.VITE_API_URL ?? 'http://127.0.0.1:8100';
/** An error answer of the API, with its stable code (the contract's error shape). */export class ApiError extends Error { constructor( readonly status: number, readonly code: string, message: string, readonly fields: string[] = [], readonly retryAfter: number | null = null, ) { super(message); this.name = 'ApiError'; }}
/** Sends a request and gives back the JSON answer, or throws an ApiError. */export async function apiFetch<T>(path: string, init: RequestInit = {}): Promise<T> { let response: Response; try { response = await fetch(`${API_URL}${path}`, { ...init, headers: { ...(init.body ? { 'Content-Type': 'application/json' } : {}), ...init.headers }, }); } catch (error) { if ((error as Error).name === 'AbortError') throw error; throw new ApiError(0, 'network_error', 'The ticket service did not answer. Check your connection.'); } const body = await response.json().catch(() => null); if (!response.ok) { const e = body?.error; const retry = response.headers.get('Retry-After'); throw new ApiError( response.status, e?.code ?? 'unknown_error', e?.message ?? `The ticket service answered ${response.status}.`, e?.fields ?? [], retry ? Number(retry) : null, ); } return body as T;}import type { TicketSummary } from '../../api/types';import { StatusBadge } from '../../ui/StatusBadge';
/** One ticket in the list. */export function TicketRow({ ticket }: { ticket: TicketSummary }) { return ( <div className="row"> <span className="row-id">{ticket.ticket_id}</span> <span className="row-subject">{ticket.subject}</span> <span className="row-meta"> {ticket.customer_name} · {ticket.team} </span> <StatusBadge status={ticket.status} /> </div> );}import { useState } from 'react';import { listTickets } from '../../api/tickets';import type { TicketFilter, TicketPage } from '../../api/types';import { ErrorMessage } from '../../ui/ErrorMessage';import { TicketFilters } from './TicketFilters';import { TicketRow } from './TicketRow';
export const NO_FILTER: TicketFilter = { status: '', team: '', q: '' };
/** The first 50 tickets that match the filters. For now, it loads them when you press Search. */export function TicketList() { const [filter, setFilter] = useState<TicketFilter>(NO_FILTER); const [page, setPage] = useState<TicketPage | null>(null); const [error, setError] = useState<Error | null>(null);
async function search() { setError(null); try { setPage(await listTickets(filter, 50)); } catch (e) { setError(e as Error); } }
return ( <section className="list" aria-labelledby="list-heading"> <h2 id="list-heading">Tickets</h2> <TicketFilters value={filter} onChange={setFilter} onSearch={search} /> {error && <ErrorMessage error={error} onRetry={search} />} {page === null ? ( <p className="muted">Press Search to load the tickets.</p> ) : ( <> <p className="muted">{page.items.length === 0 ? 'No ticket matches.' : `Showing ${page.items.length} tickets.`}</p> <ul className="rows"> {page.items.map((t) => ( <li key={t.ticket_id}> <TicketRow ticket={t} /> </li> ))} </ul> </> )} </section> );}import { render, screen } from '@testing-library/react';import userEvent from '@testing-library/user-event';import { expect, test } from 'vitest';import { apiError, installFakeApi, json, ticket } from '../../test/fakeApi';import { TicketList } from './TicketList';
test('shows the tickets after Search', async () => { installFakeApi(() => json(200, { items: [ticket(1), ticket(2, { status: 'pending' })], next: null })); render(<TicketList />); await userEvent.click(screen.getByRole('button', { name: 'Search' })); expect(await screen.findByText('Ticket number 1')).toBeInTheDocument(); expect(screen.getByText('Pending')).toBeInTheDocument();});
test('shows the API’s error message', async () => { installFakeApi(() => apiError(503, 'unavailable', 'The ticket service is not available.')); render(<TicketList />); await userEvent.click(screen.getByRole('button', { name: 'Search' })); expect(await screen.findByRole('alert')).toHaveTextContent('The ticket service is not available.');});
L’agent lit maintenant la phrase de l’API. Arrêtez l’API simulée, relancez-la avec npm run api (mode normal), puis appuyez sur Try again. La liste affiche Showing 50 tickets. (50 billets affichés). Le composant de liste n’a rien appris sur HTTP pour faire cela. Il affiche seulement l’erreur fournie par le client, grâce à un élément d’interface que toute fonctionnalité peut utiliser.
Larkfield : ce que chaque dossier signifie pour l’équipe
Section intitulée « Larkfield : ce que chaque dossier signifie pour l’équipe »Amira est responsable de l’API des billets et de son contrat. Elle peut maintenant lire seulement src/api/ et vérifier que le bureau respecte le contrat. Cela comprend les chemins, les paramètres de requête, la structure des erreurs et Retry-After. Quand le contrat change, la modification va d’abord dans api/. TypeScript indique ensuite chaque fonctionnalité qui doit suivre.
Teodor pose la question évidente : « Pourquoi pas un dossier par type de fichier, comme components/, hooks/ et services/? » Beaucoup de projets font cela. Mais une fonctionnalité comme la liste des billets se retrouve alors dans quatre dossiers. Une modification touche les quatre. Les dossiers de fonctionnalités regroupent les fichiers qui changent ensemble. Les quatre dossiers proposés ici supportent aussi bien la croissance. À la fin de ce cours, src/ contient 60 fichiers : 23 dans features/, 12 dans api/, 9 dans labs/, 4 dans lib/, 4 dans test/, 3 dans ui/ et 5 au premier niveau. Chaque nouveau fichier a une place évidente.
Quand l’utiliser, et ce que cela coûte. Séparez par responsabilité dès que deux parties du code font le même travail, comme loadTickets et sendTicket. Faites-le aussi quand un nouveau fichier n’a pas de place évidente. Pour un projet de trois ou quatre fichiers, un seul dossier convient : la structure coûterait plus qu’elle ne ferait économiser. Les coûts sont réels. Les importations deviennent plus longues ('../../api/types'), et déplacer un fichier demande de modifier ses importations. L’équipe doit aussi s’entendre sur les règles et les respecter. La règle du sens des importations aide seulement quand tout le monde la suit.
Erreur courante
Un fetch rapide dans un composant
Symptôme : Tomás a besoin d’un billet pour une nouvelle vue. « Le client, c’est trop pour ça », dit-il, et il écrit fetch(url).then((r) => r.json()) dans le composant. Cela fonctionne pour T-80008. Pour un billet qui n’existe pas, la vue affiche un titre vide et aucune erreur.
Cause : fetch n’échoue pas sur une erreur HTTP. Pour T-99999, l’API répond 404 avec {"error":{"code":"not_found","message":"There is no ticket T-99999.",…}}. Le composant traite cet objet comme un billet, et ticket.subject vaut undefined. La vérification if (!response.ok) du client est exactement la ligne que ce raccourci saute.
Correction : chaque requête passe par api/. Ajoutez-y la fonction (getTicket existe déjà dans tickets.ts), puis laissez le composant afficher l’ApiError avec ErrorMessage. Une recherche rapide trouve les raccourcis : dans une fonctionnalité ou un fichier de ui/, fetch( ne devrait jamais apparaître.
Conséquence dans le travail en IA : les points de terminaison d’IA échouent plus souvent que les listes de billets. Un fournisseur dépasse le délai, une tâche finit parmi les messages non traités, un flux s’arrête. Si chaque composant lit les erreurs à sa façon, certains échecs produisent des écrans vides ou à moitié remplis. Un agent peut alors envoyer une réponse que personne n’a vérifiée.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Où va chacun de ces nouveaux fichiers : (a) une fonction qui transforme une date en « il y a 2 heures », (b) un composant Button aux couleurs du bureau, (c) la requête qui démarre un brouillon d'IA pour un billet, (d) le panneau qui affiche le brouillon avec un bouton Stop?
Afficher la réponse
(a) lib/ : il ne connaît rien aux billets. (b) ui/ : un élément réutilisable de l’écran que toute fonctionnalité peut utiliser. (c) api/, à côté des autres requêtes (plus tard dans le cours, c’est api/drafts.ts) : il communique en HTTP avec l’API des billets. (d) features/, dans un dossier pour la fonctionnalité de brouillon (features/draft/) : c’est un écran avec son propre état. Il utilise la requête de api/ et des éléments de ui/.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Expliquez pourquoi ui/ ne doit pas importer depuis features/. Qu'est-ce qui irait mal?
Afficher la réponse
ui/ contient des éléments que toute fonctionnalité peut utiliser. Si StatusBadge importait quelque chose de features/tickets/, il dépendrait d’une fonctionnalité précise. Vous ne pourriez pas l’utiliser sans la liste des billets, et une modification de la liste pourrait casser tous les badges. features/ importe déjà depuis ui/, donc les deux dossiers dépendraient l’un de l’autre : un cycle. Aucune partie ne pourrait alors changer ou être testée seule. Garder un seul sens permet aux dossiers inférieurs de rester petits et stables.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Prédisez : l'API simulée fonctionne avec --list fail, et l'agent appuie sur Search. Quel fichier lit l'en-tête Retry-After, quel fichier décide des mots à l'écran, et quel fichier les affiche?
Afficher la réponse
src/api/client.ts lit Retry-After et le place dans l’ApiError (retryAfter vaut 2). Les mots viennent de l’API elle-même : le client copie le message de l’API dans l’erreur. Il utilise son propre texte de remplacement seulement quand la réponse n’a pas de structure d’erreur. TicketList conserve l’erreur dans l’état, et src/ui/ErrorMessage.tsx affiche le message et le bouton Try again. Aucun composant ne lit les en-têtes HTTP.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Donnez à chaque responsabilité une place :
api/communique avec l’API des billets et contient les types partagés;ui/contient l’interface réutilisable;features/contient les écrans et leur état;lib/contient les outils généraux. - Les importations vont dans un seul sens :
features/utiliseapi/,ui/etlib/; rien n’importe depuisfeatures/. - Un seul client API,
apiFetch, transforme chaque réponse d’erreur enApiErroravec le code, la phrase de l’API, les champs etRetry-After. L’agent lit maintenant « Le service de billets est indisponible. Réessayez dans quelques secondes. » au lieu de « 503 ». fetchn’échoue pas sur une erreur HTTP; la vérificationresponse.okdu client fait ce travail, une seule fois.- La structure a un coût : des importations plus longues et des règles à respecter. Utilisez-la quand le code répète un travail ou qu’un nouveau fichier n’a pas de place évidente.
La liste attend encore un clic sur Search. Ensuite, elle se chargera seule et suivra la recherche pendant que l’agent tape. Cela introduit les effets de React, et un bogue où une ancienne réponse remplace une nouvelle.
Leçon suivante : Rendu et effets