Clean Code — Chapitre 8 : Les Boundaries (Frontières)
Le chapitre 8 de Clean Code s'attaque à un problème quotidien : vous intégrez une librairie tierce, une API externe, ou un SDK, et votre code métier se retrouve collé à cette dépendance. Quand la librairie change, tout change avec elle. Martin appelle boundaries (frontières) les zones de contact entre votre code et le code qui ne vous appartient pas. Son message central : ne laissez jamais une dépendance externe contaminer votre domaine métier.
💡 L'idée clé du chapitre en une phrase :
« Le code de tiers ne nous appartient pas. Il faut créer une frontière claire pour que notre code ne dépende pas directement de ses détails d'implémentation. »
- Wrappez les libs tierces — n'importez jamais directement Axios, Sentry, Stripe… dans vos composants
- Utilisez des interfaces — pour inverser les dépendances et pouvoir substituer n'importe quelle implémentation
- Apprenez par les tests de boundary — des tests ciblés qui vérifient votre compréhension d'une lib avant de l'intégrer
- Contrôlez ce que vous ne possédez pas — isolez les parties instables du système
1. Qu'est-ce qu'une boundary ?
Une boundary est la ligne de contact entre votre code et du code externe : une librairie npm, une API REST, un SDK, un framework. Le problème identifié par Martin est simple : vous ne contrôlez pas ce code. Il peut changer, être déprécié, ou avoir une API qui ne correspond pas exactement à ce dont vous avez besoin.
En TypeScript/React, les boundaries typiques sont : Axios, TanStack Query, Sentry, Stripe, Firebase, des composants UI tiers (MUI, shadcn), ou n'importe quel SDK externe.
❌ Dépendance directe — couplage fort
// UserService.ts
import axios from "axios"; // ⚠️ dépendance directe
export async function getUser(id: string) {
// Votre logique métier CONNAÎT Axios
const res = await axios.get(`/api/users/${id}`, {
headers: { Authorization: `Bearer ${token}` },
timeout: 5000,
});
return res.data;
}
// Si Axios change d'API → tout le service change
✅ Via une interface — couplage faible
// UserService.ts
import type { IHttpClient } from "@/boundaries/http";
export class UserService {
constructor(private http: IHttpClient) {}
async getUser(id: string): Promise<User> {
// Votre logique métier ne connaît qu'une interface
return this.http.get<User>(`/users/${id}`);
}
}
// Axios peut changer → UserService ne change PAS
🎯 La règle de Martin
Évitez de vous promener dans votre base de code avec une librairie tierce directement importée. Plus elle est répandue dans votre code, plus sa migration sera douloureuse. Concentrez cet usage en un seul endroit, et exposez une interface que vous contrôlez.
2. Le pattern Wrapper — enveloppez ce que vous ne possédez pas
Un Wrapper (ou Adapter) est une fine couche de code qui entoure une lib tierce et expose votre propre API. Votre code métier n'interagit qu'avec ce wrapper — jamais directement avec la librairie.
⏱️ Durée estimée pour créer cette couche sur un projet existant : 2–4h
// boundaries/http/types.ts — Votre interface, indépendante de tout
export interface IHttpClient {
get<T>(url: string, config?: RequestConfig): Promise<T>;
post<T>(url: string, body: unknown, config?: RequestConfig): Promise<T>;
put<T>(url: string, body: unknown, config?: RequestConfig): Promise<T>;
delete<T>(url: string, config?: RequestConfig): Promise<T>;
}
export interface RequestConfig {
headers?: Record<string, string>;
timeout?: number;
signal?: AbortSignal;
}
// boundaries/http/AxiosHttpClient.ts — L'implémentation concrète (isolée ici)
import axios, { type AxiosInstance } from "axios";
import type { IHttpClient, RequestConfig } from "./types";
export class AxiosHttpClient implements IHttpClient {
private client: AxiosInstance;
constructor(baseURL: string, defaultHeaders?: Record<string, string>) {
this.client = axios.create({
baseURL,
timeout: 10_000,
headers: { "Content-Type": "application/json", ...defaultHeaders },
});
}
async get<T>(url: string, config?: RequestConfig): Promise<T> {
const res = await this.client.get<T>(url, config);
return res.data;
}
async post<T>(url: string, body: unknown, config?: RequestConfig): Promise<T> {
const res = await this.client.post<T>(url, body, config);
return res.data;
}
async put<T>(url: string, body: unknown, config?: RequestConfig): Promise<T> {
const res = await this.client.put<T>(url, body, config);
return res.data;
}
async delete<T>(url: string, config?: RequestConfig): Promise<T> {
const res = await this.client.delete<T>(url, config);
return res.data;
}
}
// Demain, migrer vers fetch natif = remplacer UNIQUEMENT ce fichier
// boundaries/http/FetchHttpClient.ts
export class FetchHttpClient implements IHttpClient {
constructor(private baseURL: string) {}
async get<T>(url: string, config?: RequestConfig): Promise<T> {
const res = await fetch(`${this.baseURL}${url}`, {
signal: config?.signal,
headers: config?.headers,
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
return res.json() as Promise<T>;
}
// ... autres méthodes
}
🔵 Autre exemple concret — wrapper Sentry : vous
importez Sentry directement dans 20 composants. Si vous migrez vers
Datadog ou un logger custom, vous devez modifier 20 fichiers. Avec un
wrapper logger.ts, vous ne modifiez qu'un seul fichier.
📦 Wrapper pour Sentry / système de logging
// boundaries/logger/types.ts
export interface ILogger {
info(message: string, context?: Record<string, unknown>): void;
warn(message: string, context?: Record<string, unknown>): void;
error(error: Error | string, context?: Record<string, unknown>): void;
captureException(error: Error): void;
}
// boundaries/logger/SentryLogger.ts
import * as Sentry from "@sentry/react";
import type { ILogger } from "./types";
export class SentryLogger implements ILogger {
info(message: string, context?: Record<string, unknown>) {
console.info(`[INFO] ${message}`, context);
Sentry.addBreadcrumb({ message, data: context, level: "info" });
}
warn(message: string, context?: Record<string, unknown>) {
console.warn(`[WARN] ${message}`, context);
Sentry.addBreadcrumb({ message, data: context, level: "warning" });
}
error(error: Error | string, context?: Record<string, unknown>) {
console.error(`[ERROR]`, error, context);
Sentry.captureMessage(String(error), { extra: context });
}
captureException(error: Error) {
Sentry.captureException(error);
}
}
// Votre code métier
// ✅ Aucune mention de Sentry ici
function processPayment(logger: ILogger, amount: number) {
try {
// logique...
} catch (e) {
logger.captureException(e as Error); // interface uniquement
}
}
3. Les interfaces TypeScript comme contrats de boundary
TypeScript est un allié naturel du chapitre 8. Là où Martin travaillait
avec Java et ses interfaces explicites, TypeScript offre le
duck typing structurel : une interface décrit la forme
attendue sans forcer un implements explicite. C'est encore
plus flexible.
🔌 Pattern complet — Analytics boundary en TypeScript
// boundaries/analytics/types.ts
export interface IAnalyticsService {
trackEvent(name: string, properties?: Record<string, unknown>): void;
identify(userId: string, traits?: Record<string, unknown>): void;
page(name: string, properties?: Record<string, unknown>): void;
}
// boundaries/analytics/MixpanelAnalytics.ts
import mixpanel from "mixpanel-browser";
import type { IAnalyticsService } from "./types";
export class MixpanelAnalytics implements IAnalyticsService {
trackEvent(name: string, properties?: Record<string, unknown>) {
mixpanel.track(name, properties);
}
identify(userId: string, traits?: Record<string, unknown>) {
mixpanel.identify(userId);
if (traits) mixpanel.people.set(traits);
}
page(name: string) {
mixpanel.track(`Page viewed: ${name}`);
}
}
// boundaries/analytics/NullAnalytics.ts — Pour les tests !
export class NullAnalytics implements IAnalyticsService {
trackEvent() {} // ne fait rien — utile en test et en dev
identify() {}
page() {}
}
// hooks/useAnalytics.ts — Le hook consomme UNIQUEMENT l'interface
import { useContext } from "react";
import { AnalyticsContext } from "@/contexts/AnalyticsContext";
import type { IAnalyticsService } from "@/boundaries/analytics/types";
export function useAnalytics(): IAnalyticsService {
const analytics = useContext(AnalyticsContext);
if (!analytics) throw new Error("AnalyticsContext manquant");
return analytics;
}
// Dans un composant — aucune dépendance directe à Mixpanel
function CheckoutButton({ amount }: { amount: number }) {
const analytics = useAnalytics();
const handleClick = () => {
analytics.trackEvent("checkout_started", { amount });
// logique de paiement...
};
return <button onClick={handleClick}>Payer {amount}€</button>;
}
// main.tsx — La configuration de l'implémentation est centralisée ici
const analyticsService = import.meta.env.PROD
? new MixpanelAnalytics()
: new NullAnalytics(); // pas de tracking en dev
<AnalyticsContext.Provider value={analyticsService}>
<App />
</AnalyticsContext.Provider>
4. Learning Tests — tester sa propre compréhension
Martin introduit un concept original : les Learning Tests. Avant d'intégrer une lib tierce dans votre projet, vous écrivez des tests qui vérifient votre compréhension de son API. Ce n'est pas du TDD classique — c'est une façon d'explorer une librairie inconnue de façon contrôlée, et de détecter les changements d'API lors des mises à jour.
🎯 Les 3 bénéfices des Learning Tests :
- Vous apprenez la lib en écrivant des vrais exemples exécutables (pas juste en lisant la doc)
- Vous avez une suite de régression : si la lib change, vos tests échouent avant que votre code ne plante
- Vous documentez vos hypothèses sur le comportement attendu
🧪 Exemple — Learning Tests pour une lib de validation (Zod)
// __tests__/boundaries/zod.learning.test.ts
// Ce fichier DOCUMENTE notre compréhension de Zod
// Si Zod change de comportement → ces tests le détectent
import { z } from "zod";
describe("Zod — Learning Tests", () => {
describe("Comportement des types optionnels", () => {
const schema = z.object({
name: z.string(),
age: z.number().optional(),
});
test("accepte un objet sans age", () => {
const result = schema.safeParse({ name: "Alice" });
expect(result.success).toBe(true);
});
test("age undefined est différent d'age absent", () => {
const withUndefined = schema.safeParse({ name: "Alice", age: undefined });
// Notre hypothèse : Zod accepte undefined pour optional()
expect(withUndefined.success).toBe(true);
});
test("rejette une string là où un number est attendu", () => {
const result = schema.safeParse({ name: "Alice", age: "25" });
// Notre hypothèse : Zod est strict par défaut (pas de coercion)
expect(result.success).toBe(false);
});
});
describe("Comportement de transform", () => {
const emailSchema = z.string().email().toLowerCase();
test("normalise l'email en minuscules", () => {
const result = emailSchema.parse("ALICE@EXAMPLE.COM");
// Notre hypothèse : toLowerCase() applique un transform
expect(result).toBe("alice@example.com");
});
});
describe("Comportement des erreurs", () => {
const schema = z.object({ name: z.string().min(2) });
test("safeParse retourne les erreurs structurées", () => {
const result = schema.safeParse({ name: "A" });
expect(result.success).toBe(false);
if (!result.success) {
// Notre hypothèse : les erreurs ont un path et un message
expect(result.error.errors[0].path).toEqual(["name"]);
expect(result.error.errors[0].message).toContain("2");
}
});
});
});
✅ Astuce pratique : nommez ces fichiers
*.learning.test.ts pour les distinguer de vos tests
unitaires classiques. Vous pouvez même les placer dans
__tests__/boundaries/ — un dossier dédié aux frontières
— pour signaler leur nature documentaire à toute l'équipe.
5. Application concrète en React — organisation des boundaries
En React, les boundaries se traduisent concrètement par une structure de dossiers qui isole toutes les dépendances externes au même endroit.
📁 Architecture recommandée — dossier boundaries/
src/ ├── boundaries/ ← TOUT ce qui est tiers vit ici │ ├── http/ │ │ ├── types.ts ← IHttpClient interface │ │ ├── AxiosHttpClient.ts │ │ └── index.ts ← export public │ ├── analytics/ │ │ ├── types.ts ← IAnalyticsService interface │ │ ├── MixpanelAnalytics.ts │ │ ├── NullAnalytics.ts ← pour les tests │ │ └── index.ts │ ├── logger/ │ │ ├── types.ts ← ILogger interface │ │ ├── SentryLogger.ts │ │ └── index.ts │ └── storage/ │ ├── types.ts ← IStorage interface │ ├── LocalStorage.ts │ └── InMemoryStorage.ts ← pour les tests │ ├── domain/ ← 0 import de lib tierce ici │ ├── services/ │ └── models/ │ ├── contexts/ ← injection des implementations │ ├── HttpContext.tsx │ └── AnalyticsContext.tsx │ └── main.tsx ← câblage final des implémentations
Câblage via Context — injection des implémentations
React Context est un excellent mécanisme pour injecter les implémentations de vos boundaries sans passer par un container DI complexe.
🔌 Câblage complet avec Context + hook typé
// contexts/ServicesContext.tsx — Point d'entrée unique
import { createContext, useContext, type ReactNode } from "react";
import type { IHttpClient } from "@/boundaries/http/types";
import type { ILogger } from "@/boundaries/logger/types";
import type { IAnalyticsService } from "@/boundaries/analytics/types";
interface Services {
http: IHttpClient;
logger: ILogger;
analytics: IAnalyticsService;
}
const ServicesContext = createContext<Services | null>(null);
export function ServicesProvider({
services,
children,
}: {
services: Services;
children: ReactNode;
}) {
return (
<ServicesContext.Provider value={services}>
{children}
</ServicesContext.Provider>
);
}
// Hook typé — un seul point d'accès aux services
export function useServices(): Services {
const ctx = useContext(ServicesContext);
if (!ctx) throw new Error("ServicesProvider manquant dans l'arbre");
return ctx;
}
// Hooks dédiés par service — encore plus propre
export const useHttp = () => useServices().http;
export const useLogger = () => useServices().logger;
export const useAnalytics = () => useServices().analytics;
// ──────────────────────────────────────────────────────────────
// main.tsx — Configuration PRODUCTION
import { AxiosHttpClient } from "@/boundaries/http/AxiosHttpClient";
import { SentryLogger } from "@/boundaries/logger/SentryLogger";
import { MixpanelAnalytics } from "@/boundaries/analytics/MixpanelAnalytics";
const prodServices: Services = {
http: new AxiosHttpClient(import.meta.env.VITE_API_URL),
logger: new SentryLogger(),
analytics: new MixpanelAnalytics(),
};
ReactDOM.createRoot(document.getElementById("root")!).render(
<ServicesProvider services={prodServices}>
<App />
</ServicesProvider>
);
// ──────────────────────────────────────────────────────────────
// setup-tests.ts — Configuration TESTS (implémentations neutres)
import { FetchHttpClient } from "@/boundaries/http/FetchHttpClient";
import { NullLogger } from "@/boundaries/logger/NullLogger";
import { NullAnalytics } from "@/boundaries/analytics/NullAnalytics";
export const testServices: Services = {
http: new FetchHttpClient("http://localhost:3001"), // serveur mock
logger: new NullLogger(), // silencieux en test
analytics: new NullAnalytics(), // pas de tracking en test
};
// renderWithServices — helper de test
export function renderWithServices(ui: ReactElement) {
return render(
<ServicesProvider services={testServices}>{ui}</ServicesProvider>
);
}
Tableau récapitulatif — Quoi wrapper en priorité ?
| Dépendance | Priorité | Raison | Interface à créer |
|---|---|---|---|
| Client HTTP (Axios, fetch) | 🔴 Haute | Utilisé partout, migre souvent | IHttpClient |
| Logger / Sentry | 🔴 Haute | Change selon l'env (prod/dev/test) | ILogger |
| Analytics (Mixpanel, GA) | 🟡 Moyenne | Silencieux en test, change d'outil | IAnalyticsService |
| Storage (localStorage) | 🟡 Moyenne | Non disponible en SSR / test | IStorage |
| Composants UI tiers (MUI) | 🟢 Basse | Rarement migré, mais pense aux tokens | Props normalisées |
| Librairies de validation (Zod) | 🟢 Basse | Stable, mais écrire des Learning Tests | Learning Tests suffisent |
⚠️ Piège fréquent : ne pas wrapper par défaut
tout sans réfléchir. Un over-engineering de boundaries est
aussi un problème. Appliquez ce principe aux dépendances instables,
très répandues dans le code, ou qui varient selon l'environnement. Une
lib de dates bien établie comme date-fns n'a
probablement pas besoin d'un wrapper complet.
À Retenir — Chapitre 8 Clean Code
- Une boundary = une zone de contact avec du code externe — librairie npm, API, SDK. Vous n'en contrôlez pas l'évolution.
- Wrappers et Adapters — Enveloppez les libs tierces dans votre propre couche. Votre code métier ne doit jamais importer Axios, Sentry, Mixpanel directement.
- Interfaces TypeScript — Définissez des interfaces qui appartiennent à votre domaine. Les implémentations concrètes sont substituables : prod, dev, test.
- Learning Tests — Avant d'intégrer une lib, écrivez des tests pour documenter votre compréhension. Ils deviennent une suite de régression si la lib change.
-
React Context pour l'injection — Injectez les implémentations via Context au niveau de
main.tsx. Chaque environnement (prod, test) a son propre câblage. -
Dossier
boundaries/— Centralisez tout le code d'intégration tierce dans un dossier dédié. Le code dansdomain/ne doit contenir aucun import de lib externe. - Ne pas over-engineer — Wrappez en priorité les dépendances instables, très répandues dans le code, ou qui varient selon l'environnement.
⏱️ Temps pour adopter ces pratiques : ~2–4h pour créer la structure de boundaries sur un projet existant, 30 min sur un nouveau projet si on part avec cette architecture dès le départ.