الفكرة في جملة: التطبيق في النص، والعالم حواليه adapters
Alistair Cockburn اقترح Hexagonal سنة 2005 عشان يحل مشكلة واحدة: الـ business logic بيتلخبط مع الـ UI والـ database، فما تقدرش تختبره ولا تغيّر التكنولوجيا من غير ما تكسره. الحل: التطبيق (الـ core) بيتكلم مع العالم من خلال ports (interfaces بلغة التطبيق)، وكل تكنولوجيا (HTTP، SQL، queue، LLM) بتتوصل بـ adapter بيترجم بينها وبين الـ port. الشكل السداسي مالوش معنى غير إنه بيدّي «جوانب كتير» للـ ports.
| المصطلح | المعنى | مثال .NET |
|---|---|---|
| Driving (primary) port | إزاي العالم بيطلب من التطبيق يعمل حاجة | IAskQuestion use case interface، أو handler class |
| Driving adapter | بيحوّل input خارجي لنداء على الـ port | Minimal API endpoint، Service Bus consumer، test |
| Driven (secondary) port | اللي التطبيق محتاجه من العالم، بلغته هو | IDocumentStore, IAnswerGenerator, IClock |
| Driven adapter | تنفيذ الـ port بتكنولوجيا معينة | EfDocumentStore, AzureOpenAiAnswerGenerator |
Hexagonal مقابل Onion مقابل Clean: الفرق الحقيقي
| Hexagonal | Onion | Clean | |
|---|---|---|---|
| التركيز | الحدود بين التطبيق والعالم (in/out) | طبقات داخل الـ core (domain model في المركز) | قاعدة الاعتمادية + أدوار محددة (entities، use cases، interface adapters، frameworks) |
| تنظيم الـ core | ما بيفرضش طبقات جوه | domain model ← domain services ← application services | entities ← use cases (interactors) بـ input/output boundaries |
| الـ ports | مفهوم أساسي وصريح | interfaces في الطبقات الداخلية | boundaries/gateways |
| القاعدة المشتركة | الكود الداخلي ما يعرفش أي حاجة عن الخارجي؛ الـ interfaces بيملكها الداخل، والخارج بينفذها (Dependency Inversion) | ||
الخلاصة العملية: لو فاهم الـ dependency rule و DIP، فاهم التلاتة. الفروق في إزاي بتنظم المشاريع والأسماء مش في المبدأ. في الإنترفيو ما تقولش «Hexagonal أحسن من Clean»؛ قول «كلهم بيطبقوا dependency inversion حوالين الـ domain؛ Hexagonal بيركز على الـ ports كحدود، و Clean بيدّي أسماء للطبقات الداخلية».
تطبيق كامل: «اسأل عن مستند» في الـ Capstone
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)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);
}
}// 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 من غير ما تلمسهم.
الاختبار عبر الـ ports
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) | القواعد والـ orchestration | fakes للـ 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 بتكدب عليك. اكتب نفس مجموعة الاختبارات وشغّلها على الاتنين.
إمتى يستاهل؟ وإمتى vertical slices أحسن؟
| الموقف | الأنسب |
|---|---|
| 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) من غير مشروع لكل طبقة.
تصميم الـ ports: لغة التطبيق مش لغة التكنولوجيا
| Port سيء | ليه سيء | Port أحسن |
|---|---|---|
IDbRepository<T>.Query(Expression<Func<T,bool>>) | بيسرّب IQueryable/EF semantics للـ core؛ مش كل expression بيتترجم | IDocumentSearch.SearchAsync(tenant, query, k) |
IOpenAiClient.CreateChatCompletion(OpenAiRequest) | اسم provider و DTOs بتاعته جوه الـ core | IAnswerGenerator.GenerateAsync(question, passages) |
IHttpSender.PostJson(url, body) | تفاصيل transport | IWebhookPublisher.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 وتبقى معتمد على التفاصيل تاني.
Migration تدريجي لمشروع موجود
- ابدأ بالـ dependencies اللي بتوجعك: الـ LLM provider والـ payment gateway والـ email — استخرج port لكل واحد، والـ adapter = الكود الحالي متغلّف.
- انقل الـ business rules من الـ controllers لـ handlers بتعتمد على الـ ports دي بس.
- اكتب tests للـ handlers بـ fakes — دي أول مكسب ملموس (اختبارات في ثواني).
- الـ EF Core: سيبه في الـ read side مباشرة (queries)، واعمل port بس للـ writes المهمة لو الـ aggregates معقدة.
- كل خطوة PR صغير، والسلوك ثابت (characterization tests من Clean Code).
أخطاء شائعة
- 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.
اختبر فهمك
الـ Service Bus consumer اللي بيستقبل «DocumentUploaded» ويستدعي use case الـ ingestion: ده إيه في Hexagonal؟
مين بيملك interface الـ IAnswerGenerator؟
تمارين محلولة
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.
أسئلة إنترفيو
(Mid) اشرح Ports & Adapters.
(Senior) Clean مقابل Hexagonal مقابل Onion؟
(Senior) إمتى ترفض hexagonal في مشروع؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.