CQRS Pattern Rules

cqrsarchitecturepatterns

Conventions for implementing Command Query Responsibility Segregation to separate read and write models, reducing complexity and enabling independent scaling.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# CQRS Pattern Rules ## Core Separation - Commands mutate state and return void or a command result (ID, status). Never return domain data from a command. - Queries only read state and must have no side effects. A query must never modify any data. - Separate command handlers and query handlers into distinct classes/modules. Never combine them. - Use dedicated read models (DTOs, projections) for queries — never expose write-model domain objects directly. ## Command Conventions - Name commands with imperative verbs: `CreateOrder`, `UpdateUserEmail`, `CancelShipment`. - Commands are value objects: immutable, fully validated before being dispatched. - Each command must have exactly one handler. One handler — one responsibility. - Command handlers perform validation, call the domain, persist changes, and publish domain events. - Return a `CommandResult` or `Result<T, Error>` type rather than throwing exceptions on business failures. - Validate commands at the boundary (controller/API layer) before dispatching — fail fast. ## Query Conventions - Name queries descriptively: `GetOrderById`, `ListActiveUsers`, `SearchProductsByCategory`. - Queries bypass the domain layer when possible — read directly from optimized read stores or views. - Use dedicated query models (read DTOs) — these are projection types, not domain entities. - Prefer direct SQL or ORM queries in query handlers; avoid loading full aggregate graphs. - Cache query results where appropriate; commands must invalidate relevant caches. ## Handler Structure - Place command handlers in `commands/` and query handlers in `queries/` directories. - Each handler file: one handler class + its request/response types. - Handlers must not call other handlers directly — use domain events or a mediator. - Use a mediator/bus pattern (`MediatR`, `CommandBus`, etc.) to decouple callers from handlers. ## Read Model / Projections - Build read models by subscribing to domain events — keep them eventually consistent where acceptable. - Denormalize aggressively for queries; optimize for read performance, not storage efficiency. - Projections must be idempotent: replaying the same event must produce the same state. - Store projections in the most appropriate store (SQL view, NoSQL collection, search index). ## Event Integration - After a command succeeds, publish domain events from the aggregate or command handler. - Never publish events before the write side persists — use transactional outbox or event store. - Domain events are named in past tense: `OrderCreated`, `UserEmailUpdated`, `ShipmentCancelled`. ## Anti-Patterns to Avoid - Do not query the write-side database from a command handler to validate business rules — use aggregate invariants. - Do not mix command logic into queries (e.g., lazy-initializing data during a read). - Do not return full domain aggregates from query handlers. - Do not use a single "service" class that handles both commands and queries. - Do not skip CQRS for complex domains just because it "seems simpler" — pay the upfront cost. ## Testing - Test command handlers with unit tests: given state, when command dispatched, then events published + state updated. - Test query handlers with integration tests against a real (or in-memory) database. - Test projections by replaying a sequence of events and asserting the final read model.

CLI

npx mindaxis apply cqrs-rules --target cursor --scope project

Используется в паках

Hexagonal Architecture

DDD, CQRS, and ports & adapters patterns

Открыть пак →

← Правила