# Les lectures d'un écran

Un écran, un aller-retour : le patron à suivre et ce qu'il ne faut pas faire.


Entre l'application et la base, chaque appel coûte une cinquantaine de millisecondes. Un écran qui fait quarante-cinq appels met plus de deux secondes à s'afficher. Ces règles ramènent ce nombre à un.

:::note[Exemples de code]
Les exemples utilisent un client générique `db` : ils illustrent la règle, pas un client précis. Ironlane évolue vers une application Next.js sur PostgreSQL seul ; les règles restent les mêmes, les noms d'appel changeront. En cours de construction.
:::

:::note[En bref]
- **LECT-01** · [Lisez la base une seule fois par écran](#lect-01--lisez-la-base-une-seule-fois-par-écran)
- **LECT-02** · [Lancez en parallèle ce qui est indépendant](#lect-02--lancez-en-parallèle-ce-qui-est-indépendant)
- **LECT-03** · [Ne lisez jamais dans une boucle](#lect-03--ne-lisez-jamais-dans-une-boucle)
- **LECT-04** · [Comptez, sommez et paginez côté serveur](#lect-04--comptez-sommez-et-paginez-côté-serveur)
- **LECT-05** · [N'appelez pas une fonction SQL pour chaque ligne](#lect-05--nappelez-pas-une-fonction-sql-pour-chaque-ligne)
- **LECT-06** · [Mettez la société dans la clé de la mémoire](#lect-06--mettez-la-société-dans-la-clé-de-la-mémoire)
- **LECT-07** · [Mesurez avant d'optimiser](#lect-07--mesurez-avant-doptimiser)
- **LECT-08** · [Répondez au clic tout de suite](#lect-08--répondez-au-clic-tout-de-suite)
:::

## Lire la base

### LECT-01 · Lisez la base une seule fois par écran

:::tip[Règle]
Un écran appelle une seule fonction SQL, qui rend tout ce qu'il affiche. Chaque appel entre l'application et la base coûte environ cinquante millisecondes, même pour une fonction vide.
:::

**Pourquoi.** Un écran qui fait quarante-cinq appels met plus de deux secondes à s'afficher avant même de calculer quoi que ce soit.

<div class="avant-apres">

```ts title="À éviter"
// app/suivi/page.tsx
const lignes = await db.lire("operation").select("*");
const compteurs = await db.appeler("compteurs_du_suivi");
const alertes = await db.appeler("alertes_du_suivi");
```

```ts title="À faire"
// app/suivi/page.tsx
const { data } = await db.appeler("page_suivi", { p_annee: annee, p_suivi: suivi });
const { lignes, compteurs, alertes } = data;
```

</div>

<span class="puce outil">Outil</span> Chaque route a un budget de lectures ; un contrôle compte les appels réels et refuse la mise en ligne s'il est dépassé.

**Voir aussi.** [Nommer les fonctions d'écran](/regles/nommage-base/)

### LECT-02 · Lancez en parallèle ce qui est indépendant

:::tip[Règle]
Ce qui ne dépend de rien part dans un seul `Promise.all`.
:::

<div class="avant-apres">

```ts title="À éviter"
const page = await db.appeler("page_suivi", { p_annee: annee });
const portefeuille = await db.appeler("mon_portefeuille");
```

```ts title="À faire"
const [{ data: page }, { data: portefeuille }] = await Promise.all([
  db.appeler("page_suivi", { p_annee: annee }),
  db.appeler("mon_portefeuille"),
]);
```

</div>

<span class="puce relecture">Relecture</span> Un `await` de plus sur une lecture est un aller-retour de plus.

### LECT-03 · Ne lisez jamais dans une boucle

:::tip[Règle]
Aucun `await` de lecture dans une boucle, un `map` ou un composant enfant. Regroupez la lecture côté base.
:::

**Pourquoi.** Chaque tour de boucle est un aller-retour : quarante-cinq opérations, quarante-cinq appels.

<div class="avant-apres">

```ts title="À éviter"
for (const op of operations) {
  const { data } = await db.lire("piece").select("*").eq("operation_id", op.id);
}
```

```ts title="À faire"
// une lecture regroupée côté base (nom de fonction donné en exemple)
const { data } = await db.appeler("pieces_des_operations", {
  p_ids: operations.map((o) => o.id),
});
```

</div>

<span class="puce outil">Outil</span> Le budget de lectures de la route échoue.

<span class="puce relecture">Relecture</span> Seule la page lit la base : les composants enfants reçoivent leurs données.

### LECT-04 · Comptez, sommez et paginez côté serveur

:::tip[Règle]
Un total se calcule dans la base. Une longue liste se pagine avec son total exact.
:::

**Pourquoi.** L'API tronque à mille lignes sans erreur : un total calculé dans le navigateur est faux, et personne ne le voit.

<div class="avant-apres">

```ts title="À éviter"
const { data } = await db.lire("piece").select("montant_ht");
const total = data.reduce((s, p) => s + p.montant_ht, 0);  // faux au-delà de 1000 lignes
```

```ts title="À faire"
const { data: total } = await db.appeler("total_des_pieces", { p_annee: annee });
```

</div>

<span class="puce relecture">Relecture</span> Une liste entière se lit par la fonction qui lève si le compte ne tombe pas.

### LECT-05 · N'appelez pas une fonction SQL pour chaque ligne

:::tip[Règle]
Dans une longue liste, calculez une fois, puis joignez.
:::

<div class="avant-apres">

```sql title="À éviter"
select l.*, taux_reel(l.id) from ligne l;  -- une exécution par ligne
```

```sql title="À faire"
select l.*, t.valeur from ligne l join taux t on t.ligne_id = l.id;  -- calculé une fois
```

</div>

<span class="puce relecture">Relecture</span> Et jamais de vue en union dans une sous-requête corrélée : agrégez une fois, à part.

## Garder en mémoire

### LECT-06 · Mettez la société dans la clé de la mémoire

:::tip[Règle]
Une mémoire de lecture a une clé qui porte la société. Une page gardée en cache se vide à chaque écriture qui la change, par une seule fonction d'invalidation.
:::

**Pourquoi.** Sans la société dans la clé, un compte lit la liste d'un autre.

<div class="avant-apres">

```ts title="À éviter"
memo("clients", () => lireLesClients());
```

```ts title="À faire"
memo(["clients", societeId], () => lireLesClients());
```

</div>

<span class="puce relecture">Relecture</span> Une page qui lit l'adresse, un cookie ou la session sort du cache.

## Mesurer

### LECT-07 · Mesurez avant d'optimiser

:::tip[Règle]
On mesure à travers la fonction entière, avec la session d'un vrai compte. On juge la vitesse sur des mesures de production prises en transaction annulée.
:::

**Pourquoi.** La copie locale compare deux versions, elle ne donne pas les temps de la production.

<div class="avant-apres">

```json title="À éviter"
{ "/suivi": "pas de budget, on verra" }
```

```json title="À faire"
{ "/suivi": { "lectures": 1 } }
```

</div>

<span class="puce outil">Outil</span> Le budget de lectures de chaque route est dans `tests/vitesse.json` ; ajouter une lecture, c'est modifier ce budget et le justifier.

### LECT-08 · Répondez au clic tout de suite

:::tip[Règle]
Un clic donne un retour visuel en moins de cent cinquante millisecondes. Aucun écran n'a à le refaire.
:::

<span class="puce outil">Outil</span> Un seul composant du cadre pose l'état « en route » au clic sur un lien ou un envoi.

## Référence rapide

| Règle | À retenir | Tenue par |
| --- | --- | --- |
| **LECT-01** | Lisez la base une seule fois par écran | Outil |
| **LECT-02** | Lancez en parallèle ce qui est indépendant | Relecture |
| **LECT-03** | Ne lisez jamais dans une boucle | Outil, Relecture |
| **LECT-04** | Comptez, sommez et paginez côté serveur | Relecture |
| **LECT-05** | N'appelez pas une fonction SQL pour chaque ligne | Relecture |
| **LECT-06** | Mettez la société dans la clé de la mémoire | Relecture |
| **LECT-07** | Mesurez avant d'optimiser | Outil |
| **LECT-08** | Répondez au clic tout de suite | Outil |

## Voir aussi

- [L'architecture](/ingenierie/architecture/)
- [Les tests et les contrôles](/ingenierie/tests/)
