Aller au contenu
English

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.

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 mainEnviron 50 minutes

Ce que vous devez savoir

Ce qu’il vous faut sur votre ordinateur

  • Le bureau à la fin de Bases de React : npm test affiche Tests 8 passed (8) (8 tests réussis).
  • L’API simulée dans le premier terminal (npm run api), et npm run dev dans 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.

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 :

Fenêtre de terminal
npm run api -- --list fail

Le -- 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) :

Fenêtre de terminal
curl -i "http://127.0.0.1:8100/v1/tickets?limit=50"
HTTP/1.1 503 Service Unavailable
X-Request-ID: c80237ea-ca11-4e3f-a2c9-2702868cb8cb
Content-Type: application/json
Retry-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 :

La liste Tickets avec un encadré rouge : Impossible de charger les billets. L'API a répondu 503. En dessous : Appuyez sur Search pour charger les billets. Aucun bouton ne permet de réessayer.
Avant : le bureau élimine la phrase de l'API et affiche un code d'état. L’image est en anglais.

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.

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.

Le cadre de l'application, main.tsx et App.tsx, en haut, utilise features/. Ce dossier contient tickets/ (TicketList, TicketRow, TicketFilters) et jobs/ (NewTicketForm). features/ utilise trois dossiers sous lui : ui/ (StatusBadge, ErrorMessage), lib/ (outils qui ne connaissent rien aux billets) et api/ (client.ts, tickets.ts, types.ts). ui/ utilise seulement les types de api/. api/ appelle l'API des billets en HTTP avec fetch. Une note rouge : jamais dans l'autre sens; api/, ui/ et lib/ n'importent rien de features/.
Quatre dossiers et un seul sens. Seul api/ communique avec l'API des billets; rien sous features/ n'importe depuis ce dossier.
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 :

src/api/client.ts (part)
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.

  1. Arrêtez npm run dev avec Ctrl+C. Gardez l’API simulée dans son mode --list fail.

  2. 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/jobs
    mv src/types.ts src/api/types.ts
    mv 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.ts
  3. Créez le client API src/api/client.ts et ses tests src/api/client.test.ts : les fichiers de l’instantané end-of-m02. Le client est présenté dans l’encadré ci-dessous.

  4. Créez src/api/tickets.ts et src/api/tickets.test.ts à partir de l’instantané. tickets.ts contient 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.

  5. Créez src/ui/ErrorMessage.tsx à partir de l’instantané : une erreur en mots, avec un bouton Try again facultatif.

  6. Modifiez les importations. Dans src/ui/StatusBadge.tsx, importez depuis '../api/types'. Dans src/test/fakeApi.ts, importez depuis '../api/types'. Dans src/App.tsx, importez depuis './features/jobs/NewTicketForm' et './features/tickets/TicketList'. Dans src/features/tickets/TicketFilters.tsx, importez depuis '../../api/types'.

  7. Remplacez src/features/jobs/NewTicketForm.tsx et son test par les fichiers de l’instantané. Le formulaire appelle maintenant createTicket et affiche le message de l’ApiError.

  8. Remplacez src/features/tickets/TicketRow.tsx, TicketList.tsx et TicketList.test.tsx par les versions dans l’encadré ci-dessous.

  9. Vérifiez les types : npx tsc --noEmit. La commande n’affiche rien quand chaque importation est correcte. Un chemin incorrect affiche error TS2307: Cannot find module (module introuvable), avec le fichier et la ligne.

  10. Exécutez les tests : npm test. La fin affiche Test Files 4 passed (4) (4 fichiers de tests réussis) et Tests 9 passed (9) (9 tests réussis).

  11. Relancez npm run dev et appuyez sur Search.

Le client et la liste après cette leçon
src/api/client.ts
// 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;
}
src/features/tickets/TicketRow.tsx
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>
);
}
src/features/tickets/TicketList.tsx
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>
);
}
src/features/tickets/TicketList.test.tsx
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.');
});
La liste Tickets avec un encadré rouge : Le service de billets est indisponible. Réessayez dans quelques secondes. Dans l'encadré, un bouton Try again.
Après : la phrase de l'API elle-même, et une façon de reprendre. L’image est en anglais.

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é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/.

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.

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.

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/ utilise api/, ui/ et lib/; rien n’importe depuis features/.
  • Un seul client API, apiFetch, transforme chaque réponse d’erreur en ApiError avec le code, la phrase de l’API, les champs et Retry-After. L’agent lit maintenant « Le service de billets est indisponible. Réessayez dans quelques secondes. » au lieu de « 503 ».
  • fetch n’échoue pas sur une erreur HTTP; la vérification response.ok du 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