Chapitre 7 – La Gestion des Erreurs

Clean Code — Chapitre 7 : La Gestion des Erreurs

Robert C. Martin consacre le chapitre 7 à un sujet que l'on traite souvent à la va-vite : la gestion des erreurs. Son message central est que le code de gestion d'erreur ne doit pas noyer la logique métier. Une bonne gestion des erreurs est aussi propre, lisible et intentionnelle que le reste du code. Ce chapitre est particulièrement pertinent en TypeScript et React, où les erreurs peuvent surgir partout — des appels API aux composants, en passant par la validation de données.

💡 L'idée clé du chapitre en une phrase :

« La gestion des erreurs est importante, mais si elle obscurcit la logique, c'est qu'elle est mal faite. »

  • Utilisez des exceptions, pas des codes de retour — les exceptions sont plus lisibles
  • Écrivez le try-catch en premier — pour définir le contrat d'erreur avant tout
  • Ne retournez pas null — créez des objets vides ou levez une exception
  • Ne passez pas null — protégez vos fonctions dès l'entrée
  • Créez des classes d'erreur contextuelles — pour enrichir le diagnostic
Les 5 règles du Chapitre 7 1. Exceptions pas de codes de retour 2. Try-Catch en premier définir le contrat d'abord 3. Classes d'erreur contexte enrichi 4. Pas de null en retour objet vide ou exception 5. Pas de null passé validation dès l'entrée Code lisible + robuste

1. Utilisez des exceptions, pas des codes de retour

Avant les exceptions, les développeurs signalaient les erreurs avec des codes de retour : si une fonction retournait -1 ou false, c'était qu'une erreur s'était produite. Le problème ? L'appelant devait penser à vérifier ce code à chaque appel. La logique métier se retrouvait noyée dans des if (result === false) imbriqués.

❌ Code de retour — à éviter

// TypeScript — style ancien, illisible
function getUser(id: string): User | null | -1 {
  if (!id) return -1;      // code d'erreur
  if (!db) return null;    // autre code d'erreur
  return db.find(id);
}

const result = getUser("abc");
if (result === -1) { /* erreur */ }
if (result === null) { /* autre erreur */ }
// La logique métier est invisible

✅ Exception — propre et explicite

// TypeScript — exceptions descriptives
function getUser(id: string): User {
  if (!id) throw new InvalidIdError(id);
  if (!db) throw new DatabaseError();
  return db.find(id);
}

try {
  const user = getUser("abc");
  // ICI : 100% logique métier, zéro bruit
} catch (e) {
  handleError(e); // séparé et isolé
}

🎯 Ce que ça change en TypeScript

TypeScript n'a pas de checked exceptions comme Java, mais les types vous permettent de documenter explicitement ce que retourne une fonction. Si une fonction peut échouer, utilisez une exception — pas un type de retour User | null | Error qui force l'appelant à gérer 3 cas à chaque appel.

2. Écrivez le try-catch en premier

Martin conseille de commencer par écrire le bloc try-catch avant même d'implémenter le corps de la fonction. Pourquoi ? Parce que cela vous force à définir d'abord quel est le contrat de la fonction en cas d'erreur — ce qui constitue une approche TDD (Test-Driven) de la gestion d'erreurs.

⏱️ Durée estimée pour adopter ce réflexe : 2-3 jours de pratique

// Étape 1 — Écrire le squelette avec try-catch d'abord
async function fetchUserProfile(userId: string): Promise<UserProfile> {
  try {
    // corps à remplir ensuite...
  } catch (e) {
    // Je définis déjà comment gérer les erreurs
    throw new FetchUserError(userId, e);
  }
}

// Étape 2 — Remplir la logique métier
async function fetchUserProfile(userId: string): Promise<UserProfile> {
  try {
    const response = await api.get(`/users/${userId}`);
    return UserProfileSchema.parse(response.data); // zod validation
  } catch (e) {
    if (e instanceof ZodError) {
      throw new InvalidUserDataError(userId, e.errors);
    }
    throw new FetchUserError(userId, e);
  }
}

Cette approche est particulièrement utile avec async/await en TypeScript, où les erreurs réseau, les erreurs de validation et les erreurs métier peuvent toutes surgir dans le même bloc try.

3. Créez des classes d'erreur contextuelles

Martin insiste : ne vous contentez pas de relancer un Error générique. Créez vos propres classes d'erreur qui expliquent le contexte de ce qui a échoué. En TypeScript, c'est simple et extrêmement utile pour le débogage.

Hiérarchie des erreurs — TypeScript Error (natif JS) message, stack AppError code, statusCode NetworkError url, statusCode ValidationError field, value NotFoundError resource, id AuthError userId, action

🏗️ Implémenter une hiérarchie d'erreurs propre en TypeScript

// errors/AppError.ts — Classe de base
export class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500,
    public readonly context?: Record<string, unknown>
  ) {
    super(message);
    this.name = this.constructor.name;
    // Important : corrige le prototype en TypeScript
    Object.setPrototypeOf(this, new.target.prototype);
  }
}

// errors/NetworkError.ts
export class NetworkError extends AppError {
  constructor(
    public readonly url: string,
    statusCode: number,
    cause?: unknown
  ) {
    super(
      `Échec de la requête vers ${url}`,
      "NETWORK_ERROR",
      statusCode,
      { url, cause }
    );
  }
}

// errors/ValidationError.ts
export class ValidationError extends AppError {
  constructor(
    public readonly field: string,
    public readonly invalidValue: unknown
  ) {
    super(
      `Valeur invalide pour le champ "${field}"`,
      "VALIDATION_ERROR",
      400,
      { field, invalidValue }
    );
  }
}

// errors/NotFoundError.ts
export class NotFoundError extends AppError {
  constructor(resource: string, id: string | number) {
    super(
      `${resource} avec l'id "${id}" introuvable`,
      "NOT_FOUND",
      404,
      { resource, id }
    );
  }
}

// Usage — propre et diagnostiquable
async function loadUser(id: string): Promise<User> {
  try {
    const res = await fetch(`/api/users/${id}`);
    if (res.status === 404) throw new NotFoundError("User", id);
    if (!res.ok) throw new NetworkError(`/api/users/${id}`, res.status);
    return res.json();
  } catch (e) {
    if (e instanceof AppError) throw e;
    throw new NetworkError(`/api/users/${id}`, 0, e);
  }
}

💡 Pourquoi Object.setPrototypeOf ?

En TypeScript compilé en ES5, l'héritage des classes natives comme Error peut casser instanceof. Cette ligne corrige le problème et garantit que e instanceof NetworkError fonctionne correctement.

4. Ne retournez pas null

C'est l'une des règles les plus impactantes du chapitre. Retourner null force chaque appelant à vérifier if (result !== null). Si l'un oublie de le faire, c'est un crash en production. Martin propose deux alternatives :

  • Lever une exception si l'absence de résultat est une erreur inattendue
  • Retourner un objet vide (liste vide, objet neutre) si c'est un cas normal

❌ Retour null — dangereux

function getUser(id: string): User | null {
  return users.find(u => u.id === id) ?? null;
}

// Chaque appelant doit vérifier...
const user = getUser("123");
if (user !== null) {  // oublier = crash
  console.log(user.name);
}

✅ Exception ou objet vide

// Cas 1 : l'absence est une erreur
function getUser(id: string): User {
  const user = users.find(u => u.id === id);
  if (!user) throw new NotFoundError("User", id);
  return user;
}

// Cas 2 : l'absence est normale
function searchUsers(query: string): User[] {
  return users.filter(u => u.name.includes(query));
  // retourne [] si aucun résultat — jamais null
}

En TypeScript, le système de types vous pousse déjà dans cette direction avec le strictNullChecks — activez-le toujours. Mais l'intention du chapitre va plus loin : même quand TypeScript l'autorise, évitez de propager le null comme valeur de retour ordinaire.

🧰 Pattern utile : le type Result

Dans les projets TypeScript modernes, on peut aussi utiliser un type Result<T, E> inspiré de Rust pour rendre les erreurs explicites dans la signature sans lever d'exception. C'est un compromis valide — tant que chaque appelant est obligé de traiter le cas d'erreur.

🦀 Pattern Result (alternatif fonctionnel) — TypeScript

// types/Result.ts
type Result<T, E extends Error = AppError> =
  | { success: true; data: T }
  | { success: false; error: E };

// Utilisation
function parseUser(raw: unknown): Result<User> {
  const parsed = UserSchema.safeParse(raw);
  if (!parsed.success) {
    return {
      success: false,
      error: new ValidationError("user", raw)
    };
  }
  return { success: true, data: parsed.data };
}

// L'appelant EST OBLIGÉ de gérer les deux cas
const result = parseUser(rawData);
if (!result.success) {
  logger.error(result.error.context);
  return;
}
console.log(result.data.name); // TypeScript sait que data existe ici

5. Ne passez pas null (ni undefined)

Symétrique de la règle précédente : si vous ne devez pas retourner null, vous ne devez pas non plus passer null à une fonction. Une fonction qui reçoit null en paramètre doit soit lever une exception, soit être protégée dès son entrée. Cela évite les fameux Cannot read property 'x' of null.

❌ null passé silencieusement

function formatUserName(user: User | null): string {
  return `${user?.firstName} ${user?.lastName}`;
  // Si user est null → retourne "undefined undefined"
  // Pas d'erreur, mais résultat incohérent
}

✅ Validation à l'entrée

function formatUserName(user: User): string {
  // TypeScript interdit le null à la signature
  // On ne défend pas contre l'impossible
  return `${user.firstName} ${user.lastName}`;
}

// La responsabilité est déplacée à l'appelant
const user = await getUser(id); // lance si absent
const name = formatUserName(user); // garanti non-null

⚠️ Ce que dit Martin ici : La plupart des langages n'ont pas de moyen simple d'empêcher le passage de null. La solution la plus propre est de ne jamais appeler une fonction avec null. En TypeScript, strictNullChecks: true dans le tsconfig.json rend cela obligatoire à la compilation — c'est votre meilleur allié.

6. Application concrète en React

React introduit des défis supplémentaires : les erreurs asynchrones, les erreurs de rendu, et la propagation visuelle des états d'erreur dans l'arbre de composants. Voici comment les principes du chapitre 7 s'appliquent concrètement.

Error Boundaries — le try-catch de React

Les Error Boundaries sont le mécanisme React pour capturer les erreurs dans le rendu. Ils correspondent directement à la règle "écrire le try-catch en premier" : vous définissez une frontière d'erreur autour de chaque zone de l'UI qui peut échouer indépendamment.

🛡️ Error Boundary moderne avec React 18 + TypeScript

// components/ErrorBoundary.tsx
import { Component, type ReactNode, type ErrorInfo } from "react";

interface Props {
  fallback: ReactNode | ((error: Error) => ReactNode);
  onError?: (error: Error, info: ErrorInfo) => void;
  children: ReactNode;
}

interface State {
  hasError: boolean;
  error: Error | null;
}

export class ErrorBoundary extends Component<Props, State> {
  state: State = { hasError: false, error: null };

  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error };
  }

  componentDidCatch(error: Error, info: ErrorInfo): void {
    // Log vers Sentry, Datadog, etc.
    this.props.onError?.(error, info);
    console.error("[ErrorBoundary]", error, info.componentStack);
  }

  render() {
    if (this.state.hasError && this.state.error) {
      const { fallback } = this.props;
      return typeof fallback === "function"
        ? fallback(this.state.error)
        : fallback;
    }
    return this.props.children;
  }
}

// Utilisation — composant de fallback dédié
function UserCardFallback({ error }: { error: Error }) {
  return (
    <div className="error-state">
      <p>Impossible d'afficher l'utilisateur.</p>
      {error instanceof NotFoundError && (
        <p>Ressource introuvable : {error.context?.resource}</p>
      )}
    </div>
  );
}

// Dans votre arbre de composants
<ErrorBoundary fallback={(e) => <UserCardFallback error={e} />}>
  <UserCard userId="123" />
</ErrorBoundary>

Gestion des erreurs async avec TanStack Query

Dans la majorité des applications React modernes, les données viennent d'une API. TanStack Query (anciennement React Query) suit naturellement les principes du chapitre 7 en séparant les états isError, isLoading, data.

🔄 Fetching propre avec TanStack Query — séparation des responsabilités

// hooks/useUser.ts
import { useQuery } from "@tanstack/react-query";

// La fonction de fetching lance des exceptions typées
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);

  if (res.status === 404) throw new NotFoundError("User", id);
  if (!res.ok) throw new NetworkError(`/api/users/${id}`, res.status);

  const data = await res.json();
  const parsed = UserSchema.safeParse(data);
  if (!parsed.success) throw new ValidationError("user", data);

  return parsed.data;
}

export function useUser(id: string) {
  return useQuery({
    queryKey: ["user", id],
    queryFn: () => fetchUser(id),
    retry: (failureCount, error) => {
      // Ne pas retry si 404 ou 400
      if (error instanceof NotFoundError) return false;
      if (error instanceof ValidationError) return false;
      return failureCount < 3;
    },
  });
}

// components/UserProfile.tsx — logique métier séparée du handling d'erreur
function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, isError, error } = useUser(userId);

  if (isLoading) return <Skeleton />;

  if (isError) {
    if (error instanceof NotFoundError) return <UserNotFound />;
    return <GenericError message={error.message} />;
  }

  // ICI : 100% logique d'affichage, zéro code d'erreur
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
    </div>
  );
}

Tableau récapitulatif — erreurs selon le contexte React

Contexte Mécanisme recommandé Principe Clean Code
Erreur de rendu dans un composant ErrorBoundary Try-catch en premier / Isolation
Erreur d'appel API async Exceptions typées + TanStack Query Classes d'erreur contextuelles
Validation de formulaire Zod + ValidationError Ne pas retourner null
Ressource introuvable NotFoundError → fallback UI Exceptions > codes de retour
Paramètre invalide dans hook Guard clause + throw Ne pas passer null

✅ Architecture type d'un projet React Clean :

  • src/errors/ — Vos classes d'erreur (AppError, NetworkError, etc.)
  • src/api/ — Fonctions de fetching qui lancent des exceptions typées
  • src/hooks/ — Hooks TanStack Query avec retry intelligent
  • src/components/ErrorBoundary.tsx — Boundaries stratégiques dans l'arbre
  • src/components/errors/ — Composants UI de fallback par type d'erreur

À Retenir

  • Exceptions > codes de retour : Une exception est auto-documentée et force le traitement. Un code de retour peut être ignoré silencieusement.
  • Try-catch en premier : Définissez le contrat d'erreur avant la logique métier. Cela force à y penser dès le départ.
  • Classes d'erreur typées : En TypeScript, créez une hiérarchie avec AppError comme base. Chaque classe porte son contexte (url, field, id…).
  • Ne retournez pas null : Retournez un objet vide (liste vide, objet neutre) ou levez une exception. Activez strictNullChecks dans votre tsconfig.
  • Ne passez pas null : Validez à l'entrée des fonctions. TypeScript avec strict mode est votre compilateur de garde.
  • En React : ErrorBoundary pour les erreurs de rendu, exceptions typées + TanStack Query pour les erreurs async, composants UI dédiés par type d'erreur.
  • Séparation des responsabilités : La gestion d'erreur doit rester à côté de la logique métier, pas dedans. Si votre code est parsemé de if (error), c'est le signal pour restructurer.

⏱️ Temps pour adopter ces pratiques : ~1 semaine pour refactorer les patterns existants, quelques jours seulement pour les intégrer sur un nouveau projet dès le départ.