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

Hexagonal Architecture (Ports & Adapters) مقارنة بـ Clean وOnion

Hexagonal Architecture vs Clean vs Onion

التلات معماريات بيقولوا نفس الفكرة بلغات مختلفة: الـ domain في النص ومش بيعتمد على أي framework. هنا Hexagonal بالتفصيل (driving/driven ports وadapters)، مقارنة دقيقة مع Clean وOnion، تطبيق كامل في .NET على use case من الـ Capstone، الاختبار عبر الـ ports، وإمتى كل ده زيادة عن اللزوم.

  • Advanced
  • ~8 min read
  • 11 sections
  • 4 code examples
  • 2 diagrams
  • 5 questions
  • Priority L2 · Essential
  • .NET 10 · ASP.NET Core · EF Core 10 · concepts from Cockburn (2005), Palermo (2008), Martin (2012)

بعد الدرس ده هتقدر

  • تشرح Ports & Adapters: driving (primary) مقابل driven (secondary) ports
  • ترسم وتطبق use case كامل بـ hexagonal في .NET (API adapter، persistence adapter، LLM adapter)
  • تقارن Hexagonal وOnion وClean: الفروق الحقيقية مقابل الفروق في المصطلحات
  • تختبر الـ application core عبر الـ ports بـ fakes من غير database ولا HTTP
  • تعرف إمتى الـ hexagonal بيستاهل وإمتى vertical slices أو layered أبسط
  • تتجنب أخطاء شائعة: interfaces لكل حاجة، leaking EF entities، adapters فيها business logic

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

01

الفكرة في جملة: التطبيق في النص، والعالم حواليه adapters

The core idea
Basics

Alistair Cockburn اقترح Hexagonal سنة 2005 عشان يحل مشكلة واحدة: الـ business logic بيتلخبط مع الـ UI والـ database، فما تقدرش تختبره ولا تغيّر التكنولوجيا من غير ما تكسره. الحل: التطبيق (الـ core) بيتكلم مع العالم من خلال ports (interfaces بلغة التطبيق)، وكل تكنولوجيا (HTTP، SQL، queue، LLM) بتتوصل بـ adapter بيترجم بينها وبين الـ port. الشكل السداسي مالوش معنى غير إنه بيدّي «جوانب كتير» للـ ports.

Application coreuse cases + domainno ASP.NET, no EF, no SDKsHTTP API adapterQueue consumerTests / CLIEF Core repositoryLLM clientEmail / webhooksClock / IDsdriving (inbound ports)driven (outbound ports)All source-code dependencies point INTO the hexagon
Driving adapters call the application through inbound ports; the application calls outward through ports implemented by driven adapters
المصطلحالمعنىمثال ‎.NET
Driving (primary) portإزاي العالم بيطلب من التطبيق يعمل حاجةIAskQuestion use case interface، أو handler class
Driving adapterبيحوّل input خارجي لنداء على الـ portMinimal API endpoint، Service Bus consumer، test
Driven (secondary) portاللي التطبيق محتاجه من العالم، بلغته هوIDocumentStore, IAnswerGenerator, IClock
Driven adapterتنفيذ الـ port بتكنولوجيا معينةEfDocumentStore, AzureOpenAiAnswerGenerator
02

Hexagonal مقابل Onion مقابل Clean: الفرق الحقيقي

What actually differs
Deep dive
Hexagonal (2005)appinside vs outside; portsOnion (2008)domainservicesinfra / UIconcentric layers inside the coreClean (2012)Euse casesadaptersframeworksnamed rings + dependency rule
Three drawings of the same dependency rule
HexagonalOnionClean
التركيزالحدود بين التطبيق والعالم (in/out)طبقات داخل الـ core (domain model في المركز)قاعدة الاعتمادية + أدوار محددة (entities، use cases، interface adapters، frameworks)
تنظيم الـ coreما بيفرضش طبقات جوهdomain model ← domain services ← application servicesentities ← use cases (interactors) بـ input/output boundaries
الـ portsمفهوم أساسي وصريحinterfaces في الطبقات الداخليةboundaries/gateways
القاعدة المشتركةالكود الداخلي ما يعرفش أي حاجة عن الخارجي؛ الـ interfaces بيملكها الداخل، والخارج بينفذها (Dependency Inversion)

الخلاصة العملية: لو فاهم الـ dependency rule و DIP، فاهم التلاتة. الفروق في إزاي بتنظم المشاريع والأسماء مش في المبدأ. في الإنترفيو ما تقولش «Hexagonal أحسن من Clean»؛ قول «كلهم بيطبقوا dependency inversion حوالين الـ domain؛ Hexagonal بيركز على الـ ports كحدود، و Clean بيدّي أسماء للطبقات الداخلية».

03

تطبيق كامل: «اسأل عن مستند» في الـ Capstone

A complete use case in .NET
Practical
Textsolution layout
src/
  Knowledge.Core/                    # the hexagon: no package references to ASP.NET/EF/AI SDKs
    Domain/        Document.cs, Answer.cs, TenantId.cs
    Ports/In/      IAskQuestion.cs
    Ports/Out/     IDocumentSearch.cs, IAnswerGenerator.cs, IUsageMeter.cs, IClock.cs
    UseCases/      AskQuestionHandler.cs
  Knowledge.Adapters.Http/           # driving adapter (Minimal API endpoints)
  Knowledge.Adapters.Persistence/    # driven: EF Core + pgvector search
  Knowledge.Adapters.Llm/            # driven: IChatClient-based generator
  Knowledge.Host/                    # composition root: Program.cs wires ports to adapters
tests/
  Knowledge.Core.Tests/              # fast tests with fakes for every outbound port
  Knowledge.Adapters.Tests/          # integration tests per adapter (Testcontainers, fake LLM server)
C#Knowledge.Core: ports and the use case
namespace Knowledge.Core.Ports.In;
public sealed record AskQuestionCommand(TenantId Tenant, Guid UserId, string Question);
public interface IAskQuestion { Task<AnswerResult> HandleAsync(AskQuestionCommand cmd, CancellationToken ct); }

namespace Knowledge.Core.Ports.Out;
public interface IDocumentSearch { Task<IReadOnlyList<Passage>> SearchAsync(TenantId tenant, string query, int k, CancellationToken ct); }
public interface IAnswerGenerator { Task<GeneratedAnswer> GenerateAsync(string question, IReadOnlyList<Passage> passages, CancellationToken ct); }
public interface IUsageMeter { Task<bool> TryConsumeAsync(TenantId tenant, int estimatedTokens, CancellationToken ct); }

namespace Knowledge.Core.UseCases;
public sealed class AskQuestionHandler(IDocumentSearch search, IAnswerGenerator generator, IUsageMeter meter) : IAskQuestion
{
    public async Task<AnswerResult> HandleAsync(AskQuestionCommand cmd, CancellationToken ct)
    {
        if (string.IsNullOrWhiteSpace(cmd.Question) || cmd.Question.Length > 2_000)
            return AnswerResult.Invalid("Question must be 1..2000 characters");
        if (!await meter.TryConsumeAsync(cmd.Tenant, estimatedTokens: 4_000, ct))
            return AnswerResult.LimitReached();

        var passages = await search.SearchAsync(cmd.Tenant, cmd.Question, k: 8, ct);
        if (passages.Count == 0) return AnswerResult.NoSources();             // business rule: never answer without sources

        var answer = await generator.GenerateAsync(cmd.Question, passages, ct);
        var cited = answer.Citations.Where(c => passages.Any(p => p.Id == c)).ToList();
        return cited.Count == 0 ? AnswerResult.NoSources() : AnswerResult.Ok(answer.Text, cited);
    }
}
C#Adapters + composition root
// Driving adapter: HTTP -> port
public static class AskEndpoints
{
    public static void Map(IEndpointRouteBuilder app) =>
        app.MapPost("/api/questions", async (AskRequest req, ITenantContext t, ClaimsPrincipal user, IAskQuestion ask, CancellationToken ct) =>
        {
            var result = await ask.HandleAsync(new(t.TenantId, user.GetUserId(), req.Question), ct);
            return result.ToHttpResult();                                       // mapping to status codes lives in the adapter
        }).RequireAuthorization();
}

// Driven adapter: port -> EF Core + pgvector
public sealed class PgDocumentSearch(AppDb db, IEmbedder embedder) : IDocumentSearch
{
    public async Task<IReadOnlyList<Passage>> SearchAsync(TenantId tenant, string query, int k, CancellationToken ct)
    {
        var v = await embedder.EmbedAsync(query, ct);
        return await db.Chunks.Where(c => c.TenantId == tenant.Value)
            .OrderBy(c => c.Embedding.CosineDistance(v)).Take(k)
            .Select(c => new Passage(c.Id, c.DocumentId, c.Text)).ToListAsync(ct);   // EF entities never leave the adapter
    }
}

// Composition root (Knowledge.Host/Program.cs)
builder.Services.AddScoped<IAskQuestion, AskQuestionHandler>();
builder.Services.AddScoped<IDocumentSearch, PgDocumentSearch>();
builder.Services.AddScoped<IAnswerGenerator, ChatClientAnswerGenerator>();
builder.Services.AddScoped<IUsageMeter, RedisUsageMeter>();

لاحظ: قاعدة «ما تجاوبش من غير مصادر» وفحص الـ citations موجودين في الـ core — مش في الـ prompt ولا في الـ controller. يعني تقدر تختبرهم في milliseconds، وتغيّر الـ LLM provider من غير ما تلمسهم.

04

الاختبار عبر الـ ports

Testing through ports
Practical
C#core tests: no database, no HTTP, no model
public sealed class AskQuestionHandlerTests
{
    private readonly FakeSearch _search = new();
    private readonly FakeGenerator _gen = new();
    private readonly FakeMeter _meter = new() { Allow = true };
    private AskQuestionHandler Sut() => new(_search, _gen, _meter);

    [Fact]
    public async Task Refuses_when_no_passages_are_found()
    {
        _search.Results = [];
        var r = await Sut().HandleAsync(new(new TenantId(Guid.NewGuid()), Guid.NewGuid(), "What is the leave policy?"), default);
        Assert.Equal(AnswerStatus.NoSources, r.Status);
        Assert.Equal(0, _gen.Calls);                                // the model is never called without evidence
    }

    [Fact]
    public async Task Drops_citations_that_were_not_retrieved()
    {
        var p = new Passage(Guid.NewGuid(), Guid.NewGuid(), "3 sick days without a certificate");
        _search.Results = [p];
        _gen.Next = new GeneratedAnswer("3 days [x]", Citations: [Guid.NewGuid()]);   // hallucinated citation
        var r = await Sut().HandleAsync(new(new TenantId(Guid.NewGuid()), Guid.NewGuid(), "sick leave?"), default);
        Assert.Equal(AnswerStatus.NoSources, r.Status);
    }
}
نوع الاختباربيختبرالأدوات
Core (unit)القواعد والـ orchestrationfakes للـ outbound ports — سريع جدًا
Adapter (integration)إن الـ adapter بينفذ الـ port صح مع التكنولوجيا الحقيقيةTestcontainers (Postgres)، WireMock/fake LLM server
Contract للـ portكل implementation للـ port بيلتزم بنفس السلوكabstract test class بيشتغل على الـ fake والحقيقي (LSP)
End-to-endالـ wiring نفسهWebApplicationFactory — قليل

الـ «contract test للـ port» نقطة قوية: لو الـ FakeSearch بيرجع نتايج مرتبة والحقيقي لأ، اختبارات الـ core بتكدب عليك. اكتب نفس مجموعة الاختبارات وشغّلها على الاتنين.

05

إمتى يستاهل؟ وإمتى vertical slices أحسن؟

When it pays off
Deep dive
الموقفالأنسب
Domain logic غني ومعقد (قواعد، invariants)، وعمر طويل، وتكنولوجيات بتتغير (LLM providers!)Hexagonal/Clean
CRUD معظمه، قواعد قليلةVertical slices أو layered بسيط — ports لكل حاجة = ceremony
Microservice صغير بيعمل حاجة واحدةمشروع واحد بـ folders، مع ports بس للـ dependencies الخارجية الحساسة
Prototype/spikeأبسط حاجة؛ هتترمي أو هتتعمل refactor

الحل الوسط الشائع: vertical slices لتنظيم الـ features، وجوه كل slice الـ dependencies الخارجية «المكلفة أو المتغيرة» (LLM، payments، email، clock) وراء ports. ده بيدّيك أغلب فوايد الـ hexagonal (testability، تبديل الـ providers) من غير مشروع لكل طبقة.

06

تصميم الـ ports: لغة التطبيق مش لغة التكنولوجيا

Designing good ports
Deep dive
Port سيءليه سيءPort أحسن
IDbRepository<T>.Query(Expression<Func<T,bool>>)بيسرّب IQueryable/EF semantics للـ core؛ مش كل expression بيتترجمIDocumentSearch.SearchAsync(tenant, query, k)
IOpenAiClient.CreateChatCompletion(OpenAiRequest)اسم provider و DTOs بتاعته جوه الـ coreIAnswerGenerator.GenerateAsync(question, passages)
IHttpSender.PostJson(url, body)تفاصيل transportIWebhookPublisher.PublishAsync(TenantEvent)
DateTime.UtcNow مباشرة في الـ domainالوقت dependency مخفية؛ اختبارات الـ expiry مستحيلةTimeProvider (موجود في ‎.NET 8+) يتحقن

حجم الـ port: اعمل port بالشكل اللي الـ use case محتاجه (Interface Segregation)، مش «كل حاجة ممكن تتعمل على الـ documents». port صغير = fake سهل واختبار واضح. والـ errors جزء من الـ port: لو الـ adapter ممكن يفشل بـ «rate limited» أو «not found»، عرّف ده بلغة التطبيق (result types أو exceptions بتاعة الـ core) والـ adapter يترجم أخطاء الـ SDK ليها — وإلا الـ core هيعمل catch لـ HttpRequestException وتبقى معتمد على التفاصيل تاني.

07

Migration تدريجي لمشروع موجود

Moving an existing codebase toward ports
Practical
  1. ابدأ بالـ dependencies اللي بتوجعك: الـ LLM provider والـ payment gateway والـ email — استخرج port لكل واحد، والـ adapter = الكود الحالي متغلّف.
  2. انقل الـ business rules من الـ controllers لـ handlers بتعتمد على الـ ports دي بس.
  3. اكتب tests للـ handlers بـ fakes — دي أول مكسب ملموس (اختبارات في ثواني).
  4. الـ EF Core: سيبه في الـ read side مباشرة (queries)، واعمل port بس للـ writes المهمة لو الـ aggregates معقدة.
  5. كل خطوة PR صغير، والسلوك ثابت (characterization tests من Clean Code).
08

أخطاء شائعة

Common mistakes
Basics
  • Port لكل class («IOrderMapper»، «IStringHelper») — الـ ports للحدود مع العالم الخارجي بس.
  • Ports بلغة التكنولوجيا (ISqlRepository.ExecuteQuery(string sql)) بدل لغة التطبيق (IDocumentSearch.SearchAsync).
  • EF entities أو HttpContext جوه الـ core.
  • Business logic في الـ adapters (الـ endpoint بيقرر «لو مفيش مصادر ارفض»).
  • Fakes بسلوك مختلف عن الحقيقي من غير contract tests.
  • مشروع لكل port: 14 مشروع لـ 3 use cases.
09

اختبر فهمك

Knowledge check
Basics

الـ Service Bus consumer اللي بيستقبل «DocumentUploaded» ويستدعي use case الـ ingestion: ده إيه في Hexagonal؟

مين بيملك interface الـ IAnswerGenerator؟

10

تمارين محلولة

Worked exercises
Practical
1: عايزين نبدّل LLM provider لعميل enterprise بس (Azure OpenAI لعميل، Ollama محلي لعميل تاني)

الحل: الـ port IAnswerGenerator ثابت. اعمل adapter لكل provider، وrouting adapter بينفذ نفس الـ port ويختار حسب إعدادات الـ tenant (decorator/composite). الـ core ما يعرفش أي حاجة. والـ eval suite نفسها بتشتغل على كل adapter قبل التفعيل للعميل.

2: مراجعة كود: الـ handler بينادي HttpClient مباشرة لـ Stripe

الحل: الـ core بقى معتمد على تفاصيل HTTP و Stripe. استخرج port بلغة التطبيق (IBillingGateway.StartCheckoutAsync(planId, tenant))، انقل HttpClient/Stripe.net للـ adapter، واختبر الـ handler بـ fake. وخلي mapping الأخطاء (Stripe error codes ← نتايج التطبيق) في الـ adapter.

11

أسئلة إنترفيو

Interview questions
Basics
(Mid) اشرح Ports & Adapters.
التطبيق في المركز وبيتعامل مع العالم من خلال ports (interfaces بلغة التطبيق): driving ports للي بيطلب من التطبيق، و driven ports للي التطبيق محتاجه. الـ adapters بتربط كل تكنولوجيا بالـ port المناسب، والاعتمادية دايمًا من برّه لجوّه.
(Senior) Clean مقابل Hexagonal مقابل Onion؟
نفس الـ dependency rule. Hexagonal بيركز على الحدود والـ ports، Onion على طبقات الـ domain جوه الـ core، و Clean بيدّي أسماء محددة للحلقات (entities، use cases، adapters). الاختيار في الشغل غالبًا مسألة تنظيم و convention للفريق، والأهم إن الـ core ما يعتمدش على frameworks.
(Senior) إمتى ترفض hexagonal في مشروع؟
لو الـ domain بسيط CRUD، الفريق صغير، والتكنولوجيات مستقرة: الـ ceremony (interfaces، mapping، مشاريع) بتكلف أكتر من الفايدة. vertical slices مع ports للـ dependencies المتغيرة بس أبسط وأسرع.
↗

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

References & further reading

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

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

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