Clean Architecture Guide

Clean Architecture Guide

Critères de décision : quand l'appliquer

Workflow en étapes

1. Modéliser le domaine (cercle intérieur)

Pas de framework, pas de DTO externe, pas de ORM mapping ici. Uniquement des classes métier pures.

// Domain/Entities/Order.cs (.NET)
public class Order
{
    public Guid Id { get; private set; }
    public Money Total { get; private set; }
    public OrderStatus Status { get; private set; }

    public void Confirm()
    {
        if (Status != OrderStatus.Pending)
            throw new DomainException("Order already processed.");
        Status = OrderStatus.Confirmed;
        AddEvent(new OrderConfirmedEvent(Id));
    }
}

Checklist domaine :

• Zéro using vers des frameworks (EF, ASP.NET, NestJS…)
• Value Objects pour les concepts sans identité (Money, Email)
• Domain Events pour les effets de bord métier
• Validations métier dans les entités, pas dans les controllers

2. Définir les ports (interfaces)

Les ports sont des contrats dans la couche Application ou Domain. Ils décrivent ce dont on a besoin, pas comment c'est implémenté.

// Application/Ports/IOrderRepository.ts (TypeScript)
export interface IOrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}

export interface IPaymentGateway {
  charge(amount: Money, token: string): Promise<PaymentResult>;
}

3. Implémenter les Use Cases (Application Services)

Un use case = une classe, une méthode publique, un résultat.

// Application/UseCases/ConfirmOrder/ConfirmOrderUseCase.ts
export class ConfirmOrderUseCase {
  constructor(
    private readonly orders: IOrderRepository,
    private readonly payment: IPaymentGateway,
    private readonly events: IEventBus,
  ) {}

  async execute(cmd: ConfirmOrderCommand): Promise<void> {
    const order = await this.orders.findById(cmd.orderId);
    if (!order) throw new NotFoundException('Order not found');

    order.confirm();
    await this.payment.charge(order.total, cmd.paymentToken);
    await this.orders.save(order);
    await this.events.publish(order.pullEvents());
  }
}

Règles use case :

• Ne retourne que des types simples ou DTOs (jamais d'Entity du domaine vers l'extérieur)
• N'instancie pas ses dépendances (DI uniquement)
• Ne connaît pas HTTP, SQL, ni aucun détail infrastructure

4. Créer les Adapters (Infrastructure / Frameworks)

// Infrastructure/Adapters/Persistence/EfOrderRepository.cs
public class EfOrderRepository : IOrderRepository
{
    private readonly AppDbContext _db;
    public EfOrderRepository(AppDbContext db) => _db = db;

    public async Task<Order?> FindByIdAsync(Guid id) =>
        await _db.Orders.FirstOrDefaultAsync(o => o.Id == id);

    public async Task SaveAsync(Order order)
    {
        _db.Orders.Update(order);
        await _db.SaveChangesAsync();
    }
}

Adapters typiques à créer : Repository (DB), Gateway (API externe), EmailSender, FileStorage, Cache, MessagePublisher.

5. Arborescence de projet recommandée

src/
├── Domain/              # Entités, Value Objects, Domain Events, interfaces de domaine
│   ├── Entities/
│   ├── ValueObjects/
│   └── Events/
├── Application/         # Use Cases, DTOs, interfaces de ports
│   ├── UseCases/
│   └── Ports/
├── Infrastructure/      # Adapters : DB, HTTP, Message Queue, Cache
│   ├── Persistence/
│   ├── Gateways/
│   └── Messaging/
└── Presentation/        # Controllers, CLI, Workers (dépend d'Application uniquement)
    ├── Http/
    └── Workers/

Pour les petits projets : organiser par feature à l'intérieur de chaque couche.

6. Composition Root (DI)

Tout l'assemblage se fait à la frontière externe, jamais dans le domaine.

// Program.cs / Startup.cs (.NET)
builder.Services.AddScoped<IOrderRepository, EfOrderRepository>();
builder.Services.AddScoped<IPaymentGateway, StripePaymentAdapter>();
builder.Services.AddScoped<ConfirmOrderUseCase>();

// NestJS Module
@Module({
  providers: [
    ConfirmOrderUseCase,
    { provide: IOrderRepository, useClass: TypeOrmOrderRepository },
    { provide: IPaymentGateway, useClass: StripeAdapter },
  ],
})
export class OrderModule {}

7. Stratégie de tests par couche

// Test unitaire use case — zéro infra
it('should confirm a pending order', async () => {
  const order = Order.create({ ... });
  const repo = { findById: vi.fn().mockResolvedValue(order), save: vi.fn() };
  const payment = { charge: vi.fn().mockResolvedValue({ success: true }) };

  await new ConfirmOrderUseCase(repo, payment, eventBus).execute({ orderId: order.id });

  expect(order.status).toBe(OrderStatus.Confirmed);
  expect(repo.save).toHaveBeenCalledWith(order);
});

Anti-patterns / Pièges

Règle de dépendance — rappel absolu

Presentation → Application → Domain
Infrastructure → Application → Domain

Jamais l'inverse. Si le domaine importe un namespace infrastructure, c'est un bug d'architecture à corriger immédiatement via un port.

Bonnes pratiques 2026

• Vertical Slicing : dans les grands projets, organiser d'abord par feature (Ordering, Billing…) puis par couche à l'intérieur — évite les dossiers monolithiques.
• Minimal API / Thin Controllers : le controller ne fait qu'appeler le use case et mapper le résultat HTTP — zéro logique.
• Result Pattern plutôt qu'exceptions pour les erreurs métier attendues (Result<T, Error>).
• Testcontainers pour les tests d'intégration des adapters (DB réelle éphémère).
• Architecture tests : utiliser NetArchTest (.NET) ou dependency-cruiser (Node) pour enforcer les règles de dépendance en CI.

# Enforcer les règles en CI (Node)
npx depcruise src --config .dependency-cruiser.js --output-type err