Cqrs

CQRS — Quick Reference

CQRS (Command Query Responsibility Segregation) sépare les opérations d'écriture et de lecture dans des modèles distincts. N'est pas par défaut — c'est une optimisation à activer quand le coût de la complexité est justifié.

Quand utiliser

Règle d'or : commencer par une architecture classique. Migrer vers CQRS lorsqu'au moins 2 des cas pertinents sont présents simultanément.

Architecture en 30 secondes

[ User ]
   ↓
[ Command ]──────────▶ [ Write Model (Domain) ]
                              ↓ persist + emit
                       [ Event(s) ]
                              ↓
[ Query ] ◀───── [ Read Model (denormalised) ] ◀── projections

• Command side : modèle normalisé, focus invariants métier. Écrit, ne lit que ce qui est nécessaire à la validation.
• Query side : modèle dénormalisé, focus performance lecture. N'a pas de logique métier.
• Projections : transforment les events en read models. Eventually consistent.

Trade-off central

Patterns associés (souvent ensemble)

• Event Sourcing : stocker la séquence d'events comme source de vérité, le write model est reconstruit en replay.
• Saga / Process Manager : orchestrer des transactions distribuées via events.
• Outbox Pattern : garantir l'atomicité publication event + write DB.
• Materialized Views : projections persistées en table dédiée pour query speed.

Anti-patterns critiques

• ❌ CQRS sans cas d'usage clair → over-engineering, double charge cognitive.
• ❌ Read model qui exécute des règles métier → bug d'invariants à chaque projection.
• ❌ Projections synchrones → on perd le bénéfice scalability.
• ❌ Event Sourcing sans snapshots → replay de millions d'events au boot.
• ❌ Command qui retourne data complète → c'est une Query déguisée.

Pour aller plus loin

Implémentations Symfony / Laravel / .NET, Event Sourcing (Prooph, EventStoreDB), saga patterns, outbox, exemples concrets, migration progressive d'un CRUD vers CQRS, checklists par phase : voir @.claude/skills/cqrs/REFERENCE.md.

CQRS — Command Query Responsibility Segregation

Vue d'ensemble

CQRS sépare les opérations de lecture (Query) et d'écriture (Command) dans des modèles distincts.

Principes :

• ✅ Optimisation indépendante lecture/écriture
• ✅ Scalabilité différenciée (read replicas)
• ✅ Event Sourcing optionnel
• ❌ Ne PAS utiliser si domaine simple (CRUD classique suffit)

---

Table des matières

1. Quand utiliser CQRS 2. Quand NE PAS utiliser CQRS 3. Architecture CQRS 4. Implémentation 5. Event Sourcing 6. Trade-offs 7. Checklist

---

Quand utiliser CQRS

Exemple : Système de facturation avec audit légal obligatoire.

---

Quand NE PAS utiliser CQRS

Règle : CQRS est une optimisation. Ne l'utiliser que si le problème justifie la complexité.

Quote : "CQRS is a pattern that should be applied carefully. It's not a silver bullet." — Greg Young

---

Architecture CQRS

Principe

┌─────────────────────────────────────────────────────────┐
│                        Client                           │
└───────────┬─────────────────────────────┬───────────────┘
            │                             │
            ▼                             ▼
     ┌──────────────┐             ┌──────────────┐
     │   Command    │             │    Query     │
     │     Side     │             │     Side     │
     └──────┬───────┘             └──────┬───────┘
            │                             │
            ▼                             ▼
     ┌──────────────┐             ┌──────────────┐
     │  Write Model │             │  Read Model  │
     │  (normalized)│             │ (denormalized)│
     └──────┬───────┘             └──────┬───────┘
            │                             │
            ▼                             ▼
     ┌──────────────┐             ┌──────────────┐
     │ Postgres     │──Event──────▶ Elasticsearch│
     │ (master)     │ Projection  │  (replicas)  │
     └──────────────┘             └──────────────┘

Command Side

Responsabilité : Valider et exécuter les commandes (create, update, delete).

Caractéristiques :

• Modèle normalisé (3NF)
• Validation métier stricte
• Event emission
• Write-optimized

Query Side

Responsabilité : Répondre aux requêtes de lecture (get, list, search).

Caractéristiques :

• Modèle dénormalisé (projection)
• Pas de validation (déjà faite côté command)
• Read-optimized (indexes, caching)
• Eventual consistency acceptable

---

Implémentation

Symfony (Messenger + Doctrine)

Command :

// Command
final readonly class CreateOrderCommand
{
    public function __construct(
        public string $userId,
        public array $items,
        public float $totalAmount,
    ) {}
}

// Handler
final class CreateOrderCommandHandler implements MessageHandlerInterface
{
    public function __construct(
        private EntityManagerInterface $em,
        private MessageBusInterface $eventBus,
    ) {}

    public function __invoke(CreateOrderCommand $command): void
    {
        // Validation métier
        if ($command->totalAmount <= 0) {
            throw new InvalidOrderException('Total must be positive');
        }

        // Créer l'entité
        $order = new Order($command->userId, $command->items, $command->totalAmount);
        $this->em->persist($order);
        $this->em->flush();

        // Émettre event
        $this->eventBus->dispatch(new OrderCreatedEvent($order->getId()));
    }
}

Query :

// Query
final readonly class GetOrderQuery
{
    public function __construct(public string $orderId) {}
}

// Handler
final class GetOrderQueryHandler implements MessageHandlerInterface
{
    public function __construct(private OrderReadRepository $repository) {}

    public function __invoke(GetOrderQuery $query): OrderReadModel
    {
        return $this->repository->findById($query->orderId)
            ?? throw new OrderNotFoundException();
    }
}

Projection (Event Handler) :

final class OrderProjector implements MessageHandlerInterface
{
    public function __construct(private OrderReadRepository $readRepo) {}

    public function __invoke(OrderCreatedEvent $event): void
    {
        // Créer le read model dénormalisé
        $readModel = new OrderReadModel(
            id: $event->orderId,
            userName: $this->getUserName($event->userId),
            itemsCount: count($event->items),
            totalAmount: $event->totalAmount,
            createdAt: new \DateTimeImmutable(),
        );

        $this->readRepo->save($readModel);
    }
}

Laravel (Action pattern)

Command :

class CreateOrderAction
{
    public function execute(CreateOrderDTO $dto): Order
    {
        DB::beginTransaction();

        $order = Order::create([
            'user_id' => $dto->userId,
            'items' => $dto->items,
            'total_amount' => $dto->totalAmount,
        ]);

        event(new OrderCreated($order));

        DB::commit();

        return $order;
    }
}

Query :

class GetOrderQuery
{
    public function execute(string $orderId): OrderReadModel
    {
        return OrderReadModel::findOrFail($orderId);
    }
}

---

Event Sourcing

Principe

Au lieu de stocker l'état actuel, stocker tous les events qui ont mené à cet état.

Exemple :

État classique :
Order { status: "delivered" }

Event Sourcing :
OrderCreated -> OrderPaid -> OrderShipped -> OrderDelivered

Avantages

• ✅ Audit complet (qui a fait quoi, quand)
• ✅ Time travel (reconstruire état passé)
• ✅ Replay events (reconstruire projections)

Inconvénients

• ❌ Complexité élevée
• ❌ Stockage volumineux
• ❌ Requêtes complexes (reconstruire état)

Quand utiliser : Audit légal, finance, santé (compliance stricte).

---

Trade-offs

Règle : Ne pas utiliser CQRS "par défaut". Commencer par architecture classique, migrer si nécessaire.

---

Checklist

Avant d'adopter CQRS

• [ ] Le domaine est-il complexe (logique métier riche) ?
• [ ] Y a-t-il un ratio lecture/écriture déséquilibré (> 10:1) ?
• [ ] L'équipe maîtrise-t-elle les patterns DDD/Event-Driven ?
• [ ] L'eventual consistency est-elle acceptable ?

Implémentation

• [ ] Séparer command handlers et query handlers
• [ ] Modèle write normalisé, modèle read dénormalisé
• [ ] Event bus pour projections async
• [ ] Tests d'isolation (command ne lit pas, query n'écrit pas)

Avec Event Sourcing

• [ ] Store d'events (PostgreSQL, EventStore)
• [ ] Snapshot strategy (éviter replay complet)
• [ ] Replay mechanism (reconstruire projections)

---

Ressources

• Greg Young - CQRS : cqrs.files.wordpress.com
• Martin Fowler - CQRS : martinfowler.com/bliki/CQRS.html
• Microsoft - CQRS Pattern : learn.microsoft.com/en-us/azure/architecture/patterns/cqrs

---

Date de dernière mise à jour : 2026-04 Version : 1.0.0 Auteur : The Bearded CTO