Software Engineer Encyclopedia
0%
Domain 06 · Software Architecture & Design Patterns · Topic 6.1

Clean Architecture في .NET: Dependency Rule من غير Overengineering

Clean Architecture — Deep Practical .NET Guide

شرح الطبقات والاعتماد للداخل، Domain/Application/Infrastructure/API، use cases، DI، persistence abstractions، DTOs، testing، modular monolith وvertical slices.

  • Advanced
  • ~26 min read
  • 21 sections
  • 20 code examples
  • 1 diagrams
  • 5 questions
  • Priority L1 · Important
  • .NET 10 · C# 14 · EF Core 10

المتطلبات قبل ما تبدأ

خبرة عملية ببناء API بقاعدة بيانات — الأنماط دي حلول لمشاكل لازم تكون شفتها.

مستوى التعمق المطلوب

DEEP PRACTICALUnderstand why dependencies point inward and avoid adding layers without a reason.

01

Clean Architecture بتحل إيه؟

Keep business policy independent from infrastructure
Deep dive

Clean Architecture طريقة لتنظيم dependencies بحيث business rules لا تعتمد على تفاصيل database أو web framework أو message broker. الفكرة الأساسية ليست عدد projects ولا أسماء folders؛ الفكرة أن اتجاه source-code dependencies يشير للداخل نحو policy/domain. التفاصيل الخارجية تنفذ contracts يحتاجها الداخل، والـ composition root يربط implementations وقت التشغيل.

لو غيرت SQL Server إلى PostgreSQL، المفروض domain rules لا تتغير. لو غيرت Minimal APIs إلى Controllers، business use cases لا تتغير. لو استبدلت SMTP provider، لا تعدل domain model. لكن ده لا يعني أن التغيير الخارجي لا يؤثر في Infrastructure/API؛ ده مكان التغيير المقصود.

Clean Architecture ليست هدفًا بذاتها. تطبيق CRUD صغير أو prototype قد يكون أبسط مع feature folders و DbContext مباشرة. لو بنيت 5 projects و12 interfaces لكل endpoint، فأنت ربما صنعت ceremony لا استقلالية. استخدمها عندما business rules، integrations، testing، أو expected change تبرر الحدود.

02

Dependency Rule: السهم يشاور للداخل

Compile-time dependency direction
Deep dive

المبدأ: inner layers لا تعرف outer layers. Domain لا references Application أو Infrastructure أو ASP.NET Core. Application تعرف Domain وتعرّف abstractions التي تحتاجها. Infrastructure references Application/Domain لتنفيذ interfaces. API references Application و Infrastructure في composition root، وتعرف كيفية استقبال HTTP وتحويله إلى use case.

APIHTTP endpointsDTO mappingComposition rootInfrastructureEF CoreRedis / SMTPExternal adaptersApplicationUse casesPorts / interfacesOrchestrationDomainEntitiesValue objectsInvariantsCompile-time references point toward inner policy; runtime calls cross interfaces
Dependency direction — implementation details depend inward

الرسمة مفاهيمية: Infrastructure تنفذ interfaces معرفة في الداخل؛ runtime call قد يخرج من Application إلى repository implementation عبر DI، لكن compile-time dependency لا تجعل Application references Infrastructure. ده هو Dependency Inversion عمليًا.

Dependency Graph عملي: راجع اتجاه كل Reference

أهم اختبار لـ Clean Architecture مش اسم الـ folders؛ هو مين يقدر يعمل reference لمين؟ تخيل Solution فيها Domain و Application و Infrastructure و API. الاتجاه المقبول غالبًا: Application يعتمد على Domain، و Infrastructure يعتمد على Application و Domain لتنفيذ الـ ports، و API يعتمد على Application ويستدعي composition root لتسجيل Infrastructure. Domain لا يعرف EF Core ولا ASP.NET ولا أي SDK خارجي.

الـ Dependency Rule تخص compile-time references، مش ترتيب استدعاء runtime. وقت التشغيل قد ينادي Application interface ثم يصل التنفيذ إلى Infrastructure بسبب Dependency Injection. ده مش كسر للقاعدة؛ لأن الـ source code في Application لا يعتمد على concrete adapter.

TextAllowed project reference direction
MyShop.Domain          -> no project references
MyShop.Application    -> MyShop.Domain
MyShop.Infrastructure -> MyShop.Application, MyShop.Domain
MyShop.Api            -> MyShop.Application, MyShop.Infrastructure
MyShop.ArchitectureTests -> projects under test

راجع الاتجاه آليًا في CI. وجود namespace اسمه Domain داخل API لا يثبت إن التصميم سليم. افحص csproj references و NuGet dependencies، وابحث عن تسريب HttpContext أو DbContext أو IConfiguration إلى Domain. لو Domain محتاج الوقت، مرر قيمة أو abstraction صغيرة مثل IClock في Application، ولا تربطه بـ System.Web أو ASP.NET.

C#A use case depends on a port, not DbContext
public interface IOrderStore
{
    Task<Order?> FindAsync(Guid id, CancellationToken ct);
    Task SaveAsync(Order order, CancellationToken ct);
}

public sealed class CancelOrderHandler(IOrderStore orders)
{
    public async Task Handle(Guid id, CancellationToken ct)
    {
        var order = await orders.FindAsync(id, ct)
            ?? throw new NotFoundException("Order was not found.");
        order.Cancel();
        await orders.SaveAsync(order, ct);
    }
}

لكن لا تحوّل كل class إلى interface لمجرد اتباع القاعدة. اعمل abstraction عند حدّ تغيير أو عند boundary خارجي أو عندما تحتاج بديلًا/اختبارًا. كثرة interfaces التي لا تمثل contract حقيقيًا تجعل التنقل أصعب ولا تضيف استقلالًا فعليًا.

Dependency Rule بالتفصيل: Source Code Dependencies مش Runtime Calls

قاعدة Clean Architecture تتكلم أساسًا عن اتجاه اعتماد source code: أسماء الـ types والـ interfaces التي يترجم إليها مشروع داخلي يجب ألا تجبره على معرفة مشروع خارجي. في runtime قد يستدعي Use Case interface، والـ implementation الموجودة في Infrastructure تستقبل النداء عبر DI. لذلك لا يوجد تناقض بين compile-time dependency إلى الداخل و runtime control flow إلى الخارج ثم العودة بالنتيجة.

مثال: CreateInvoiceHandler يحتاج IInvoiceRepository. ضع contract في Application إذا كانت حاجة use case، أو في Domain إذا كانت domain policy نفسها تملك abstraction. Infrastructure تنفذ contract باستخدام EF Core. لا تضع IRepository<T> تلقائيًا في Domain لمجرد أن كل شيء يجب أن يكون interface؛ ضع abstraction حيث يوجد consumer policy، واجعلها تعبّر عن operations المطلوبة لا عن كل CRUD الممكن.

لا تخلط Dependency Inversion Principle مع Dependency Injection: DIP مبدأ تصميم، DI آلية composition/runtime wiring. يمكنك تطبيق DIP يدويًا عبر constructor injection، ووجود DI container لا يجعل architecture نظيفة إذا كانت كل الطبقات تعتمد على Infrastructure مباشرة.

03

Domain Layer: business model وليس مكان EF

Entities, value objects and invariants
Deep dive

Domain layer تحتوي business concepts والقواعد التي يجب أن تظل صحيحة بغض النظر عن طريقة التخزين أو النقل. أمثلة: Order، Money، Reservation، Product، Domain Events، Policies. Domain لا تعرف DbContext أو HttpContext أو Redis. تجنب attributes/configuration الخاصة بالـ persistence داخل domain إذا كان الفصل مهمًا، لكن لا تحول كل property إلى abstraction بلا سبب.

Rich domain model مناسب عندما توجد invariants وسلوك lifecycle معقد. CRUD-heavy app قد يكون anemic model أبسط. المهم أن قواعد business لا تتبعثر في controllers أو EF configurations أو background jobs. لا تجعل domain entity تنفذ IO؛ أعطها بياناتها واطلب منها قرارًا/transition.

C#Domain entity protects an invariant
public sealed class Order
{
    private readonly List<OrderItem> _items = [];
    public Guid Id { get; private set; }
    public IReadOnlyCollection<OrderItem> Items => _items.AsReadOnly();
    public OrderStatus Status { get; private set; } = OrderStatus.Draft;

    public void AddItem(ProductSnapshot product, int quantity)
    {
        if (Status != OrderStatus.Draft)
            throw new DomainException("Items can only be added to a draft order.");
        if (quantity <= 0)
            throw new DomainException("Quantity must be positive.");
        _items.Add(new OrderItem(product, quantity));
    }

    public void Confirm()
    {
        if (_items.Count == 0)
            throw new DomainException("An empty order cannot be confirmed.");
        Status = OrderStatus.Confirmed;
    }
}

الـ domain لا تعرف كيف يتم حفظ Order؛ هي تحمي state. لو احتجت uniqueness عبر عدة orders أو stock concurrency، domain logic وحدها لا تكفي؛ database constraint/transaction/atomic update يحمي invariant عبر concurrent operations.

04

Application Layer: Use Cases و Orchestration

Coordinate work without owning domain rules
Deep dive

Application layer تنفذ use cases: PlaceOrder، CancelReservation، UpdateProfile. تستقبل command/query models، تتحقق من input/application-level preconditions، تحمل aggregates عبر ports، تنادي domain behavior، تحفظ التغييرات، وتنسق external effects. هي لا ينبغي أن تتحول إلى مكان كل business rule؛ لو rule تخص state entity، ضعها في domain model أو domain service.

Application service عادة تعرف interfaces مثل IOrderRepository و IUnitOfWork و IPaymentGateway. هذه interfaces تعبر عن احتياج use case، وليس تفاصيل implementation. Validation في Application قد يتحقق من وجود required IDs/format، أما invariant مثل «لا يمكن تأكيد order فارغ» في domain.

C#Place order use case
public sealed record PlaceOrderCommand(Guid CustomerId,
    IReadOnlyList<PlaceOrderItem> Items);

public sealed class PlaceOrderHandler(
    ICustomerRepository customers,
    IProductCatalog products,
    IOrderRepository orders,
    IUnitOfWork unitOfWork)
{
    public async Task<Guid> Handle(PlaceOrderCommand command, CancellationToken ct)
    {
        var customer = await customers.GetAsync(command.CustomerId, ct)
            ?? throw new NotFoundException("Customer not found.");

        var order = Order.Create(customer.Id);
        foreach (var requested in command.Items)
        {
            var product = await products.GetSnapshotAsync(requested.ProductId, ct)
                ?? throw new NotFoundException("Product not found.");
            order.AddItem(product, requested.Quantity);
        }

        order.Confirm();
        await orders.AddAsync(order, ct);
        await unitOfWork.SaveChangesAsync(ct);
        return order.Id;
    }
}

ده مثال توضيحي؛ التطبيق الحقيقي قد يحتاج bulk product lookup، stock reservation، pricing policy، idempotency و outbox. لا تنفذ external payment داخل DB transaction طويلة. Use case ينسق الخطوات ويحدد transaction boundary، لكنه لا يضمن distributed atomicity.

05

Infrastructure Layer: Implementations and Adapters

EF Core, Redis, SMTP and external systems
Deep dive

Infrastructure تنفذ التفاصيل: EF Core DbContext/configurations/repositories، Redis cache، SMTP/email، payment gateway، file storage، message broker. هي تعرف interfaces التي تحتاجها Application/Domain، وتقدم implementations. لا تجعل Application references Infrastructure project لمجرد استخدام concrete repository.

C#Infrastructure repository implementation
public sealed class EfOrderRepository(AppDbContext db) : IOrderRepository
{
    public Task<Order?> GetAsync(Guid id, CancellationToken ct) =>
        db.Orders.Include(x => x.Items)
            .SingleOrDefaultAsync(x => x.Id == id, ct);

    public Task AddAsync(Order order, CancellationToken ct) =>
        db.Orders.AddAsync(order, ct).AsTask();
}

خلي EF configuration في Infrastructure باستخدام IEntityTypeConfiguration. لو Domain entities فيها private fields/constructors، اضبط mapping بعناية واختبر materialization. لا تستخدم generic repository يخفي كل قدرات EF Core ويجبرك تعمل عشرات methods عامة؛ repository interface يجب أن يعبر عن aggregate/use-case needs.

06

API / Presentation Layer: Thin Endpoints

Transport concerns and DTO boundaries
Practical

API layer مسؤولة عن HTTP: routing، binding، authentication metadata، response status، serialization، OpenAPI. تستقبل request DTO وتحولها إلى command، تستدعي Application، ثم تحول result إلى response DTO. لا تضع business workflow طويلًا داخل endpoint ولا ترجع EF entity مباشرة للعميل.

C#Thin Minimal API endpoint
app.MapPost("/orders", async (
    CreateOrderRequest request,
    PlaceOrderHandler handler,
    CancellationToken ct) =>
{
    var command = new PlaceOrderCommand(request.CustomerId,
        request.Items.Select(x => new PlaceOrderItem(x.ProductId, x.Quantity)).ToArray());
    var id = await handler.Handle(command, ct);
    return Results.Created($"/orders/{id}", new { id });
}).RequireAuthorization();

DTOs تحمي contract من تغير domain/persistence schema، وتسمح بالـ validation والـ versioning. Mapping ليس هدفًا بذاته؛ لو mapping trivial استخدم code واضح. في endpoints كثيرة، feature-based folders أو endpoint classes تساعد التنظيم.

07

Interfaces و Dependency Injection و Composition Root

Wire the object graph at the edge
Deep dive

Composition Root هو المكان الذي يعرف concrete implementations ويربطها بال interfaces، غالبًا Program.cs أو extension methods لكل layer. الـ DI container يبني object graph. Application لا تحتاج تعرف أن IOrderRepository تنفذها EfOrderRepository؛ composition root هو الذي يقرر.

C#Register layers at the composition root
// API project / Program.cs
builder.Services.AddApplication();
builder.Services.AddInfrastructure(builder.Configuration);

// Infrastructure extension:
services.AddDbContext<AppDbContext>(...);
services.AddScoped<IOrderRepository, EfOrderRepository>();
services.AddScoped<IUnitOfWork, EfUnitOfWork>();

راجع lifetimes: DbContext Scoped غالبًا، repository الذي يستخدمه Scoped، stateless singleton service فقط لو thread-safe ولا يحتفظ بـ scoped dependency. لا تحقن Scoped service داخل Singleton. لا تجعل Domain يعتمد على DI container؛ constructor injection أو factory domain واضحة تكفي.

Composition Root و DI Lifetimes في Solution متعددة المشاريع

API تعرف كل modules وتستدعي extension methods. Application تسجل handlers/validators؛ Infrastructure تسجل DbContext/repositories/gateways. تجنب أن Infrastructure تستدعي API registration أو Domain تعرف container. الـ project references تعبر عن compile-time dependency، والـ DI registrations تعبر عن runtime object graph.

C#Layer registration extensions
// MyShop.Application
public static IServiceCollection AddApplication(this IServiceCollection services)
{
    services.AddScoped<PlaceOrderHandler>();
    services.AddScoped<CancelOrderHandler>();
    services.AddValidatorsFromAssembly(typeof(AddApplicationMarker).Assembly);
    return services;
}

// MyShop.Infrastructure
public static IServiceCollection AddInfrastructure(
    this IServiceCollection services, IConfiguration configuration)
{
    services.AddDbContext<AppDbContext>(options =>
        options.UseSqlServer(configuration.GetConnectionString("Default")));
    services.AddScoped<IOrderRepository, EfOrderRepository>();
    services.AddScoped<IUnitOfWork, EfUnitOfWork>();
    return services;
}

راجع lifetimes: DbContext scoped، repository scoped، stateless singleton only when thread-safe and independent of scoped state. لا تجعل singleton cache يحتفظ بـ DbContext. لو background worker يحتاج scoped dependencies، أنشئ scope لكل execution عبر IServiceScopeFactory أو استخدم IDbContextFactory.

08

Project References و Folder Structure

Enforce boundaries with the build
Practical

هيكل شائع:

TextSolution structure
MyShop.sln
src/
  MyShop.Domain/          # no project references outward
  MyShop.Application/     # references Domain
  MyShop.Infrastructure/  # references Application + Domain
  MyShop.Api/             # references Application + Infrastructure
 tests/
  MyShop.Domain.Tests/
  MyShop.Application.Tests/
  MyShop.Infrastructure.IntegrationTests/

Project references تفرض جزءًا من Dependency Rule compile-time. لكن folders وحدها لا تفرضها. Architecture tests مثل NetArchTest أو ArchUnitNET تقدر تمنع Domain من referencing Microsoft.AspNetCore أو Infrastructure namespaces. راجع architecture rules في CI حتى لا تنحرف الحدود مع الوقت.

Folder by layer مناسب لو الفريق صغير والـ layers واضحة. Folder by feature يجمع use case files حسب business capability مثل Orders/Create، Orders/Cancel. ممكن تجمع feature folders داخل Application مع إبقاء project boundaries. لا تخلط feature organization مع dependency direction؛ هما محوران مختلفان.

09

اختبار كل Layer

Test where behavior lives
Deep dive

Domain tests سريعة من غير mocks غالبًا؛ اختبر invariants و state transitions. Application tests تستخدم fakes/mocks للـ ports وتتحقق من orchestration/error mapping. Infrastructure integration tests تستخدم database/provider حقيقيًا لاختبار SQL mapping/transactions. API tests تتحقق من HTTP contracts/authentication/authorization. لا تحاول mock EF Core LINQ provider لاختبار query translation.

C#Architecture rule — conceptual test
[Fact]
public void Domain_must_not_reference_infrastructure()
{
    var result = Types.InAssembly(typeof(Order).Assembly)
        .ShouldNot().HaveDependencyOn("MyShop.Infrastructure")
        .GetResult();
    Assert.True(result.IsSuccessful);
}

Architecture tests ليست بديلًا عن code review، لكنها تمنع dependency drift. اختبر project references الفعلية و namespace dependencies حسب rules واضحة، ولا تكتب rule تمنع dependencies مفيدة داخل layer من غير سبب.

10

Modular Monolith و Vertical Slice كبدائل أو مكملات

Organize by business capability
Deep dive

Modular Monolith تطبيق واحد deployment/runtime لكن مقسم إلى modules لها ownership وحدود واضحة، وربما schemas/contracts داخلية. غالبًا خطوة أفضل من microservices مبكرة: تحافظ على simplicity التشغيلية مع منع shared-everything. لا تجعل كل module يقرأ جداول module أخرى مباشرة؛ عرّف module APIs/events أو read models.

Vertical Slice Architecture تنظم الكود حسب feature/use case بدل فصل كل controllers/services/repositories في folders عامة. كل slice تحتوي request/handler/validator/response وربما query. ده يقلل التنقل بين layers في features بسيطة، ويمكن أن يتعايش مع Domain و Infrastructure boundaries.

Clean Architecture و Vertical Slice ليستا متعارضتين بالضرورة. الأولى تحدد dependency boundaries، والثانية طريقة تنظيم features داخل تلك الحدود. اختَر أقل structure يوضح ownership ويقلل coupling.

Modular Monolith: حدود داخل نفس Deployment

في modular monolith، كل module يملك use cases و domain model و persistence boundary الخاصة به، لكن deployment واحد. مثال: Catalog، Ordering، Billing، Identity. التواصل عبر module contracts أو internal events، وليس direct access عشوائي لجداول module آخر. يمكن أن تبدأ ب schema واحدة مع ownership convention، ثم تفصل storage عند وجود سبب.

لا تجعل modular monolith مجرد folders. الحدود تحتاج ownership: من يكتب أي tables؟ من يملك events/contracts؟ هل module تستطيع استدعاء implementation داخلية لأخرى؟ architecture tests و code review يساعدان. ده غالبًا يتيح استخراج service لاحقًا أسهل من monolith متشابك، من غير دفع تكلفة network calls الآن.

Modular Monolith: حدود Modules قبل القفز إلى Microservices

Modular Monolith تطبيق واحد قابل للنشر، لكنه مقسم إلى modules لها APIs داخلية وملكية بيانات وقواعد اعتماد واضحة. مثال: Catalog و Ordering و Billing. لا تجعل كل module يقرأ جداول module أخرى مباشرة؛ قدّم contract أو query interface. لا تشارك Domain Entities عبر modules؛ شارك primitives أو contracts مستقرة فقط عند الضرورة.

الفائدة: deployment و local transactions أسهل من microservices، مع تقليل coupling إذا فرضت boundaries. الخطر: يتحول إلى monolith عادي إذا كل module تستطيع الوصول لكل tables والـ internal classes. استخدم project boundaries أو namespaces + architecture tests، وسجل module ownership و allowed dependencies. استخراج service لاحقًا يصبح أسهل لكنه ليس مجانيًا؛ ستحتاج network contracts و distributed consistency.

11

إمتى Clean Architecture تكون Overkill؟

Avoid ceremony and accidental complexity
Deep dive

لو التطبيق CRUD صغير، business rules قليلة، فريق واحد، وتغييرات محدودة، قد تكفي طبقات بسيطة أو vertical slices مع DbContext. لا تضف repository فوق كل DbSet إذا كان لا يضيف domain meaning أو test boundary. لا تضف mediator لكل method لو direct call أوضح. لا تكرر DTOs في كل طبقة من غير حاجة.

علامات overengineering: interfaces لها implementation واحدة بلا سبب تغيير، mapping classes أكثر من business logic، use case يمر عبر 8 layers لعملية بسيطة، generic abstractions يصعب debug، أو domain model لا يحتوي behavior فعليًا. راجع التصميم على أساس change cost وليس عدد patterns.

12

اختبر فهمك

Knowledge check
Practical
ما المقصود بأن dependencies تشير للداخل؟
Outer details مثل Infrastructure/API تعتمد compile-time على abstractions/domain داخلية؛ Domain لا تعرف التفاصيل الخارجية.
هل Application layer هي مكان كل business rules؟
لا؛ هي تنسق use cases، أما invariants والسلوك الذي يخص domain objects فيكون في Domain.
من يعرف EF Core implementation؟
Infrastructure و composition root؛ Application تعتمد على repository/unit-of-work contracts.
هل كل مشروع يحتاج Clean Architecture؟
لا؛ حجم القواعد والتغيير والاختبار يحدد قيمة الفصل. CRUD صغير قد يكون أبسط ببنية أخف.
هل Vertical Slice عكس Clean Architecture؟
لا؛ الأولى تنظيم feature code، والثانية dependency direction؛ يمكن الجمع بينهما.
13

Domain Logic vs Application Logic: مثال تفصيلي

Business decision versus use-case coordination
Deep dive

تمييز مهم: «هل يمكن إلغاء الحجز الآن؟» business decision تعتمد على reservation state/cancellation policy، ومكانها domain. «حمّل reservation، اجلب policy، نفذ cancellation، احفظ، وسجل outbox message» orchestration، ومكانها application. «هل request body فيها reason؟» input validation عند API/Application boundary. «كيف نحفظ reservation؟» Infrastructure.

C#Domain owns the cancellation rule
public void Cancel(DateTimeOffset now, CancellationPolicy policy)
{
    if (Status is not ReservationStatus.Confirmed)
        throw new DomainException("Only confirmed reservations can be cancelled.");
    if (!policy.CanCancel(CheckIn, now))
        throw new DomainException("Cancellation window has passed.");
    Status = ReservationStatus.Cancelled;
}
C#Application coordinates the use case
public async Task CancelAsync(Guid id, string reason, CancellationToken ct)
{
    var reservation = await repository.GetForUpdateAsync(id, ct)
        ?? throw new NotFoundException();
    reservation.Cancel(clock.UtcNow, cancellationPolicy);
    await outbox.AddAsync(ReservationCancelled.From(reservation, reason), ct);
    await unitOfWork.SaveChangesAsync(ct);
}

لو حطيت cancellation rule في controller، worker أو admin command قد يتجاوزها. ولو حطيت repository lookup داخل entity، domain أصبحت تعرف persistence. الفصل يحافظ على أن أي entry point تستخدم نفس rule.

14

Validation و Error Handling بين الطبقات

Map failures at the boundary
Practical

Validation لها مستويات: API model validation تتحقق من shape/required/range؛ Application validation تتحقق من use-case prerequisites مثل وجود identifier أو permission؛ Domain validation تحمي invariants؛ Database constraints تحمي integrity عبر كل writers. لا تكرر نفس validation في خمس طبقات من غير سبب، لكن لا تعتمد على طبقة واحدة لحماية كل شيء.

Application لا ترجع IResult أو ActionResult؛ دي HTTP concerns. ارجع typed result/error codes أو exceptions متفق عليها. API maps NotFound إلى 404، Validation إلى 400/422، Conflict إلى 409، Forbidden إلى 403. Infrastructure exceptions لا تتسرب للعميل مع connection strings/SQL.

Validation و Error Mapping بين Layers

API validation تفحص shape/format/required fields، Application validation تفحص use-case preconditions، Domain invariants تحمي business state. لا تضع IResult أو ProblemDetails داخل Domain؛ هذه HTTP concepts. Application قد ترجع typed errors/Result، و API layer تحولها إلى 400/404/409/422 حسب contract.

مثال: Quantity لازم integer أكبر من صفر. API model binding/DataAnnotations تقدر تمنع string غير صالح؛ domain value object يضمن positive quantity حتى لو object اتبنى من background job أو test. أما «المخزون يكفي الآن؟» فهو invariant يحتاج transaction/concurrency control مع storage، وليس validation ثابتة فقط.

C#Domain value object protects a basic invariant
public readonly record struct Quantity
{
    public int Value { get; }
    private Quantity(int value) => Value = value;

    public static Quantity Create(int value) => value > 0
        ? new Quantity(value)
        : throw new DomainException("Quantity must be positive.");
}

لا تكرر نفس validation message في كل layer بلا داعٍ. لكن لا تعتمد على API layer وحدها لحماية domain. حافظ على mapping centralized وواضح، وسجل error code/correlation ID بدل تفاصيل حساسة.

15

Architecture Tests تمنع Dependency Drift

Turn architectural decisions into executable rules
Deep dive

Architecture decision لو ظلت في README فقط قد تُكسر بعد شهر. اكتب tests تمنع Domain من الاعتماد على Infrastructure/ASP.NET Core، وتمنع Application من استخدام DbContext مباشرة لو قرارك أن repository ports هي boundary. اختبر naming/namespace conventions عند الحاجة، لكن لا تضع rules معقدة لدرجة أن كل refactor يصبح معركة مع test.

C#Conceptual architecture tests
[Fact]
public void Domain_does_not_depend_on_outer_layers()
{
    var result = Types.InAssembly(typeof(Order).Assembly)
        .ShouldNot().HaveDependencyOn("MyShop.Infrastructure")
        .And().ShouldNot().HaveDependencyOn("Microsoft.AspNetCore")
        .GetResult();

    Assert.True(result.IsSuccessful);
}

[Fact]
public void Application_does_not_reference_web_types()
{
    var result = Types.InAssembly(typeof(PlaceOrderHandler).Assembly)
        .ShouldNot().HaveDependencyOn("Microsoft.AspNetCore.Http")
        .GetResult();
    Assert.True(result.IsSuccessful);
}

أسماء APIs تختلف حسب NetArchTest/ArchUnitNET version؛ اعتبر الكود illustration وتحقق من package API الفعلية. المهم أن rule تعكس dependency policy حقيقية وتعمل في CI.

Architecture Tests و Project Dependency Enforcement

Architecture rule المكتوبة في README يمكن أن تُنسى. استخدم project references و architecture tests/Analyzers لمنع Domain من الاعتماد على ASP.NET Core/Infrastructure، ومنع Application من الاعتماد على provider SDKs. راجع namespace dependencies و assembly references معًا؛ مجرد عدم وجود project reference لا يمنع reflection أو shared utility project من تسريب detail.

قواعد مقترحة: Domain لا references أي project داخل solution؛ Application references Domain فقط؛ Infrastructure references Application/Domain؛ API references Application و Infrastructure composition root. Tests projects لها references منفصلة. لا تجعل Common أو Shared project بابًا خلفيًا لكل dependencies؛ كل abstraction تحتاج owner واضح.

اختبر قواعد architecture في CI. عند خرق rule، اطلب exception موثقًا في ADR بدل إسكات analyzer بشكل دائم. Architecture tests لا تثبت أن design جيد، لكنها تحمي بعض boundaries من التآكل مع الوقت.

Architecture Test: امنع تسريب Infrastructure إلى Domain

الاختبار المعماري يحوّل قرار التصميم إلى guardrail. مثال باستخدام ArchUnitNET أو NetArchTest: تأكد أن Domain لا يعتمد على Infrastructure أو ASP.NET Core أو EF Core. أسماء المكتبات وواجهاتها تتغير حسب إصدارها؛ لذلك ثبّت إصدار الأداة في المشروع وراجع API الخاص به عند التطبيق، ولا تنسَ أن static architecture test لا يفهم كل dependency مخفية عبر reflection أو runtime configuration.

C#Illustrative architecture rule (NetArchTest style)
var result = Types.InAssembly(domainAssembly)
    .ShouldNot()
    .HaveDependencyOn("Microsoft.EntityFrameworkCore")
    .GetResult();

Assert.True(result.IsSuccessful,
    "Domain must not depend on Entity Framework Core.");

أضف قواعد ثانية: API لا يصل إلى Infrastructure repositories مباشرة إذا كان الاتفاق أن كل العمليات تمر عبر Application؛ لا توجد circular project references؛ و Domain لا يحتوي DTOs خاصة بالـ HTTP. لا تبالغ في منع كل استخدام framework type: القرار يجب أن يحمي boundary حقيقية، وليس تحويل الاختبارات إلى قائمة ممنوعات بلا مبرر.

Architecture Tests و ADR: اجعل التصميم قابلًا للفحص

اكتب architecture tests تمنع Domain من reference إلى EF Core/ASP.NET Core، وتمنع module من reference إلى internals في module أخرى، وتمنع cycles بين assemblies. لا تعتمد على convention مكتوب فقط؛ guardrail آلي يمنع regression. لكن الاختبارات لا تثبت جودة التصميم كاملة؛ قد يمر dependency graph نظيف بينما use cases ما زالت متشابكة منطقيًا.

اكتب ADR لكل قرار مكلف أو صعب الرجوع: context، constraints، options، decision، consequences، revisit triggers. مثال: اختيار modular monolith لأن team صغيرة والمعاملات المحلية مهمة، مع trigger لإعادة التقييم عند الحاجة إلى independent scaling أو ownership منفصل. ADR ليس documentation لكل سطر؛ هو ذاكرة القرار.

Architecture Test: امنع تسريب Infrastructure إلى Domain

الاختبار المعماري يحوّل قرار التصميم إلى guardrail. مثال باستخدام ArchUnitNET أو NetArchTest: تأكد أن Domain لا يعتمد على Infrastructure أو ASP.NET Core أو EF Core. أسماء المكتبات وواجهاتها تتغير حسب إصدارها؛ لذلك ثبّت إصدار الأداة في المشروع وراجع API الخاص به عند التطبيق، ولا تنسَ أن static architecture test لا يفهم كل dependency مخفية عبر reflection أو runtime configuration.

C#Illustrative architecture rule (NetArchTest style)
var result = Types.InAssembly(domainAssembly)
    .ShouldNot()
    .HaveDependencyOn("Microsoft.EntityFrameworkCore")
    .GetResult();

Assert.True(result.IsSuccessful,
    "Domain must not depend on Entity Framework Core.");

أضف قواعد ثانية: API لا يصل إلى Infrastructure repositories مباشرة إذا كان الاتفاق أن كل العمليات تمر عبر Application؛ لا توجد circular project references؛ و Domain لا يحتوي DTOs خاصة بالـ HTTP. لا تبالغ في منع كل استخدام framework type: القرار يجب أن يحمي boundary حقيقية، وليس تحويل الاختبارات إلى قائمة ممنوعات بلا مبرر.

16

Transaction Boundaries و Outbox في Clean Architecture

Atomic database work versus external side effects
Deep dive

Use case يحدد business transaction boundary: أي تغييرات لازم تنجح أو تفشل معًا داخل نفس database transaction؟ Repository/UoW abstractions لا تعني أن كل call تعمل transaction منفصلة. في EF Core، SaveChanges غالبًا ينفذ changes في transaction واحدة عند دعم provider؛ لو workflow يحتاج عدة SaveChanges/commands، حدد explicit transaction strategy.

لا تحتفظ transaction مفتوحة أثناء HTTP call إلى payment provider أو SMTP أو message broker. الشبكة قد تتأخر أو تفشل، فتطول locks وتزيد deadlocks. بدلًا من ذلك استخدم local transaction لحفظ state + outbox intent، ثم background publisher يتعامل مع external delivery. لو business workflow موزع، Saga/compensation قد تكون مطلوبة؛ لا تدعي أن DB transaction تضمن atomicity عبر خدمات مستقلة.

C#Application boundary records an outbox intent
public async Task ConfirmAsync(Guid orderId, CancellationToken ct)
{
    var order = await orders.GetAsync(orderId, ct)
        ?? throw new NotFoundException();

    order.Confirm(clock.UtcNow);
    await outbox.AddAsync(OrderConfirmedIntegrationEvent.From(order), ct);
    await unitOfWork.SaveChangesAsync(ct);
}

الـ outbox record والـ aggregate changes يجب يحفظوا في نفس physical database transaction. مجرد استدعاء AddAsync على repository آخر لا يضمن ذلك؛ تأكد إن الاثنين يستخدمان نفس DbContext/transaction boundary أو آلية مكافئة. publisher يجب يتعامل مع duplicate delivery و retry و dead-letter.

Use Case و Transaction: مين يملك Commit؟

الـ Application Use Case ينسق العملية ويحدد حدودها، لكن تفاصيل SQL transaction تنتمي إلى Infrastructure. لا تجعل كل Repository ينفذ SaveChanges منفصلًا لو العملية تتطلب ذرية بين Order و OrderItems. وإلا قد يُحفظ الطلب وتفشل عناصره، أو العكس. استخدم DbContext واحدًا scoped للعملية، واجعل handler ينهي التغيير عبر abstraction واحدة مثل IUnitOfWork أو persistence port مناسب.

C#Atomic order creation with one unit of work
public sealed class PlaceOrderHandler(
    IOrderRepository orders,
    IUnitOfWork unitOfWork,
    IInventory inventory)
{
    public async Task<Guid> Handle(PlaceOrder command, CancellationToken ct)
    {
        var reservation = await inventory.ReserveAsync(command.Items, ct);
        var order = Order.Place(command.CustomerId, reservation.Items);
        await orders.AddAsync(order, ct);
        await unitOfWork.SaveChangesAsync(ct);
        return order.Id;
    }
}

الكود السابق لا يضمن transaction واحدة لو Inventory خدمة خارجية. لا تحاول وضع distributed transaction بين SQL وخدمة خارجية كحل افتراضي. استخدم workflow: احجز inventory بمفتاح idempotency، احفظ order و outbox message في نفس SQL transaction، ثم worker يرسل الحدث. لو فشل الحجز بعد إنشاء الطلب، نفّذ compensation واضحة مثل CancelOrder. لازم تحدد من البداية حالات Pending/Confirmed/Failed بدل إيهام المستخدم أن العملية ذرية عبر الشبكة.

قاعدة عملية: transaction قصيرة حول state محلي في قاعدة واحدة؛ لا تضع داخلها HTTP calls أو انتظار user input أو عمليات طويلة. طول transaction يزيد locks واحتمال deadlocks ويقلل throughput.

من يملك Transaction؟ Application Use Case أم Repository؟

Repository غالبًا مسؤول عن تحميل وحفظ aggregate، لكنه لا ينبغي أن يبدأ transaction منفصلة لكل method إذا كان use case يحتاج تعديل Order و Inventory في نفس database transaction. EF Core DbContext.SaveChanges ينفذ التغييرات في transaction عند دعم provider، ويمكن Application boundary أن ينسق أكثر من operation أو explicit transaction عند الحاجة. لا تجعل كل repository يفتح ويغلق transaction دون معرفة الصورة الكاملة.

عند وجود أكثر من database أو external API لا توجد ACID transaction واحدة تلقائيًا. لا تحتفظ ب transaction SQL مفتوحة أثناء انتظار payment gateway أو HTTP call؛ هذا يطيل locks ويستهلك connections. استخدم local transaction لحفظ state + outbox، ثم background publisher و workflow/Saga لمعالجة الحدود الموزعة. عرّف حالات Pending/Confirmed/Failed بوضوح حتى لا تعرض نجاحًا لم يحدث.

C#Application boundary commits aggregate and outbox atomically
public sealed class PlaceOrderHandler(AppDbContext db, IClock clock)
{
    public async Task HandleAsync(PlaceOrder command, CancellationToken ct)
    {
        var order = Order.Place(command.CustomerId, command.Items, clock.UtcNow);
        db.Orders.Add(order);
        db.OutboxMessages.Add(OutboxMessage.Create(
            "OrderPlaced", new { order.Id, order.Total }));
        await db.SaveChangesAsync(ct); // one local database commit
    }
}

هذا يفترض أن Orders و OutboxMessages في نفس relational database/context transaction. لا يعني أن message نُشرت بالفعل؛ publisher يعمل لاحقًا ويحتاج retry/idempotency. اختبر atomicity: فشل حفظ outbox يجب أن يمنع commit للطلب، وفشل النشر بعد commit يجب ألا يفقد الحدث.

17

Architecture Decision Records: وثّق لماذا اخترت هذا التصميم

Context, decision and consequences
Practical

ADR وثيقة قصيرة لكل قرار معماري مهم: context/problem، constraints، options، decision، consequences، status و date. أمثلة: modular monolith vs microservices، SQL Server vs PostgreSQL، repository abstraction vs DbContext direct، synchronous request vs background job. وثّق البدائل التي رفضتها والسبب، وليس القرار فقط.

قرار معماري جيد له revisit trigger: «نعيد تقييم CQRS لو read workload أصبح مختلفًا بوضوح عن write model» أفضل من «نستخدم CQRS لأنه best practice». ADR يقلل hidden assumptions ويجعل onboarding و code review أسرع.

ADR عملي: لماذا Modular Monolith بدل Microservices؟

Context: فريق صغير يملك Catalog و Orders و Payments، والعمليات الحالية تحتاج transaction محلية وتغييرات domain مشتركة. Options: (1) monolith بلا boundaries، (2) modular monolith، (3) microservices مستقلة. Decision: modular monolith مع project/module boundaries و architecture tests. Consequences: deployment واحد و transactions محلية أسهل، لكن scale/ownership مستقلان محدودان. Revisit trigger: module لديها team مستقل و load profile مختلف أو release cadence مستقل مع contract مستقر.

هذا القرار ليس قاعدة عامة. لو domains مستقلة فعلًا وفريق تشغيل قادر على distributed systems، microservices قد تكون مناسبة. ADR يمنع اتخاذ قرار معماري بناءً على trend فقط، ويجعل تكلفة الاختيار ومتى نعيد النظر واضحة.

18

تطبيق Clean Architecture تدريجيًا على Codebase موجود

Refactor boundaries without a risky rewrite
Practical

ابدأ برسم dependency map الحالي، وحدد أكثر use case تتغير أو يصعب اختبارها. استخرج domain rules pure أولًا، ثم اجعل application use case تنسقها، ثم عرّف ports عند الحاجة إلى database/HTTP/files. انقل implementation إلى Infrastructure دون تغيير behavior، ثم اجعل API مجرد adapter. بعد كل خطوة شغّل characterization/integration tests. لا تنقل كل الملفات في commit واحد.

لا تبدأ بإنشاء عشر projects إذا الفريق لا يستطيع الحفاظ عليها. يمكن البدء بمجلدات/modules داخل assembly ثم فصل assemblies عندما تحتاج compiler-enforced boundaries. اجعل migration reversible وصغيرة. النجاح يقاس بانخفاض coupling وسهولة اختبار use case، لا بعدد folders أو interfaces.

19

Clean Architecture Review: أسئلة قبل اعتماد Pull Request

Review dependency direction and business ownership
Practical
  • هل Application use case يملك orchestration أم أن controller أصبح workflow engine؟
  • هل Domain يحمي invariants أم يمكن تعديل state مباشرة من أي layer؟
  • هل Infrastructure تفاصيل قابلة للاستبدال أم تسرب EF/SDK types إلى الداخل؟
  • هل transaction boundary واضحة ومتناسبة مع consistency requirement؟
  • هل tests تستخدم real provider حيث تكون SQL translation والقيود جزءًا من الخطر؟
  • هل project references acyclic ومحمية بـ architecture tests؟
  • هل abstraction أضيفت بسبب variation حقيقي أم لمجرد اتباع template؟

راجع أيضًا deployment topology: Clean Architecture لا تفرض microservices أو عددًا محددًا من projects. يمكن أن تكون طبقات متعددة في process واحدة. حافظ على فرق واضح بين architecture policy و framework convention، ووثق أي استثناء له سبب وتاريخ لإعادة التقييم.

20

Operational Concerns لا تسكن في Domain

Keep deployment and observability concerns at the right boundary
Deep dive

Configuration binding و logging و health endpoints و OpenTelemetry exporters و cloud identity غالبًا تفاصيل تشغيلية تُركب عند host/Infrastructure boundary. Domain لا يحتاج أن يعرف Application Insights أو Key Vault أو Docker environment variables. Application قد يطلب ICurrentUser أو IClock كـ port لأن هذه معلومات يحتاجها use case، بينما adapter يقرأها من HTTP context أو TimeProvider.

اختبر أن تشغيل use case لا يحتاج ASP.NET Core host، وأن infrastructure configuration validation تفشل مبكرًا عند startup إذا secret reference أو connection string ناقصة. هذا يحافظ على domain pure ويجعل deployment failures واضحة. لا تنقل كل شيء إلى Infrastructure لمجرد أنه ليس Domain؛ application orchestration لها ownership مستقل.

21

تطبيق Clean Architecture على مشروع MyShop بدون مبالغة

A realistic solution layout and dependency graph
Practical

خلينا نربط الطبقات بمشروع متجر إلكتروني. الـ solution ممكن تحتوي MyShop.Domain و MyShop.Application و MyShop.Infrastructure و MyShop.Api. Domain فيها Order و OrderItem و Money و OrderStatus والقواعد. Application فيها PlaceOrderCommand و handler وواجهات IOrderRepository و IPaymentGateway. Infrastructure فيها AppDbContext و EF configurations و SQL repositories و payment provider adapter. API فيها endpoints و authentication setup و composition root.

اتجاه الـ project references أهم من شكل المجلدات: Domain لا reference أي project آخر. Application references Domain. Infrastructure references Application و Domain لتنفيذ interfaces. API references Application، وغالبًا Infrastructure فقط لتسجيل implementations. لا تجعل Application تستدعي new SqlOrderRepository()؛ سجلها في startup عن طريق extension method مثل AddInfrastructure(configuration).

C#Composition root — wire the outer adapters
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddApplication();
builder.Services.AddInfrastructure(builder.Configuration);
builder.Services.AddAuthentication().AddJwtBearer();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapOrderEndpoints();
app.Run();

خلي AddInfrastructure extension method في Infrastructure، لكنه لا يُستدعى من Domain أو Application. لو connection string ناقصة، افشل عند startup برسالة واضحة بدل ما تكتشف المشكلة عند أول request. الـ API host هو المكان الطبيعي لقراءة environment/configuration وربط adapters.

قرار عملي: لا تنشئ interface لكل class. اعمل port لما Application تحتاج dependency خارجية أو boundary مفيدة للاختبار أو التغيير. لا تعمل IStringHelper حول method pure لا تحتاج substitution. ولا تضع DTOs الخاصة بالـ HTTP في Domain. لو الـ response model يتغير مع API version، يجب ألا يفرض تغييرًا على business entity.

  • اختبار Domain بدون ASP.NET Core أو EF Core.
  • اختبار Application باستخدام fake repositories و fake clock/payment gateway.
  • اختبار Infrastructure مع provider حقيقي أو Testcontainers عند الحاجة.
  • اختبار API للـ routing/authentication/serialization والـ composition الفعلي.
  • ↗

    المراجع والقراءة الإضافية

    References & further reading

    الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

    خريطة التغطية: 23 عنصر من الـ Roadmap ومكان شرحه في الدرس
    RoadmapSeparation of Concerns§01
    RoadmapDependency Rule§02
    RoadmapDomain Layer§02
    RoadmapApplication Layer§02
    RoadmapInfrastructure Layer§02
    RoadmapAPI / Presentation Layer§02
    RoadmapDependency Inversion§02
    RoadmapUse Cases§02
    RoadmapInterfaces and Implementations§02
    RoadmapDependency Injection§07
    RoadmapDomain Logic vs Application Logic§03
    RoadmapPersistence Abstractions§05
    RoadmapDTOs and Mapping§06
    RoadmapValidation§04
    RoadmapError Handling§02
    RoadmapLayer Testing§02
    RoadmapProject References§02
    RoadmapComposition Root§02
    RoadmapWhen Clean Architecture Is Overkill§01
    SuggestedModular Monolith (recommended first step)§01
    SuggestedVertical Slice Architecture (alternative)§01
    SuggestedArchitecture tests (NetArchTest / ArchUnitNET)§02
    SuggestedFolder by feature vs by layer§01

    خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

    محتويات الدرس