CQRS يعني إيه؟
CQRS اختصار Command Query Responsibility Segregation. Command يطلب تغيير state ولا يرجع domain data كبيرة؛ Query يقرأ بيانات ولا يغير state. الهدف فصل responsibility لأن write model يحتاج invariants/consistency، بينما read model يحتاج projection/query performance. CQRS لا يعني تلقائيًا microservices أو event sourcing أو database منفصلة.
ابدأ بـ logical CQRS داخل نفس application ونفس database: Commands تمر عبر handlers/domain model، Queries تستخدم EF projection مباشرة. ده يعطي separation من غير eventual consistency. لو عندك read workload مختلف أو scaling needs، ممكن لاحقًا تفصل read store وتقبل eventual consistency.
CQRS في رسمة
ممكن الـ write والـ read model يبقوا نفس الـ database (CQRS «خفيف» بـ handlers منفصلة) أو منفصلين (eventual consistency). ابدأ بالخفيف.
Commands vs Queries
Command اسمها فعل: PlaceOrder، CancelReservation، ChangePassword. تحمل data اللازمة لتنفيذ use case. Query اسمها سؤال: GetOrderDetails، SearchProducts. ترجع DTO/read model. لا تستخدم command لقراءة فقط أو query تغير state.
public sealed record CancelOrderCommand(Guid OrderId, string Reason);
public sealed record GetOrderDetailsQuery(Guid OrderId);
public sealed record OrderDetailsDto(
Guid Id, string Status, decimal Total,
IReadOnlyList<OrderLineDto> Items);Command لا تحتاج تحمل entity كاملة من client؛ استقبل identifiers و intent، ثم اجلب trusted state من DB. لا تقبل Status الجديد من client في CancelOrder؛ command تمثل intent، والـ domain يقرر transition المسموح.
Handlers و Validation و Transaction Boundaries
Handler ينفذ use case: load aggregate، validate context، invoke domain behavior، persist، publish event عبر outbox إذا لزم. Validation يمكن أن تكون input validation قبل handler، بينما domain invariants داخل aggregate. Transaction boundary غالبًا واحدة حول command handler/Unit of Work.
public sealed class CancelOrderHandler(
IOrderRepository orders, IUnitOfWork unitOfWork)
{
public async Task Handle(CancelOrderCommand command, CancellationToken ct)
{
var order = await orders.GetForModificationAsync(command.OrderId, ct)
?? throw new NotFoundException("Order not found.");
order.Cancel(command.Reason);
await unitOfWork.SaveChangesAsync(ct);
}
}لو cancellation ترسل refund عبر provider خارجي، لا تضع HTTP call داخل DB transaction. سجل intent/outbox أو workflow state، ثم نفذ refund كخطوة منفصلة قابلة لل retry/reconciliation.
Command Idempotency و Concurrency
Command ممكن تتكرر بسبب double-click، mobile retry، timeout بعد commit، أو message redelivery. لا تفترض أن HTTP POST يصل مرة واحدة. أضف idempotency key للعمليات الحساسة، وخزن outcome المرتبط بها في نفس transaction مع business update. Unique constraint على key يمنع تنفيذ command مرتين عبر replicas.
Command handler يجب يحدد concurrency semantics: هل يسمح بآخر update يفوز؟ هل يحتاج optimistic concurrency version؟ هل transition مشروط بـ current status؟ لا تجعل command مجرد DTO ينفذ Update لكل fields؛ command تعبر عن intent وتحدد allowed mutation.
var affected = await db.Orders
.Where(x => x.Id == command.OrderId &&
x.Status == OrderStatus.Pending &&
x.RowVersion == command.ExpectedVersion)
.ExecuteUpdateAsync(setters => setters
.SetProperty(x => x.Status, OrderStatus.Cancelled), ct);
if (affected == 0)
throw new ConflictException("Order changed or cannot be cancelled.");لو تستخدم ExecuteUpdate، أضف audit/outbox بوضوح لأن aggregate methods و domain events لن تنفذ تلقائيًا. لو تحتاج domain behavior، load tracked aggregate ثم تحقق من version عند SaveChanges.
Handler Design: لا تجعل كل Handler مجرد Proxy
Handler جيد ينسق use case: authorization على المورد، تحميل aggregate، تنفيذ behavior، حفظ، وإرجاع result واضح. لا تنقل business invariant إلى validator فقط؛ validator مناسب لصحة الشكل مثل الاسم غير فارغ أو page size ضمن حد، بينما domain method تحمي invariant مهما كان مصدر الاستدعاء. وإلا يمكن bypass validator من job أو test أو message consumer.
لا تجعل Handler يستدعي 8 handlers أخرى كأنك بنيت workflow graph غير مرئي. استخرج domain service أو application service عندما توجد orchestration مشتركة، أو استخدم explicit workflow state machine للعمليات الطويلة. Pipeline behavior مناسب concerns عامة مثل validation و logging و transaction، لكن لا تضع business-specific behavior فيه لأن ذلك يخفي control flow.
MediatR و Mediator Alternatives
Mediator library تقلل direct dependencies بين caller وال handler: endpoint يرسل command إلى mediator، والـ mediator يختار handler. MediatR مشهور في .NET، لكن licensing/version terms يجب مراجعتها عند الاستخدام التجاري، ويمكن استخدام source-generated mediator أو Wolverine أو hand-rolled dispatcher حسب requirements. لا تجعل library هي architecture نفسها.
لو عندك 5 use cases بسيطة، direct handler injection قد يكون أوضح. mediator مفيد عندما تحتاج pipeline behaviors موحدة للـ validation/logging/transaction/metrics أو dispatch conventions. لا تستخدم mediator لإخفاء flow معقد يجعل call graph غير قابل للفهم.
Mediator Pitfalls و Handler Explosion
Handler لكل use case قد يجعل boundaries واضحة، لكنه قد ينتج classes كثيرة trivial. لو handler مجرد يمرر request إلى service من غير policy/transaction/validation، direct method call قد يكون أوضح. لا تخفِ control flow في nested notifications و pipeline behaviors يصعب تتبعها.
استخدم correlation IDs و structured logs حول command/handler. سجّل request type و duration/outcome، لكن لا تسجل sensitive payload. لا تجعل generic pipeline behavior تنفذ side effects غير متوقعة مثل إرسال email قبل transaction commit.
Read Models و Projection
Read model DTO مصممة لشاشة أو API response، ويمكن أن تجمع بيانات من عدة tables وتعمل projection مباشرة في SQL. لا تحتاج ترجع domain aggregate ثم تحولها في memory. في logical CQRS، نفس database تخدم writes/reads، لكن الكود والـ model منفصلان.
public sealed class GetOrderDetailsHandler(AppDbContext db)
{
public Task<OrderDetailsDto?> Handle(
GetOrderDetailsQuery query, CancellationToken ct) =>
db.Orders.AsNoTracking()
.Where(x => x.Id == query.OrderId)
.Select(x => new OrderDetailsDto(
x.Id, x.Status.ToString(), x.Total,
x.Items.Select(i => new OrderLineDto(
i.ProductNameSnapshot, i.Quantity, i.UnitPrice)).ToArray()))
.SingleOrDefaultAsync(ct);
}Projection تقلل columns وال tracking. راجع SQL generated، pagination، index design و N+1. لو read model materialized منفصلًا، وضح freshness/lag و rebuild strategy.
Separate Read/Write Databases و Eventual Consistency
Physical CQRS قد يستخدم write database normalized/read model store مثل Elasticsearch أو denormalized SQL tables. بعد commit، event/CDC projector يحدث read store asynchronously. عندها read model قد تتأخر؛ user ينشئ order ثم يقرأ قائمة orders قبل وصول projection. لازم UX/API تحدد read-your-writes behavior: return created resource مباشرة، read from write store لفترة، أو expose projection watermark/consistency token.
Eventual consistency ليست «bug» لكنها contract. قِس projection lag، وفّر replay/rebuild، تعامل مع duplicate/out-of-order events، واحتفظ event schema version. لو consumer يعالج event رقم 12 ثم 11، هل يكتب state قديمة؟ استخدم version/sequence per aggregate أو idempotent upsert rules.
Command -> Write DB transaction
|-- update aggregate
|-- insert Outbox event
v
Outbox dispatcher -> Broker -> Projection consumer
|-- deduplicate event id
|-- apply aggregate version
v
Read model storeCQRS مع Read Replica: Eventual Consistency و Retry
لو فصلت read database عن write database، قد ينجح command ثم query مباشرة لا ترى التغيير بعد بسبب replication lag. ده eventual consistency. لا تفترض إن read-your-writes مضمون. خيارات التعامل: اقرأ من write store بعد command حساس، أعد response من command نفسه، أرسل version/sequence token، أو اعرض حالة Pending حتى يصل projection.
لا تجعل client يعيد command لمجرد أن response ضاع؛ استخدم idempotency key أو command ID محفوظًا مع النتيجة. يجب أن يكون handler قادرًا على تمييز duplicate request عن عملية جديدة. في حال optimistic concurrency، أعد conflict واضحًا مع expected/current version بدل overwrite صامت.
Event Sourcing مختلف: هو تخزين sequence من domain events كمصدر الحقيقة، وبناء state منها. ليس مرادفًا لـ CQRS. له تكلفة schema evolution، replay، snapshots، event versioning، privacy/erasure، debugging، projection rebuilds. لا تختاره لمجرد أن عندك audit log؛ قد يكفي append-only audit table.
Consistency في CQRS: Read-Your-Writes و Eventual Consistency
عندما command تكتب في primary database و query تقرأ من replica أو projection محدثة عبر events، قد لا يرى المستخدم التغيير فورًا. هذا Eventual Consistency وليس bug بالضرورة، لكن API يجب تشرح الحالة. يمكن أن تعيد command resource ID و status، أو query من write model لفترة قصيرة، أو تستخدم version token حتى يعرف client أن projection وصلت إلى version المطلوبة.
لا تستخدم CQRS مع read/write databases منفصلتين لمجرد فصل classes. ابدأ بفصل logical handlers في نفس database ونفس transaction. أضف projections منفصلة عندما query performance أو shape تبرر ذلك. كل read model جديدة لها تكلفة: rebuild، schema evolution، duplicate delivery، monitoring lag، و event versioning.
Pipeline Behaviors
Pipeline behavior يلف handler لتطبيق concern مشترك: validation، logging، metrics، transaction، idempotency، tracing. حافظ على ترتيب واضح: validation قبل transaction غالبًا؛ logging/metrics حول العملية؛ transaction حول persistence. لا تجعل behavior يخفي side effects أو يفتح transaction لكل query بلا داعٍ.
public sealed class ValidationBehavior<TRequest, TResponse>(
IEnumerable<IValidator<TRequest>> validators)
{
public async Task<TResponse> Handle(
TRequest request, RequestHandlerDelegate<TResponse> next,
CancellationToken ct)
{
var failures = validators
.SelectMany(v => v.Validate(request).Errors)
.Where(error => error is not null)
.ToArray();
if (failures.Length > 0)
throw new ValidationException(failures);
return await next();
}
}الكود conceptual وقد يختلف signature حسب mediator library/version. لو كتبت pipeline يدويًا، اختبر order و exception behavior و cancellation propagation.
Outbox و Event Sourcing Awareness
Domain event يصف حقيقة داخل domain مثل OrderConfirmed. Integration event رسالة تُرسل إلى systems أخرى بعد commit. Outbox يحفظ integration event في نفس transaction مع business change، ثم dispatcher ينشرها. ده يكمل CQRS لكنه ليس شرطًا فيه.
Event Sourcing مختلف: source of truth هو event stream، والـ current state يُبنى من events. CQRS يمكن تطبيقه من غير event sourcing، وغالبًا ابدأ بذلك. Event sourcing يضيف event schema evolution، replay، projections، ordering، snapshots و operational complexity؛ لا تستخدمه لمجرد أن CQRS موجود.
Event Sourcing: ما الذي يتغير فعلًا؟
في CRUD، current state هي source of truth. في Event Sourcing، append-only event stream هي source of truth، والـ aggregate state يُعاد بناؤه بتطبيق events بالترتيب. ده يتيح history/replay/audit/time-travel projections، لكنه يجعل event schema evolution و snapshots و event ordering و concurrency و retention أصعب.
لا تعدل event قديمة لتناسب code جديد؛ version/upcast event schema أو أضف event type جديدًا. Snapshots تقلل replay time لكنها ليست source of truth. projections قابلة لإعادة البناء من event log، لكن rebuild قد يستغرق وقتًا ويحتاج versioned consumers. Event sourcing لا يعني event broker؛ storage stream قد تكون database مخصصة.
اختَر Event Sourcing عندما history نفسها business-critical أو تحتاج temporal reconstruction/audit قوي أو workflows event-centric. لا تختاره لمجرد أنك تريد audit log بسيط؛ table audit/outbox قد تكفي.
Event Versioning و Projection Rebuild
إذا event schema تغيرت، consumers القديمة والجديدة قد تعمل معًا أثناء deployment. أضف fields اختيارية أو versioned envelope، وتجنب إعادة تفسير معنى field قديم بصمت. عند projection bug قد تحتاج rebuild من event log أو source of truth؛ لذلك حدد retention، replay speed، idempotency، وماذا يحدث للـ side effects أثناء replay. لا ترسل emails أو تخصم أموالًا عند إعادة بناء read model.
Projection يجب تكون idempotent أو تحفظ processed position/version. لو events out-of-order، استخدم aggregate sequence number أو version guard. لا تفترض أن timestamp وحده يكفي للترتيب. اختبر duplicate, delayed, missing, poison events، وراقب projection lag.
Benefits و Trade-offs وإمتى لا تستخدم CQRS
الفوائد: command intent واضح، handlers أصغر، read/write models مستقلة، testing أوضح، ويمكن scale reads/writes بشكل مختلف لاحقًا. التكاليف: ملفات/handlers أكثر، duplication بين models، mapping، pipeline complexity، eventual consistency لو فصلت stores، و debugging عبر dispatch.
لا تحتاج CQRS لو CRUD بسيط، نفس model يخدم reads/writes جيدًا، ولا توجد complexity أو scaling pressure. لا تفصل databases قبل وجود سبب. ابدأ logical separation داخل monolith ثم قِس. CQRS ليس pattern إلزاميًا لكل endpoint.
اختبار CQRS End-to-End
Command tests: valid transition، invalid state، duplicate command، concurrency conflict، repository failure، outbox persistence، rollback. Query tests: filtering/sorting/paging، projection fields، tenant scope، performance-critical SQL، read model freshness. لو physical CQRS، اختبر consumer idempotency، replay، out-of-order events، poison message و projection rebuild.
لا تكتب integration test تنتظر projection بــ Thread.Sleep ثابت؛ استخدم polling bounded مع timeout أو test hook/wait condition. اختبر lag metrics والـ behavior عندما read model متأخرة. API contract يجب يوضح هل read-after-write فوري أم eventual.
CQRS Lab: Command و Query لنفس Order من غير فصل قواعد البيانات
أفضل بداية لـ CQRS في تطبيق .NET هي فصل intent والـ models، وليس تشغيل database ثانية أو broker. PlaceOrder command يغير state، و GetOrderDetails query يقرأ projection. الاثنين يمكن أن يستخدموا نفس SQL Server ونفس DbContext في البداية، لكن لا تشارك command DTO كأنه response DTO.
public sealed record ConfirmOrder(Guid OrderId, Guid CustomerId);
public sealed class ConfirmOrderHandler(AppDbContext db)
{
public async Task Handle(ConfirmOrder command, CancellationToken ct)
{
var order = await db.Orders
.Include(x => x.Items)
.SingleOrDefaultAsync(x => x.Id == command.OrderId
&& x.CustomerId == command.CustomerId, ct)
?? throw new NotFoundException("Order not found.");
order.Confirm(); // Domain invariant lives on the aggregate.
await db.SaveChangesAsync(ct);
}
}public sealed record OrderDetails(Guid Id, string Status,
decimal Total, IReadOnlyList<OrderLineDto> Items);
public sealed class GetOrderDetailsHandler(AppDbContext db)
{
public Task<OrderDetails?> Handle(Guid id, Guid customerId,
CancellationToken ct) => db.Orders.AsNoTracking()
.Where(x => x.Id == id && x.CustomerId == customerId)
.Select(x => new OrderDetails(x.Id, x.Status.ToString(),
x.Total, x.Items.Select(i => new OrderLineDto(
i.ProductName, i.Quantity, i.UnitPrice)).ToList()))
.SingleOrDefaultAsync(ct);
}الـ command يتأكد من ownership/authorization، يحمل aggregate، ينفذ transition ويحفظ. الـ query لا يحتاج tracking ولا domain aggregate كامل؛ يقرأ شكل الشاشة مباشرة. لاحظ أن إخفاء Order عن عميل آخر قد يكون 404 أو 403 حسب سياسة الـ API، لكن لا تعتمد على client-supplied CustomerId وحده: استخرج الهوية من authenticated principal وتحقق من resource ownership في server.
أضف MediatR أو mediator library فقط عندما تقلل coupling أو توفر pipeline behaviors ذات قيمة. لا تحول كل method إلى handler لمجرد أن CQRS موجود في roadmap. في نفس database transaction، command يمكن أن يحفظ state و outbox record معًا. Publisher يرسل event لاحقًا، وال consumer idempotent. لا تنشر event قبل commit ثم تفترض أن database و broker أصبحا atomic.
اختبر command على قواعد domain والـ transaction/concurrency، واختبر query على projection و authorization filters و pagination. افصل read store لاحقًا عندما يوجد سبب مقاس: query workload مختلف، scaling مستقل، أو projection معقدة. وقتها وثّق eventual consistency و read-your-writes behavior.
اختيار CQRS: Decision Questions
- هل write rules معقدة ومختلفة عن read projections؟
- هل reads كثيرة ومكلفة أو تحتاج schema مختلفة؟
- هل تحتاج scale read/write independently؟
- هل الفريق يستطيع تشغيل outbox/broker/projections/rebuild؟
- هل eventual consistency مقبولة ومفهومة للـ users؟
- هل logical CQRS داخل نفس DB تحل المشكلة أولًا؟
ابدأ بأقل مستوى من الفصل يحقق الفائدة: separate command/query handlers، ثم read models، وبعدها separate store فقط إذا أثبت القياس الحاجة. CQRS قرار تدريجي وليس migration إلزامية.
CQRS بسيط داخل Monolith: فصل Read عن Write بدون Microservices
CQRS لا يشترط database منفصلة ولا message broker ولا Event Sourcing. أبسط شكل: command handler يحمّل aggregate ويطبق business invariant، و query handler يستخدم projection مباشرة إلى DTO. الهدف أن write model يعبّر عن business behavior، والـ read model يجيب الشاشة بكفاءة.
public sealed record RenameProduct(Guid ProductId, string NewName);
public sealed class RenameProductHandler(AppDbContext db)
{
public async Task Handle(RenameProduct command, CancellationToken ct)
{
var product = await db.Products.SingleOrDefaultAsync(
x => x.Id == command.ProductId, ct)
?? throw new NotFoundException();
product.Rename(command.NewName);
await db.SaveChangesAsync(ct);
}
}
public sealed class ProductDetailsQuery(AppDbContext db)
{
public Task<ProductDetails?> Get(Guid id, CancellationToken ct) =>
db.Products.AsNoTracking()
.Where(x => x.Id == id)
.Select(x => new ProductDetails(x.Id, x.Name, x.Price,
x.Category.Name))
.SingleOrDefaultAsync(ct);
}الـ query لا يحتاج أن يحمّل aggregate كاملًا إذا كان المطلوب عرض اسم وسعر وتصنيف. والـ command لا يجب أن يقبل كل أعمدة الـ entity كـ DTO update؛ ذلك يفتح mass assignment ويضعف invariants. اجعل command يعبر عن intent محدد، مثل RenameProduct أو ChangePrice، وليس UpdateProductEverything.
اختبر فهمك
هل CQRS يتطلب database منفصلة للقراءة والكتابة؟
هل CQRS يعني Event Sourcing؟
لماذا Query handler يستخدم projection؟
ما المشكلة التي يحلها Outbox؟
متى يكون CQRS overengineering؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خريطة التغطية: 15 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.