Chapitre 11 – Les Systèmes

Clean Code — Chapitre 11 : Les Systèmes

Le chapitre 11 marque une montée en niveau d'abstraction. Après avoir parlé de fonctions, de classes, et de tests, Martin s'attaque à la construction de systèmes entiers. Son message : un système propre émerge d'une architecture qui sépare les préoccupations, retarde les décisions, et permet l'évolution sans réécriture massive. En React/TypeScript, ce chapitre résonne particulièrement avec les questions d'architecture : feature folders, layers, injection de dépendances.

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

« La complexité tue. Elle aspire la vie des développeurs, rend les systèmes difficiles à planifier, construire et tester. Un bon système doit séparer ses préoccupations dès le début. »

  • Separation of Concerns — Découper le système en couches indépendantes (UI, Domain, Infrastructure)
  • Dependency Injection — Inverser les dépendances pour que le domaine métier ne connaisse pas l'infrastructure
  • Émergence propre — Commencer simple, laisser l'architecture émerger avec les besoins réels
  • Retarder les décisions — Ne pas figer les choix techniques (BDD, framework) trop tôt
Architecture en couches — Flux de dépendances Couche UI (Presentation) Composants React • Hooks UI • Routing • State Management Dépend de → Domain Couche Domain (Business Logic) Services • Entities • Use Cases • Business Rules NE dépend PAS de l'infra (inversion) Couche Infrastructure (Adapters) HTTP Client • Database • Storage • External APIs Implémente les interfaces du Domain dépend de implémente

1. Separation of Concerns — découper le système

Martin insiste : un système ne peut pas être propre s'il mélange toutes ses préoccupations. La séparation des préoccupations (Separation of Concerns) signifie que chaque partie du système doit avoir une responsabilité claire et ne pas empiéter sur les autres.

Présentation (UI)

Comment afficher les données à l'utilisateur. React components, styles, interactions.

Logique métier

Les règles et processus qui définissent le domaine. Indépendant de l'UI et de l'infra.

Infrastructure

Comment accéder aux données externes : API, BDD, stockage, services tiers.

❌ Tout mélangé — préoccupations entrelacées

// Un composant qui fait TOUT
function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);

  useEffect(() => {
    // ⚠️ Infrastructure dans l'UI
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(data => {
        // ⚠️ Logique métier dans l'UI
        const formattedUser = {
          ...data,
          displayName: data.firstName + " " + data.lastName,
          isVip: data.credits > 1000,
        };
        setUser(formattedUser);
      });
  }, [userId]);

  if (!user) return <div>Loading...</div>;

  return (
    <div>
      <h1>{user.displayName}</h1>
      {user.isVip && <span>⭐ VIP</span>}
    </div>
  );
}
// ❌ UI + Logique métier + Infrastructure
// → Impossible à tester, à réutiliser, à faire évoluer

✅ Préoccupations séparées

// Infrastructure — HTTP
class UserRepository {
  async findById(id: string): Promise<UserDTO> {
    const res = await fetch(`/api/users/${id}`);
    return res.json();
  }
}

// Domain — Logique métier
class User {
  constructor(
    public firstName: string,
    public lastName: string,
    public credits: number
  ) {}

  get displayName(): string {
    return `${this.firstName} ${this.lastName}`;
  }

  get isVip(): boolean {
    return this.credits > 1000;
  }
}

// Domain — Use Case
class GetUserProfile {
  constructor(private repo: UserRepository) {}

  async execute(id: string): Promise<User> {
    const dto = await this.repo.findById(id);
    return new User(dto.firstName, dto.lastName, dto.credits);
  }
}

// UI — Présentation pure
function UserProfile({ userId }: { userId: string }) {
  const user = useUserProfile(userId); // hook custom

  if (!user) return <div>Loading...</div>;

  return (
    <div>
      <h1>{user.displayName}</h1>
      {user.isVip && <span>⭐ VIP</span>}
    </div>
  );
}
// ✅ Chaque couche a sa responsabilité

🎯 Règle simple de séparation

La logique métier ne doit jamais importer fetch, axios, ou un composant React. Elle doit être testable en isolation, sans serveur web, sans DOM, sans rien d'externe.

2. Dependency Injection — inverser les dépendances

L'injection de dépendances (DI) est le mécanisme clé pour respecter la séparation des préoccupations. Au lieu que le domaine métier importe directement une implémentation d'infrastructure, il reçoit une interface qu'on lui injecte de l'extérieur.

Inversion de dépendances — Avant / Après ❌ Sans DI UserService (Domain) AxiosClient (Infra) import ⚠️ Le domaine dépend de l'infra ✅ Avec DI UserService (Domain) IHttpClient (Interface) dépend de AxiosClient FetchClient MockClient implémentent

🔌 Pattern DI complet en TypeScript/React

// ──────────────────────────────────────────────────────────────
// 1. DOMAIN — Définit ses besoins via une interface
// ──────────────────────────────────────────────────────────────
// domain/ports/IUserRepository.ts
export interface IUserRepository {
  findById(id: string): Promise<User>;
  save(user: User): Promise<void>;
}

// domain/services/UserService.ts
export class UserService {
  // ✅ Dépend de l'interface, PAS d'une implémentation
  constructor(private repository: IUserRepository) {}

  async promoteToVip(userId: string): Promise<void> {
    const user = await this.repository.findById(userId);
    user.credits += 1000;
    await this.repository.save(user);
  }
}

// ──────────────────────────────────────────────────────────────
// 2. INFRASTRUCTURE — Implémente l'interface du Domain
// ──────────────────────────────────────────────────────────────
// infrastructure/repositories/ApiUserRepository.ts
export class ApiUserRepository implements IUserRepository {
  constructor(private httpClient: IHttpClient) {}

  async findById(id: string): Promise<User> {
    const dto = await this.httpClient.get<UserDTO>(`/users/${id}`);
    return new User(dto.firstName, dto.lastName, dto.credits);
  }

  async save(user: User): Promise<void> {
    await this.httpClient.put(`/users/${user.id}`, user);
  }
}

// infrastructure/repositories/InMemoryUserRepository.ts
export class InMemoryUserRepository implements IUserRepository {
  private users = new Map<string, User>();

  async findById(id: string): Promise<User> {
    const user = this.users.get(id);
    if (!user) throw new Error("User not found");
    return user;
  }

  async save(user: User): Promise<void> {
    this.users.set(user.id, user);
  }
}

// ──────────────────────────────────────────────────────────────
// 3. INJECTION — Context React pour câbler les dépendances
// ──────────────────────────────────────────────────────────────
// contexts/ServicesContext.tsx
interface Services {
  userService: UserService;
}

const ServicesContext = createContext<Services | null>(null);

export function ServicesProvider({ children }: { children: ReactNode }) {
  // Câblage en PRODUCTION
  const httpClient = new AxiosHttpClient(import.meta.env.VITE_API_URL);
  const userRepository = new ApiUserRepository(httpClient);
  const userService = new UserService(userRepository);

  return (
    <ServicesContext.Provider value={{ userService }}>
      {children}
    </ServicesContext.Provider>
  );
}

export const useUserService = () => {
  const ctx = useContext(ServicesContext);
  if (!ctx) throw new Error("ServicesContext missing");
  return ctx.userService;
};

// ──────────────────────────────────────────────────────────────
// 4. TESTS — Injection d'une implémentation mock
// ──────────────────────────────────────────────────────────────
describe("UserService", () => {
  test("promoteToVip ajoute 1000 crédits", async () => {
    // ✅ Pas besoin d'API réelle — injection d'un mock
    const mockRepo = new InMemoryUserRepository();
    await mockRepo.save(new User("1", "Alice", "Dupont", 500));

    const service = new UserService(mockRepo);
    await service.promoteToVip("1");

    const user = await mockRepo.findById("1");
    expect(user.credits).toBe(1500);
  });
});

✅ Avantages de la DI :

  • Testabilité — Injecter des mocks, pas besoin d'API/BDD réelle
  • Flexibilité — Changer d'implémentation (Axios → Fetch) sans toucher au domaine
  • Isolation — Le domaine métier reste pur, sans dépendances externes

3. Architecture en couches — la Clean Architecture

Martin recommande une organisation en couches concentriques, où chaque couche ne connaît que les couches intérieures. La plus célèbre application de ce principe est la Clean Architecture (popularisée par Uncle Bob lui-même).

📐 Les 3 couches essentielles

🎨
Presentation (UI)

Responsabilité : Affichage, interactions utilisateur, routing, state management UI.

Dépend de : Domain (via hooks/Context)

Exemples : Composants React, pages, layouts, formulaires

💼
Domain (Business Logic)

Responsabilité : Règles métier, entités, use cases, validations.

Dépend de : Rien (ou interfaces qu'il définit lui-même)

Exemples : Services, entités (User, Order), règles de calcul

⚙️
Infrastructure (Adapters)

Responsabilité : Accès aux données externes, API, BDD, stockage.

Dépend de : Domain (implémente ses interfaces)

Exemples : Repositories, HttpClient, LocalStorage wrappers

📁 Structure de dossiers Clean Architecture en React

src/
├── domain/                      ← ❤️ Coeur du système (logique métier)
│   ├── entities/
│   │   ├── User.ts             ← Entité métier pure
│   │   └── Order.ts
│   ├── services/
│   │   ├── UserService.ts      ← Use cases / business logic
│   │   └── OrderService.ts
│   └── ports/                   ← Interfaces (que l'infra implémente)
│       ├── IUserRepository.ts
│       └── IPaymentGateway.ts
│
├── infrastructure/              ← 🔌 Adapters externes
│   ├── repositories/
│   │   ├── ApiUserRepository.ts    ← Implémente IUserRepository
│   │   └── InMemoryUserRepository.ts
│   ├── http/
│   │   └── AxiosHttpClient.ts
│   └── storage/
│       └── LocalStorageAdapter.ts
│
├── presentation/                ← 🎨 UI / React
│   ├── components/
│   │   ├── UserCard.tsx
│   │   └── OrderList.tsx
│   ├── pages/
│   │   ├── HomePage.tsx
│   │   └── UserProfilePage.tsx
│   ├── hooks/
│   │   ├── useUserService.ts   ← Injection via Context
│   │   └── useOrders.ts
│   └── contexts/
│       └── ServicesContext.tsx ← Point d'injection DI
│
└── main.tsx                     ← Câblage final (prod/dev/test)

🔵 Règle de dépendance : Le code dans domain/ ne doit jamais importer quoi que ce soit de infrastructure/ ou presentation/. C'est le coeur protégé du système.

4. Émergence propre — ne pas tout concevoir d'avance

Martin met en garde contre le big design up front (concevoir toute l'architecture avant d'écrire du code). Au lieu de ça, il recommande de commencer simple et de laisser l'architecture émerger avec les besoins réels. C'est la philosophie You Aren't Gonna Need It (YAGNI).

Évolution progressive d'un système

Phase 1 : Prototype (jour 1-7)

Tout dans des composants React. Pas de couches, pas de services. fetch direct dans les useEffect.

✅ Parfait pour valider l'idée rapidement

Phase 2 : Extraction (semaine 2-3)

Extraire les hooks custom (useUsers, useOrders). Créer des helper functions pour la logique métier.

✅ Le code commence à être réutilisable

Phase 3 : Services (mois 1-2)

Créer des classes de service pour encapsuler la logique métier. Introduire des interfaces pour les repositories.

✅ Testabilité améliorée, début de séparation domain/infra

Phase 4 : Couches (mois 3+)

Architecture en 3 couches complète (Domain, Infrastructure, Presentation). Injection de dépendances via Context.

✅ Système mature, facile à faire évoluer et à tester

⚠️ Ne sautez pas directement à la phase 4 si vous commencez un projet. L'architecture doit émerger avec les besoins réels, pas être imposée d'avance. Commencez simple, refactorez quand la complexité l'exige.

5. Application concrète — Système React complet

Voici un exemple complet d'une application React qui applique tous les principes du chapitre 11 : séparation des préoccupations, DI, couches, émergence progressive.

🏗️ Système complet — User Management (architecture propre)

// ══════════════════════════════════════════════════════════════
// DOMAIN LAYER — Logique métier pure
// ══════════════════════════════════════════════════════════════

// domain/entities/User.ts
export class User {
  constructor(
    public readonly id: string,
    public firstName: string,
    public lastName: string,
    public email: string,
    public credits: number
  ) {}

  get displayName(): string {
    return `${this.firstName} ${this.lastName}`;
  }

  get isVip(): boolean {
    return this.credits >= 1000;
  }

  addCredits(amount: number): void {
    if (amount <= 0) throw new Error("Amount must be positive");
    this.credits += amount;
  }
}

// domain/ports/IUserRepository.ts
export interface IUserRepository {
  findById(id: string): Promise<User>;
  findAll(): Promise<User[]>;
  save(user: User): Promise<void>;
  delete(id: string): Promise<void>;
}

// domain/services/UserService.ts
export class UserService {
  constructor(
    private repository: IUserRepository,
    private logger: ILogger
  ) {}

  async promoteToVip(userId: string): Promise<User> {
    const user = await this.repository.findById(userId);
    user.addCredits(1000);
    await this.repository.save(user);
    
    this.logger.info("User promoted to VIP", { userId });
    return user;
  }

  async searchUsers(): Promise<User[]> {
    return this.repository.findAll();
  }
}

// ══════════════════════════════════════════════════════════════
// INFRASTRUCTURE LAYER — Adapters
// ══════════════════════════════════════════════════════════════

// infrastructure/repositories/ApiUserRepository.ts
export class ApiUserRepository implements IUserRepository {
  constructor(private httpClient: IHttpClient) {}

  async findById(id: string): Promise<User> {
    const dto = await this.httpClient.get<UserDTO>(`/users/${id}`);
    return this.mapDtoToEntity(dto);
  }

  async findAll(): Promise<User[]> {
    const dtos = await this.httpClient.get<UserDTO[]>("/users");
    return dtos.map(this.mapDtoToEntity);
  }

  async save(user: User): Promise<void> {
    await this.httpClient.put(`/users/${user.id}`, this.mapEntityToDto(user));
  }

  async delete(id: string): Promise<void> {
    await this.httpClient.delete(`/users/${id}`);
  }

  private mapDtoToEntity(dto: UserDTO): User {
    return new User(dto.id, dto.firstName, dto.lastName, dto.email, dto.credits);
  }

  private mapEntityToDto(user: User): UserDTO {
    return {
      id: user.id,
      firstName: user.firstName,
      lastName: user.lastName,
      email: user.email,
      credits: user.credits,
    };
  }
}

// ══════════════════════════════════════════════════════════════
// PRESENTATION LAYER — React UI
// ══════════════════════════════════════════════════════════════

// presentation/hooks/useUserService.ts
export function useUserService() {
  const { userService } = useContext(ServicesContext);
  if (!userService) throw new Error("ServicesContext missing");
  return userService;
}

// presentation/components/UserCard.tsx
export function UserCard({ userId }: { userId: string }) {
  const userService = useUserService();
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    userService.searchUsers().then(users => {
      const found = users.find(u => u.id === userId);
      setUser(found ?? null);
      setLoading(false);
    });
  }, [userId, userService]);

  const handlePromote = async () => {
    if (!user) return;
    const promoted = await userService.promoteToVip(user.id);
    setUser(promoted);
  };

  if (loading) return <div>Loading...</div>;
  if (!user) return <div>User not found</div>;

  return (
    <div>
      <h2>{user.displayName}</h2>
      <p>{user.email}</p>
      <p>Credits: {user.credits}</p>
      {user.isVip && <span>⭐ VIP</span>}
      {!user.isVip && <button onClick={handlePromote}>Promote to VIP</button>}
    </div>
  );
}

// ══════════════════════════════════════════════════════════════
// COMPOSITION ROOT — Câblage final
// ══════════════════════════════════════════════════════════════

// main.tsx
const httpClient = new AxiosHttpClient(import.meta.env.VITE_API_URL);
const logger = import.meta.env.PROD ? new SentryLogger() : new ConsoleLogger();
const userRepository = new ApiUserRepository(httpClient);
const userService = new UserService(userRepository, logger);

ReactDOM.createRoot(document.getElementById("root")!).render(
  <ServicesProvider services={{ userService }}>
    <App />
  </ServicesProvider>
);

Tableau de décision — Quand appliquer chaque pattern ?

Taille du projet Architecture recommandée Raison
Petit (<10 composants) Tout dans les composants Overhead inutile de séparer en couches
Moyen (10-50 composants) Hooks custom + helper functions Suffit pour réutiliser la logique
Grand (50-200 composants) Services + Repositories + DI Testabilité et maintenabilité critiques
Très grand (200+ composants) Clean Architecture complète (3 couches) Évolutivité long-terme, équipes multiples

À Retenir

  • Separation of Concerns — Un système propre sépare ses préoccupations : UI, logique métier, infrastructure. Chacune dans sa couche.
  • Dependency Injection — Le domaine métier ne dépend pas de l'infrastructure. Il définit des interfaces que l'infra implémente (inversion de dépendances).
  • Architecture en couches — 3 couches essentielles : Presentation (UI React), Domain (business logic), Infrastructure (adapters externes).
  • Règle de dépendance — Le code dans domain/ ne doit jamais importer de infrastructure/ ou presentation/. Les flèches de dépendance pointent vers l'intérieur.
  • Émergence progressive — Ne pas concevoir toute l'architecture d'avance. Commencer simple (tout dans les composants), refactorer en couches quand la complexité l'exige.
  • React Context pour DI — Câbler les services via Context. Le main.tsx est le "composition root" où on instancie et injecte tout.
  • Testabilité — Avec DI, on peut injecter des mocks dans les tests. Le domaine métier se teste sans serveur, sans DOM, sans rien d'externe.
  • Évolutivité — Changer d'implémentation (Axios → Fetch, API → LocalStorage) ne touche qu'un seul fichier dans infrastructure/. Le domaine et l'UI ne changent pas.

⏱️ Temps pour migrer vers Clean Architecture : ~1-2 semaines sur un projet existant moyen. Sur un nouveau projet : commencer simple, introduire les couches progressivement (phase 1 → 4).