الصورة الكبيرة: الـ API بيعمل إيه؟
الـ Web API هو boundary بين client (موبايل، Angular، خدمة تانية) وبين business capabilities عندك. العميل بيبعت HTTP request فيه method و URL و headers وممكن body؛ التطبيق يفسّر الطلب، يطبّق السياسات، ينفّذ المنطق، ويرجع status code و headers و representation غالباً JSON.
Transport contract
HTTP هو الاتفاق على شكل التواصل: method، URI، status، headers، body. لا تخلط بين HTTP وبين business logic.
Application behavior
Endpoint يربط الطلب بحالة استخدام، ثم service/domain يتعامل مع القواعد، و data access يتعامل مع التخزين.
Host responsibilities
Kestrel يستقبل الاتصالات، والـ middleware pipeline يمرر الطلب خلال cross-cutting concerns ثم endpoint execution.
الـ request/response lifecycle لازم يبقى واضح في دماغك: network connection → server accepts request → middleware → endpoint selection/execution → response creation → middleware unwind → network response. الـ response ممكن يبدأ streaming؛ وقتها مش كل body لازم يكون اتجهز في الذاكرة قبل الإرسال.
خريطة ذهنية لدورة ASP.NET Core API
استخدم الخريطة دي عند debugging. لو route لم يتم اختياره، المشكلة Routing. لو body لم يتحول إلى DTO، راجع content type/model binding. لو 400 قبل دخول action، راجع automatic validation. لو user وصل للـ action لكنه غير مسموح، راجع authorization/resource access. لو database بطيئة، راقب persistence spans. لو JSON مختلف عن المتوقع، راجع result execution/serializer settings.
الفصل بين المراحل يمنعك من وضع workaround في المكان الخطأ. مثلاً لا تعالج invalid JSON داخل business service؛ الخدمة لم تستلم DTO صالحاً أصلاً. ولا تجعل controller يقرر SQL retry policy؛ ده concern في infrastructure/dependency boundary. ولا تستخدم CORS لتمنع API access؛ CORS browser policy وليست authorization.
الـ Hosting و Program.cs
في القالب الحديث، WebApplication.CreateBuilder(args) بيجهز Generic Host و Web Host defaults: configuration providers، logging providers، DI container، environment، Kestrel defaults، و content root. بعد كده بتسجل الخدمات، تستدعي Build() لإنشاء التطبيق، وتكوّن middleware/endpoint pipeline، ثم Run() لتشغيله.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
builder.Services.AddProblemDetails();
builder.Services.AddScoped<IInventoryService, InventoryService>();
var app = builder.Build();
if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler();
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseRouting();
app.MapControllers();
app.Run();
// Needed by WebApplicationFactory in some top-level Program test setups.
public partial class Program { }تتبّع التنفيذ
CreateBuilderينشئ builder ويحمّل إعدادات البيئة والـ command line وغيرها.builder.Servicesهو composition root: مكان تسجيل الخدمات قبل بناء provider. تفاصيل resolution والـ lifetimes موجودة في درس Dependency Injection.Buildيبني الـ app والـ service provider ويثبت إعدادات الـ pipeline.- النداءات
Use...تضيف middleware بالترتيب؛MapControllersيضيف controller endpoints. Runيبدأ استقبال الطلبات ويبقى التطبيق شغالاً حتى الإيقاف.
Environment management
الاسم الشائع للبيئات هو Development و Staging و Production، والقيمة تأتي عادة من DOTNET_ENVIRONMENT أو ASPNETCORE_ENVIRONMENT حسب host/configuration precedence. لا تضع secrets في ملفات إعدادات committed. استخدم User Secrets محلياً، و environment variables أو secret manager في النشر. البيئة ليست security boundary: لا تعتمد على اسمها وحده لحماية endpoint.
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"Inventory": {
"LowStockThreshold": 12
}
}الـ configuration providers لها ترتيب أولوية؛ غالباً environment variables والـ command-line values تتغلب على JSON files. لذلك نفس المفتاح قد يأخذ قيمة مختلفة في كل بيئة من غير تغيير الكود.
Request Anatomy و Kestrel والـ Reverse Proxy
الـ HTTP request عند وصوله للتطبيق لا يكون مجرد URL. Kestrel يقرأ HTTP framing، يكوّن HttpContext ويملأ Request properties مثل Method و Scheme و Host و Path و Query و Headers و Body. الـ Body stream قد يكون غير seekable، لذلك buffering أو القراءة المتكررة لها تكلفة وحدود. خلف reverse proxy مثل IIS/nginx/ingress، الاتصال الخارجي قد ينتهي عند proxy ثم proxy يتصل بـ Kestrel داخلياً؛ لذلك scheme/remote IP الأصليين قد يحتاجان Forwarded Headers Middleware من proxy موثوق.
app.MapGet("/diagnostics/request", (HttpContext context) => new
{
context.Request.Method,
Path = context.Request.Path.Value,
Query = context.Request.QueryString.Value,
Scheme = context.Request.Scheme,
Host = context.Request.Host.Value,
Protocol = context.Request.Protocol,
IsHttps = context.Request.IsHttps
});لا تترك diagnostics endpoint مفتوحاً في production؛ هذه معلومات للتوضيح. لا تثق في X-Forwarded-For أو X-Forwarded-Proto من أي client عشوائي. اضبط KnownProxies/KnownNetworks وفعّل middleware قبل أي component يعتمد على scheme/IP. وإلا يمكن للمهاجم spoofing للـ client IP أو تجاوز rate limiting/security rules.
من أول byte لحد Action Result: دورة الطلب بالتفصيل
افصل بين أربع مراحل عشان ما تخلطش مسؤوليات ASP.NET Core: transport، hosting، middleware/endpoint routing، وapplication execution. المتصفح أو الموبايل يفتح connection ويبعث HTTP bytes. Kestrel يقرأ البروتوكول ويحوّل الاتصال إلى request abstractions. الـ host يمرر HttpContext للـ pipeline. Routing يختار endpoint ويملى metadata. بعد كده authorization و filters/model binding/validation حسب نوع endpoint. الـ action أو handler ينفذ، ثم result executor/HTTP result يحوّل النتيجة إلى status و headers و body. أخيراً response يرجع خلال middleware التي تنتظر next.
الـ HttpContext يمثل request واحد: Request، Response، User، Items، TraceIdentifier، و RequestServices. لا تخزن HttpContext في field داخل singleton أو تحتفظ به بعد انتهاء request؛ عمره مرتبط بالطلب. لو محتاج تنقل معلومة بين middleware و endpoint في نفس الطلب استخدم HttpContext.Items بحذر، ولو محتاج correlation/tracing استخدم Activity/diagnostics.
الترتيب الدقيق يختلف بين Controller actions و Minimal API handlers. في MVC مثلاً model binding و validation و action filters جزء من MVC action invocation، بينما Minimal APIs لها parameter binding و endpoint filters. لذلك لا تحفظ pipeline كأنها قائمة واحدة لكل أنواع endpoints؛ افهم أي subsystem مسؤول عن كل مرحلة.
Action result مش هو نفس HTTP response
لما ترجع Ok(dto) أنت بترجع object يعبّر عن النتيجة. MVC result executor هو اللي يحدد status code ويعمل content negotiation/serialization ويكتب body. أما return dto في بعض الأنماط فله semantics مختلفة. استخدم response types واضحة عشان تقدر توثق success و failure contracts وتختبرها.
[HttpGet("{id:int}")]
[ProducesResponseType<ProductResponse>(StatusCodes.Status200OK)]
[ProducesResponseType<ProblemDetails>(StatusCodes.Status404NotFound)]
public async Task<ActionResult<ProductResponse>> GetById(
int id, CancellationToken cancellationToken)
{
var product = await service.FindAsync(id, cancellationToken);
if (product is null)
return NotFound();
return Ok(product);
}اختبر الـ endpoint من HTTP boundary، مش بس باختبار service. اختبار service يثبت business behavior، لكنه لا يثبت route matching أو JSON serialization أو status code أو middleware. تفاصيل integration testing موجودة في جزء Web API الثاني.
HttpContext و Request Scope و Thread Safety
HttpContext مش object عام للتطبيق كله؛ هو state مرتبط بطلب HTTP واحد. تقدر تقرأ منه Request/Response/User/TraceIdentifier/RequestAborted، لكن لا تحتفظ به في singleton ولا تمرره إلى background job بعد انتهاء request. لو محتاج user ID أو tenant ID في background job، انسخ القيمة الضرورية إلى job payload قبل ما تنهي request، ولا تنقل HttpContext نفسه.
ASP.NET Core request processing async، فلا تفترض إن نفس request سيظل على نفس thread طوال عمره. لا تستخدم ThreadLocal لتخزين request data. استخدم DI scope أو HttpContext.Items أو logging scope أو Activity context حسب طبيعة البيانات. IHttpContextAccessor متاح عند الضرورة لكنه يعتمد على AsyncLocal وله تكلفة؛ الأفضل تمرير البيانات المطلوبة صراحةً إلى application service بدل جعل كل service تقرأ HttpContext مباشرة.
[Authorize]
[HttpPost("orders")]
public async Task<ActionResult<OrderResponse>> Create(
CreateOrderRequest request, CancellationToken token)
{
var userId = User.FindFirstValue(ClaimTypes.NameIdentifier);
if (string.IsNullOrWhiteSpace(userId))
return Unauthorized();
var result = await orderService.CreateAsync(
userId, request, token);
return CreatedAtAction(nameof(Get), new { id = result.Id }, result);
}ده يخلي application service تستقبل user ID كبيانات صريحة، ويمكن اختبارها من غير fake HttpContext. لكن مجرد وجود user ID لا يثبت أن المستخدم يملك كل resource؛ service/domain authorization يجب أن يتحقق من ownership والسياسات المطلوبة.
Request Diagnostics و Trace Context
في production، request واحد ممكن يمر عبر mobile client ثم API gateway ثم ASP.NET Core ثم database وخدمة خارجية. استخدم W3C Trace Context (traceparent) و OpenTelemetry instrumentation لربط spans. TraceIdentifier الخاص بـ ASP.NET Core مفيد داخل host، لكنه ليس بديلاً كاملاً عن distributed trace propagation. لا تخلط TraceId مع CorrelationId أو UserId؛ كل واحد له purpose مختلف.
في logs، استخدم structured properties مثل route template و status code و duration و trace ID. تجنب raw URL كـ metric label أو query string في logs إذا قد تحتوي PII. فعّل sampling للترايسز وفق volume/cost، لكن حافظ على error traces أو tail-based sampling عند الحاجة. لا تجعل observability نفسها سبباً في overload.
Routing واختيار الـ Endpoint
Routing مش مجرد استخراج ID من URL. الـ endpoint routing بيحدد أي endpoint ينطبق على method والمسار والقيود والـ metadata، ثم middleware يقدر يقرأ الـ selected endpoint ويطبق authorization أو rate limiting أو غيرهم. الترتيب التفصيلي للـ middleware في درس Middleware.
[ApiController]
[Route("api/products")]
public sealed class ProductsController : ControllerBase
{
[HttpGet("{id:int}")]
public ActionResult<ProductResponse> GetById(int id)
=> Ok(new ProductResponse(id, "Keyboard"));
[HttpGet]
public ActionResult<IReadOnlyList<ProductResponse>> Search([FromQuery] string? q)
=> Ok(Array.Empty<ProductResponse>());
}
public sealed record ProductResponse(int Id, string Name);[Route] على مستوى controller يحدد prefix. الـ attribute [HttpGet] و [HttpPost] يحددان HTTP verb، و template مثل {id:int} يضيف route constraint. الـ constraint يساعد في اختيار route، لكنه ليس validation تجاري بديل؛ ما زلت تتحقق إن المنتج موجود وإن المستخدم مسموح له الوصول.
404 Not Found معناها لم يتم العثور على route/resource مناسب وفق السياق. 405 Method Not Allowed معناها المسار معروف لكن HTTP method غير مدعوم لذلك المورد، وقد يصدر معه Allow header.
Filters vs Middleware vs Endpoint Filters
| Mechanism | Scope | Best fit |
|---|---|---|
| Middleware | Whole HTTP pipeline | Exception boundary, request correlation, security headers |
| MVC filters | MVC action/result pipeline | Controller/action-specific behavior |
| Endpoint filters | Minimal API endpoint invocation | Shared handler argument/result behavior |
| Authorization policies | Endpoint/resource access decision | Who may perform an operation |
اختار extension point بناءً على المعلومات التي تحتاجها. لو محتاج كل request حتى static files و non-MVC endpoints، استخدم middleware. لو محتاج action arguments أو MVC result، استخدم MVC filter. لو endpoint Minimal API فقط، endpoint filter قد تكون أوضح. لو المشكلة permission، لا تكتب filter يدوياً قبل ما تدرس policy authorization.
Controllers و Action Methods
Controller هو adapter عند حد HTTP، مش المكان المناسب لكل business rules. يرث API controller عادة من ControllerBase، ويحوّل HTTP input إلى استدعاء application service ثم يحوّل النتيجة إلى HTTP response. استخدام Controller يضيف دعم Views؛ أما API فقط فـ ControllerBase أنسب.
[ApiController]
[Route("api/products")]
public sealed class ProductsController(IProductQuery query) : ControllerBase
{
[HttpGet("{id:int}")]
[ProducesResponseType<ProductResponse>(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<ProductResponse>> Get(
int id, CancellationToken cancellationToken)
{
var product = await query.FindAsync(id, cancellationToken);
return product is null ? NotFound() : Ok(product);
}
}
public interface IProductQuery
{
Task<ProductResponse?> FindAsync(int id, CancellationToken cancellationToken);
}
public sealed record ProductResponse(int Id, string Name, decimal Price);ليه الكود متقسم كده؟
- الـ route template يعرّف عنوان المورد.
- الـ controller يستقبل
CancellationTokenالمرتبط بالـ request؛ لو العميل قطع الاتصال أو الطلب اتلغى، يقدر العمل التابع يوقف بدوره. - الـ query service تحمل مسؤولية استرجاع البيانات؛ controller لا يعرف EF Core ولا SQL.
ActionResult<T>يعبّر إن النتيجة قد تكون payload من النوع T أو HTTP result زي 404.- Attributes الخاصة بـ response types توثّق contract للـ OpenAPI tooling، لكنها لا تضمن وحدها إن implementation يرجع الحالة فعلاً.
Controller Conventions و ApiController Behavior
[ApiController] يجمع مجموعة conventions مفيدة: attribute routing requirement، inference لمصادر binding في حالات كثيرة، automatic 400 عند invalid ModelState، و Problem Details style errors لبعض الحالات. هذه defaults تقلل boilerplate لكنها لا تلغي فهم binding. Input/output formatters تتعامل مع media types؛ JSON formatter يحوّل DTO إلى JSON والعكس. استخدم [Consumes] و [Produces] عندما تحتاج توضيح supported content types، وليس لمجرد تزيين الكود.
اختَر return shape حسب contract: IActionResult مرن، ActionResult<T> يجمع payload مع HTTP alternatives، و typed result metadata يمكن أن يزيد وضوح OpenAPI. لا ترجع 200 لكل الحالات مع body يحتوي { success:false }؛ status code جزء من protocol ويساعد proxies/clients/monitoring.
تصميم Controller قابل للصيانة
Controller الجيد غالباً يعمل أربع حاجات: يقرأ HTTP input، يطلب use case من application service، يترجم النتيجة إلى HTTP response، ويضيف metadata اللازمة للوثيقة. لو لقيت controller بيحسب خصومات، ويقرر inventory، ويعمل transaction، ويكتب SQL، ويبعث email، فهو بقى مكان business orchestration كله. انقل السلوك إلى service/use-case، وسيب controller boundary adapter.
لا تحوّل كل action إلى method generic واحدة لكل CRUD لمجرد تقليل الأسطر. أسماء العمليات الواضحة مثل ApproveOrder و CancelOrder تعكس business intent أحسن من UpdateStatus إذا كانت القواعد مختلفة. كذلك response DTO ينبغي أن يعبّر عن contract، لا عن كل أعمدة الجدول.
اسأل نفسك عند مراجعة كل action: هل أقدر أفهم HTTP contract من signature والـ attributes؟ هل business rule موجودة في المكان المسؤول عنها؟ هل status codes تمثل الحالات المتوقعة؟ هل cancellation وصل للـ I/O؟
Action Return Types و Cancellation
في controller API عندك خيارات مثل IActionResult و ActionResult<T> و specific typed results. ActionResult<T> مفيد لما success يرجع DTO لكن failure يرجع NotFound/BadRequest. IActionResult مرن لكنه أقل وضوحاً في success schema. لا ترجع entity مباشرة. مرر CancellationToken إلى كل I/O operation؛ العميل قد يغلق الاتصال، ولا معنى لإكمال query مكلفة بعد إلغاء الطلب لو العملية يمكن إيقافها بأمان.
[HttpGet("{id:int}")]
public async Task<ActionResult<ProductResponse>> Get(
int id, CancellationToken cancellationToken)
{
var result = await query.FindAsync(id, cancellationToken);
return result is null ? NotFound() : Ok(result);
}
public Task<Product?> FindAsync(int id, CancellationToken token)
=> db.Products.AsNoTracking()
.SingleOrDefaultAsync(p => p.Id == id, token);لا تبتلع OperationCanceledException كأنها server failure عادية. وفي background work لا تستخدم RequestAborted كـ lifetime للعمل بعد انتهاء request؛ لو العملية يجب أن تكمل بعد response، انقلها إلى durable job/queue.
Controller Conventions و API Behavior
[ApiController] يفعّل behaviors مهمة مثل automatic 400 عند ModelState invalid، binding source inference، و Problem Details-style client errors حسب إعدادات التطبيق. [Route] يحدد base template، و [HttpGet]/[HttpPost] يحددان verb/template، و [ProducesResponseType] يضيف metadata للـ OpenAPI. دي attributes تصف HTTP contract؛ لا تعتبرها business validation أو authorization في حد ذاتها.
استخدم ActionResult<T> لما success type معروف ومعه عدة HTTP outcomes. IActionResult مناسب لما النتائج متنوعة أو لا يوجد success payload. Task<T> يوضح async execution، و CancellationToken يربط العملية بعمر الطلب. تجنب async void تماماً في actions لأنه يمنع framework من انتظار completion ومعالجة exceptions بشكل صحيح.
Route constraint مثل {id:guid} يمنع string غير صالح من مطابقة route، لكن validation للـ business rules يظل منفصلاً. لو endpoint لا يجد resource بعد binding صحيح، 404 أنسب من 400. ولو caller غير مسموح له، 403 أو 404 حسب disclosure policy.
اختيار Return Type و Testing للـ Controller
Controller action return type يؤثر على وضوح العقد والـ OpenAPI. ActionResult<T> مناسب لما عندك success DTO معروف ومعه نتائج مثل NotFound أو Conflict. IActionResult مرن لكنه لا يوضح schema للنجاح بنفس القوة. لو ترجع DTO مباشرة، framework قد يعمل ObjectResult وفق conventions. خليك consistent داخل API، ووثّق failure responses باستخدام ProducesResponseType أو OpenAPI metadata.
في integration test، استخدم HttpClient من WebApplicationFactory وأرسل HTTP request حقيقي. اختبر route template، method، binding، serialization، status code، content type، headers، authorization، و Problem Details. Unit test للـ controller وحده غالباً لا يختبر framework pipeline؛ في ASP.NET Core الأفضل اختبار service كـ unit واختبار endpoint عبر integration.
[Fact]
public async Task Get_missing_product_returns_404()
{
using var client = factory.CreateClient();
using var response = await client.GetAsync("/api/products/404404");
Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
Assert.Equal("application/problem+json",
response.Content.Headers.ContentType?.MediaType);
}لو عندك multiple environments، الاختبار لازم يضبط test configuration بوضوح. لا تعتمد على Development-only exception page كأنها production behavior. استخدم test database أو fake service وفق ما تريد اختباره.
مراجعة API Endpoint قبل الـ Merge
اعمل review من منظور client وليس من منظور C# class فقط. هل URL يمثل resource واضح؟ هل method صحيح؟ هل route/query/body/header binding واضح؟ هل request DTO يسمح فقط بالحقول المقصودة؟ هل validation ترجع error contract متوقع؟ هل authentication وال authorization متطبقان؟ هل response status و schema و headers واضحة؟ هل cancellation وصل إلى I/O؟ هل logs مفيدة ولا تحتوي secrets؟ هل integration test يغطي success و failure؟
مثال: endpoint لإنشاء منتج لا ينبغي أن يقبل CreatedByUserId أو IsApproved من العميل. الخادم يستخرج user identity من authenticated principal، ويقرر approval وفق business rules. response 201 تحتوي Location إلى resource الجديدة و DTO public. لو الاسم مكرر، يرجع conflict Problem Details. لو JSON malformed، يرجع 400. لو المستخدم anonymous، يرجع 401 قبل business operation.
هذا النوع من review يكشف أن API ليست مجرد Controller + EF query؛ هي contract، security boundary، operational component، وواجهة versioned بين أنظمة قد تتحدث في أوقات مختلفة.
Model Binding: البيانات جاية منين؟
Model binding يقرأ HTTP request ويحاول تكوين parameters أو DTOs من route، query string، headers، form fields، أو request body. في Controller APIs مع [ApiController]، framework يقدر يستنتج binding source من نوع parameter واسم route، لكن الأفضل التصريح بـ [FromRoute] و [FromQuery] و [FromBody] في العقود المهمة لتقليل الالتباس.
[HttpGet("{id:int}")]
public IActionResult Get(
[FromRoute] int id,
[FromQuery] bool includeInactive = false,
[FromHeader(Name = "X-Client-Version")] string? clientVersion = null)
=> Ok(new { id, includeInactive, clientVersion });
[HttpPost]
public IActionResult Create([FromBody] CreateProductRequest request)
=> CreatedAtAction(nameof(Get), new { id = 42 }, new { id = 42 });
public sealed record CreateProductRequest(string Name, decimal Price);قاعدة مهمة: HTTP request body غالباً يُقرأ مرة واحدة، لذلك لا تصمم action فيها أكثر من complex parameter يتنافس على نفس body. استخدم DTO واحداً واضحاً. ملفات الرفع تستخدم IFormFile و multipart/form-data، وسنفصل قواعدها في جزء Web API الثاني.
Binding و validation مرحلتان مختلفتان: binding يحاول تحويل القيمة (مثل النص "abc") إلى int؛ validation يختبر هل القيمة الناتجة مقبولة (مثل Price أكبر من صفر). [ApiController] يعيد 400 تلقائياً عند ModelState invalid في السيناريو المعتاد، قبل دخول action.
Model Binding: كل قيمة جت منين؟
Model binding هو تحويل HTTP representation إلى .NET parameters/objects. مصادر شائعة: route values، query string، headers، form fields، request body، و DI services. اختيار المصدر جزء من contract؛ لو endpoint يستقبل id من route و page من query، صرّح ده عندما يكون inference غير واضح أو لما تقرأ signature وتحتاج تفهمها فوراً.
| Attribute | Source | Example |
|---|---|---|
[FromRoute] | Route template | /products/42 |
[FromQuery] | Query string | ?page=2 |
[FromHeader] | HTTP header | X-Tenant |
[FromBody] | Serialized body | JSON document |
[FromForm] | Form/multipart fields | Upload metadata |
[FromServices] | DI container | Application service |
[HttpGet("{id:int}")]
public Task<ActionResult<ProductResponse>> Search(
[FromRoute] int id,
[FromQuery] string? term,
[FromHeader(Name = "X-Client-Version")] string? clientVersion,
[FromServices] IProductQuery query,
CancellationToken cancellationToken)
{
return SearchCore(id, term, clientVersion, query, cancellationToken);
}ما ينفعش تقرأ نفس request body كذا مرة من غير buffering مقصود؛ body stream غالباً forward-only. خلي عندك DTO واحد للـ JSON body، وتجنب قبول entity كاملة. الـ binding يثبت إن القيمة قابلة للتحويل لنوع .NET، لكنه لا يثبت إنها business-valid: الرقم 42 قابل للتحويل لـ int حتى لو المنتج غير موجود.
Validation مش authorization
Validation تسأل: هل input صحيح؟ Authorization تسأل: هل هذا المستخدم مسموح له يعمل العملية على هذا المورد؟ وجود CustomerId صحيح شكلياً لا يعني إن العميل الحالي يملك هذا الـ customer. لازم تربط قرار الوصول بهوية المستخدم و resource ownership، مش بمجرد صحة القيمة القادمة من العميل.
Binding ثم Validation ثم Action: مثال تتبّع كامل
تخيل request إلى POST /api/products?notify=true والـ JSON body يحتوي name و price. Routing يختار action المطابقة للـ POST. Model binding يقرأ query parameter notify ويحوّل النص true إلى bool، ويقرأ JSON body إلى CreateProductRequest. Validation تفحص Required/Range/Length وتملأ ModelState. مع ApiController، invalid ModelState يؤدي إلى 400 قبل دخول action غالباً. لو valid، action تستدعي application service، ثم result executor يحول DTO إلى JSON ويحدد status.
لو body JSON malformed، فشل parsing يحدث قبل business logic. لو price = -5 قابل للتحويل إلى decimal لكنه غير valid، validation ترفضه. لو price = 100 valid شكلياً لكن user لا يملك permission لإنشاء product في tenant، authorization/business rule ترفضه. التمييز بين parsing و validation و business rule و authorization يجعل status codes والتصميم أوضح.
public sealed record CreateProductRequest(
[property: Required, StringLength(120, MinimumLength = 2)] string Name,
[property: Range(typeof(decimal), "0.01", "999999.99")] decimal Price,
[property: Required, StringLength(3, MinimumLength = 3)] string Currency);Attributes تتحقق من input shape، لكن لا تضع فيها كل business logic. الـ validator يمكنه التحقق من currency allow-list، والـ domain يضمن invariants، والـ database تضمن foreign keys/unique constraints تحت concurrency.
Response Serialization و Content-Type
بعد action result، framework يختار formatter/serializer ويكتب response. JSON options تؤثر على property naming، enums، nulls، dates، converters، reference handling. API clients تعتمد على هذه التفاصيل حتى لو لم تكتبها في controller. تجنب global serialization changes من غير contract review، ولا تستخدم polymorphic serialization على public DTOs إلا لو discriminator schema موثق ومختبر.
HTTP status code يحدد outcome، و Content-Type يحدد representation، و headers مثل Location/ETag/Cache-Control تضيف semantics. POST create غالباً 201 Created مع Location إلى resource الجديدة؛ PUT قد يرجع 200 مع representation أو 204 بلا body؛ DELETE قد يرجع 204 عند نجاح الحذف. اختار contract واحداً متسقاً ووثّقه.
Configuration و Options Pattern
اقرأ الإعدادات مرة عبر typed options بدل تكرار string keys في كل service. IOptions<T> مناسب للإعداد الثابت بعد بدء التطبيق، و IOptionsSnapshot<T> scoped ويعيد snapshot لكل request، و IOptionsMonitor<T> يدعم مراقبة التغييرات في المصادر التي تدعم reload. لا تفترض أن كل provider قابل لإعادة التحميل.
public sealed class InventoryOptions
{
public const string SectionName = "Inventory";
public int LowStockThreshold { get; init; } = 5;
}
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOptions<InventoryOptions>()
.BindConfiguration(InventoryOptions.SectionName)
.Validate(o => o.LowStockThreshold >= 0, "Threshold cannot be negative.")
.ValidateOnStart();
public sealed class StockAlertService(IOptions<InventoryOptions> options)
{
public bool IsLow(int quantity) => quantity <= options.Value.LowStockThreshold;
}ValidateOnStart() يمنع تشغيل التطبيق بإعدادات غير صالحة بدلاً من اكتشاف المشكلة عند أول request. في التطبيقات ذات الخيارات المعقدة استخدم IValidateOptions<T> أو validation متخصصة، ولا تخزن secrets داخل object قد يظهر في logs.
Configuration و Options Pattern من غير قيم عشوائية
ASP.NET Core يجمع configuration من providers. في القالب المعتاد JSON files ثم environment variables ثم command-line، والأولوية النهائية تتحدد بترتيب providers المضافة. لذلك لا تفترض أن appsettings.json هي القيمة النهائية. استخدم strongly typed options بدل قراءة strings في أماكن كثيرة، وطبّق validation عند startup حتى يفشل التطبيق مبكراً لو configuration ناقصة.
public sealed class PaymentOptions
{
public const string SectionName = "Payment";
public string BaseUrl { get; init; } = "";
public int TimeoutSeconds { get; init; }
}
builder.Services
.AddOptions<PaymentOptions>()
.BindConfiguration(PaymentOptions.SectionName)
.Validate(o => Uri.TryCreate(o.BaseUrl, UriKind.Absolute, out _),
"Payment:BaseUrl must be an absolute URI.")
.Validate(o => o.TimeoutSeconds is >= 1 and <= 60,
"TimeoutSeconds must be between 1 and 60.")
.ValidateOnStart();الـ Options validation تمنع التطبيق من استقبال traffic بإعدادات غير صالحة. لكن لا تضع API keys أو passwords في appsettings committed. استخدم User Secrets في development و secret store أو environment injection في production، وامنع طباعة configuration كاملة في logs.
Environment و Secrets و Options Validation
Environment name يغيّر configuration file والـ developer exception behavior، لكنه ليس security control. أي user قد يزور endpoint لو لم تضف authorization. Secrets لا تحفظها في repository. User Secrets local development convenience وليست encrypted production vault؛ في production استخدم managed secret store أو deployment secret injection. لا تطبع configuration objects كاملة في log لأن فيها احتمال secrets.
Options validation عند startup أفضل من اكتشاف config error عند أول payment request. تحقق من absolute URLs، timeout range، required credentials presence، allowed hostnames، و connection string format. لا تتحقق من secret value نفسها في log أو exception message.
Configuration Providers و Secrets
Configuration abstraction تسمح للكود يقرأ قيمة واحدة بغض النظر عن مصدرها. مصادر شائعة: appsettings.json، appsettings.{Environment}.json، User Secrets في development، environment variables، command-line، و external secret/config providers. ترتيب إضافة providers يحدد precedence؛ القيمة التي تأتي لاحقاً غالباً تتغلب على السابقة. في environment variables تستخدم double underscore لتمثيل hierarchy مثل Payment__TimeoutSeconds.
خلي configuration strongly typed عبر Options، وفرق بين IOptions و IOptionsSnapshot و IOptionsMonitor وفق lifetime/update needs. IOptions قيمة مناسبة غالباً للثابتة، Snapshot scoped، Monitor singleton-friendly ويدعم change notifications لبعض providers. لا تستخدم Monitor لتدوير secret تلقائياً إلا لو provider/consumer مصممين لذلك. والأهم: لا تضع secrets في Git أو logs أو screenshots.
Logging: سجّل أحداثاً قابلة للتحليل
الـ logging الاحترافي مش تجميع strings. استخدم message templates ثابتة وحقول منفصلة حتى تقدر تعمل query حسب ProductId أو Outcome. مستويات شائعة: Trace/Debug للتشخيص، Information للأحداث الطبيعية المهمة، Warning لحدث غير متوقع لكنه متعافى منه، Error لفشل عملية، Critical لفشل خطير يحتاج تدخل.
public sealed class InventoryService(ILogger<InventoryService> logger)
{
public void Reserve(int productId, int quantity)
{
using var scope = logger.BeginScope(new Dictionary<string, object>
{
["ProductId"] = productId
});
logger.LogInformation("Reserving {Quantity} units", quantity);
if (quantity <= 0)
{
logger.LogWarning("Rejected invalid reservation quantity {Quantity}", quantity);
throw new ArgumentOutOfRangeException(nameof(quantity));
}
}
}لا تسجل passwords أو bearer tokens أو raw payment details أو request bodies الحساسة. استخدم correlation/trace identifiers لربط logs بالـ trace؛ تفاصيل OpenTelemetry والتنسيق المتقدم داخل part 2 ودرس Observability لاحقاً.
Logging: إزاي تفهم اللي حصل في Request؟
Logging في backend مش مجرد Console.WriteLine. الهدف إنك تقدر تجاوب: مين عمل request؟ على أي endpoint؟ انتهت بإيه؟ استغرقت قد إيه؟ ولو فشلت، إيه exception type والـ dependency اللي فشلت؟ استخدم structured logging بحيث القيم تبقى properties مستقلة، مش string واحدة صعب تبحث فيها.
public sealed class ProductService(
IProductRepository repository,
ILogger<ProductService> logger)
{
public async Task<Product?> FindAsync(int id, CancellationToken token)
{
logger.LogDebug("Looking up product {ProductId}", id);
var product = await repository.FindAsync(id, token);
if (product is null)
logger.LogInformation("Product {ProductId} was not found", id);
else
logger.LogDebug("Product {ProductId} loaded", id);
return product;
}
}الـ placeholder {ProductId} property name، والقيمة تتخزن كـ structured field عند provider يدعم ذلك. تجنب interpolation مثل $"Product {id}" في logging hot paths لأنه يبني string حتى لو log level disabled، ويصعّب تحليل fields. اختار log level: Trace/Debug للتفاصيل، Information للأحداث التشغيلية المهمة، Warning لحالة غير متوقعة لكن التطبيق تعامل معها، Error لفشل عملية، Critical لفشل خطير على النظام.
لا تسجل passwords، bearer tokens، cookies، connection strings، payment card data، أو request body كاملة بشكل افتراضي. الـ correlation/trace ID يربط logs بطلب واحد؛ distributed trace يربط spans عبر services. لا تعتبر correlation ID دليلاً على هوية العميل.
ملخص واختبار الفهم
- ASP.NET Core يهيئ Host و DI و Configuration و Logging قبل استقبال الطلبات.
- الـ middleware pipeline يحيط باختيار وتنفيذ endpoint.
- Controller هو HTTP adapter؛ لا تضع داخله كل business logic.
- Model binding يحوّل مصادر HTTP إلى parameters؛ validation تختبر صحة المدخلات.
- Options و structured logging يخليان configuration والرصد أكثر انضباطاً.
طلب GET /api/products/12 وصل إلى Controller، لكن قاعدة البيانات لا تحتوي المنتج. ما status الأنسب؟
لماذا نمرر CancellationToken من action إلى service؟
هل [ApiController] يغني عن business validation؟
أين تضع secret API key؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
خريطة التغطية: 10 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.