DTOs و Mapping: حدود واضحة للـ API
الـ Entity بتعبّر عن persistence/domain needs؛ الـ DTO بتعبّر عن contract خارجي. لو رجّعت EF entity مباشرة، ممكن تكشف حقول داخلية، تدخل في serialization cycles، تربط API schema بتصميم قاعدة البيانات، أو تسمح over-posting عند استقبال body. خلي request DTO منفصل عن response DTO، وحدد الحقول المسموح للعميل يرسلها.
public sealed record CreateProductRequest(string Name, decimal Price);
public sealed record ProductResponse(int Id, string Name, decimal Price);
public sealed class Product
{
public int Id { get; private set; }
public string Name { get; private set; } = "";
public decimal Price { get; private set; }
public bool IsDeleted { get; private set; }
public Product(string name, decimal price)
{
Name = name;
Price = price;
}
}
static ProductResponse ToResponse(Product p)
=> new(p.Id, p.Name, p.Price);الـ mapping اليدوي واضح و compile-time safe ومناسب لما التحويلات قليلة. Mapperly يولد mapping code وقت compilation، و AutoMapper مفيد في mapping واسع لكنه يضيف convention/configuration layer ويحتاج اختبارات للتحويلات الحساسة. لا تختَر mapper لمجرد تقليل عدد الأسطر.
API Versioning و Backward Compatibility
Mobile clients لا يتم تحديثها كلها في نفس اليوم؛ ممكن نسخة قديمة تظل موجودة عند مستخدمين شهور. لذلك backward compatibility مهمة. إضافة optional response field غالباً additive، لكن تغيير معنى field أو حذفها أو تغيير type أو جعل optional input required breaking. إضافة enum value قد تكسر clients التي تستخدم exhaustive switch. اختبر client behavior قبل release.
Versioning strategy لازم تتضمن deprecation window، migration guide، telemetry لمعرفة استخدام versions، و sunset date. لا تدعم versions للأبد من غير تكلفة واضحة، ولا تكسر clients فجأة لأن backend deployed. API versioning package قد تساعد في routing/documentation، لكنها لا تصمم compatibility policy نيابة عنك.
الـ production concerns حوالين الـ endpoint
Exception Handling و Problem Details
الـ exception غير المتوقعة لا يجب أن تتحول تلقائياً إلى 500 مع تفاصيل stack trace للعميل. استخدم global exception handler، سجّل exception داخلياً بالـ trace identifier، وأرسل Problem Details (RFC 9457) برسالة عامة وحقول مثل type و title و status و instance. أخطاء validation قد تكون 400، resource missing 404، conflict 409، و unexpected failure 500.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddProblemDetails();
builder.Services.AddExceptionHandler<GlobalExceptionHandler>();
var app = builder.Build();
app.UseExceptionHandler();
public sealed class GlobalExceptionHandler(
ILogger<GlobalExceptionHandler> logger) : IExceptionHandler
{
public async ValueTask<bool> TryHandleAsync(
HttpContext context, Exception exception, CancellationToken token)
{
logger.LogError(exception, "Unhandled request failure {TraceId}",
context.TraceIdentifier);
context.Response.StatusCode = StatusCodes.Status500InternalServerError;
await context.Response.WriteAsJsonAsync(new ProblemDetails
{
Status = 500,
Title = "An unexpected error occurred.",
Type = "https://httpstatuses.com/500",
Extensions = { ["traceId"] = context.TraceIdentifier }
}, token);
return true;
}
}لا تمسك كل exception وترجع 200 أو 400. ولا تسجل نفس exception في كل layer فينتج duplicate noisy logs. استخدم domain/application error types للأخطاء المتوقعة، والاستثناءات للأحداث الاستثنائية فعلاً. Result pattern قد يكون أوضح في flows التي تحتوي failure متوقعاً ومتعدد الأنواع؛ لكن لا تحوّل كل method إلى 12 حالة معقدة بلا داعٍ.
Problem Details: شكل موحّد للأخطاء
Problem Details في RFC 9457 بيوحّد شكل error response عشان client ما يضطرش يتعامل مع JSON مختلف لكل endpoint. الحقول القياسية تشمل type و title و status و detail و instance، وتقدر تضيف extension members مثل code أو errors. لا تجعل detail يحمل stack trace أو SQL error في production.
{
"type": "https://api.example.com/problems/validation",
"title": "One or more validation errors occurred.",
"status": 400,
"instance": "/api/products",
"code": "request.validation_failed",
"errors": {
"price": ["Price must be greater than zero."],
"name": ["Name is required."]
},
"traceId": "00-..."
}الـ type يعرّف فئة المشكلة بشكل ثابت؛ title عنوان قصير؛ detail شرح safe؛ و instance يحدد occurrence. خليك ثابت في error codes لأن clients ممكن تعتمد عليها، لكن لا تجعل client يفسر نص الرسالة البشرية كأنه machine protocol.
builder.Services.AddProblemDetails(options =>
{
options.CustomizeProblemDetails = context =>
{
context.ProblemDetails.Extensions["traceId"] =
context.HttpContext.TraceIdentifier;
};
});
var app = builder.Build();
app.UseExceptionHandler();
app.UseStatusCodePages();تأكد أن exception handler مسجل وموجود مبكراً في pipeline، وأن developer exception page لا تظهر في production. اختبر status code والـ content type والحقول، مش مجرد إن response body غير فارغ.
Result Pattern مقابل Exceptions
لو عملية business ممكن تفشل بشكل متوقع مثل ProductNotFound أو InsufficientStock أو DuplicateEmail، عندك اختيار: Result type أو exception domain-specific. الـ Result مفيد لما الفشل branch طبيعي ومتكرر ويتوقعه caller؛ الـ exception أنسب لفشل غير متوقع أو حالة استثنائية لا ينبغي أن تكون flow control يومي. لا يوجد قانون أن كل exceptions غلط أو أن كل method لازم ترجع Result.
public sealed record Error(string Code, string Message);
public sealed record Result<T>(T? Value, Error? Error)
{
public bool IsSuccess => Error is null;
public static Result<T> Success(T value) => new(value, null);
public static Result<T> Failure(string code, string message)
=> new(default, new Error(code, message));
}
public async Task<Result<ProductResponse>> FindProductAsync(
int id, CancellationToken token)
{
var product = await repository.FindAsync(id, token);
return product is null
? Result<ProductResponse>.Failure("product.not_found", "Product was not found.")
: Result<ProductResponse>.Success(Map(product));
}في boundary حوّل Result إلى HTTP status/Problem Details. حافظ على mapping مركزي حتى لا endpoint يرجع 404 وآخر 400 لنفس error. لو بتستخدم library أو union type، افهم nullability والـ exhaustive matching وسلوك serialization بدلاً من تقليد شكل Result من غير invariant واضح.
Filters ومكان كل Cross-Cutting Concern
Filters تعمل داخل MVC action invocation pipeline، بعد اختيار endpoint وقبل/بعد مراحل controller/action حسب النوع. Resource filters تحيط بمعظم MVC pipeline، Action filters تحيط باستدعاء action، Exception filters تتعامل مع بعض exceptions أثناء تنفيذ MVC، و Result filters تحيط بتنفيذ result. Filters ليست بديلاً عاماً للـ middleware؛ الـ middleware يعمل على مستوى التطبيق ويغطي endpoints أوسع.
public sealed class TimingFilter(ILogger<TimingFilter> logger) : IAsyncActionFilter
{
public async Task OnActionExecutionAsync(
ActionExecutingContext context, ActionExecutionDelegate next)
{
var started = Stopwatch.GetTimestamp();
var executed = await next();
var elapsed = Stopwatch.GetElapsedTime(started);
logger.LogInformation("Action {Action} took {ElapsedMs} ms",
context.ActionDescriptor.DisplayName, elapsed.TotalMilliseconds);
}
}
builder.Services.AddScoped<TimingFilter>();
// Apply with [ServiceFilter(typeof(TimingFilter))] on a controller/action.Filters: إمتى تستخدمها وإمتى Middleware؟
Filters تخص MVC/Razor Pages action execution، وتشتغل بعد اختيار MVC action. Middleware أوسع: تقدر تشتغل على كل request في pipeline قبل الوصول إلى MVC أو حتى لو endpoint غير MVC. استخدم middleware للـ correlation, exception boundary, request logging, security headers. استخدم filters لسلوك مرتبط بـ MVC action مثل resource/action/result handling أو metadata خاصة بالـ controller.
| Filter | When it runs | Typical use |
|---|---|---|
| Authorization | Early, before most action work | Legacy MVC authorization hooks; prefer policy authorization |
| Resource | Around model binding | Cache/short-circuit MVC resource work |
| Action | Around action method | Action-specific cross-cutting behavior |
| Exception | Handles exceptions in MVC pipeline | MVC-specific exception handling |
| Result | Around result execution | Result rendering concerns |
لا تستخدم filter لتكرار authentication أو global exception handling الموجود بالفعل في middleware. ولا تضع business validation في filter عام؛ validation مرتبطة بالـ input/domain عادة أوضح في validator/use case.
Security: لا تختزلها في JWT
Security في Web API طبقات: authentication يثبت هوية caller؛ authorization يقرر هل يحق له تنفيذ الفعل على المورد المحدد؛ validation تتحقق من المدخلات؛ rate limiting يحد من الاستهلاك؛ transport security يحمي القناة؛ و CORS يحدد browser cross-origin access فقط. CORS لا يمنع curl أو Postman ولا يثبت الهوية. تفاصيل JWT و claims و policies و cookies في مجلد Authentication & Authorization، ودرس CORS يتعمق في preflight والـ credentials. لو عايز implementation منفصل للـ handler approach راجع درس Minimal APIs، وتفاصيل مواصفات التوثيق في Swagger / OpenAPI.
app.UseHttpsRedirection();
app.UseRouting();
app.UseCors("SpaClient");
app.UseAuthentication();
app.UseRateLimiter();
app.UseAuthorization();
app.MapControllers();الترتيب الدقيق يعتمد على السياسات والـ endpoint metadata؛ اجعل CORS في موضع يتيح معالجة preflight، واجعل authorization قبل تنفيذ endpoint، وتأكد أن rate-limiting partition لا يسرّب identity data ولا يسمح بسهولة بتجاوز limits. لا تخزن access tokens في logs أو URLs.
Authentication و Authorization و CORS و Rate Limiting
الأربع مفاهيم دي بتظهر جنب بعض في Program.cs لكن كل واحدة بتحل مشكلة مختلفة. Authentication يثبت هوية caller ويكوّن ClaimsPrincipal. Authorization يقرر هل الهوية دي مسموح لها بالعملية أو المورد. CORS سياسة browser تسمح لصفحة من origin مختلف بقراءة response؛ هي لا تمنع Postman أو mobile client ولا تعتبر access control. Rate limiting يحدد معدل الطلبات لحماية capacity والعدالة، وليس إثبات هوية المستخدم.
في JWT bearer API، authentication middleware يقرأ token ويتحقق من signature/issuer/audience/expiry ثم يملأ HttpContext.User. Authorization middleware يطبق policy/role/claim/resource requirements. CORS middleware لازم يكون في موضع مناسب بعد routing وقبل authorization وفق pipeline المعتاد حتى يتعامل مع preflight. Rate limiter قد يستخدم endpoint metadata أو partition key مثل user/tenant/IP؛ اختار partition بعناية ولا تجعل IP وحده هوية المستخدم.
builder.Services.AddCors(options => options.AddPolicy("Spa", policy =>
policy.WithOrigins("https://app.example.com")
.WithMethods("GET", "POST", "PUT", "DELETE")
.WithHeaders("Content-Type", "Authorization")));
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(options =>
options.AddPolicy("InventoryReader", policy =>
policy.RequireAuthenticatedUser().RequireClaim("scope", "inventory.read")));
builder.Services.AddRateLimiter(options =>
{
options.AddFixedWindowLimiter("public-read", limiter =>
{
limiter.PermitLimit = 60;
limiter.Window = TimeSpan.FromMinutes(1);
limiter.QueueLimit = 0;
});
});
app.UseRouting();
app.UseCors("Spa");
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();ده registration sketch؛ JWT validation parameters و rate-limit partitioning محتاجين إعداداً فعلياً يناسب النظام. لا تستخدم AllowAnyOrigin مع credentials. لا تعتبر CORS بديلاً عن CSRF protection في cookie-auth browser apps، ولا تضع secrets في frontend code.
Rate Limiting: Fixed Window و Sliding و Token Bucket
Rate limiter يحدد عدد requests المسموح بها خلال window أو معدل replenishment. Fixed window بسيط لكنه يسمح burst عند حدود النافذة؛ sliding window يوزع allowance عبر أجزاء من windows؛ token bucket يسمح burst محدود مع refill؛ concurrency limiter يحد عدد العمليات المتزامنة وليس عدد requests في الدقيقة. اختار حسب workload: login brute force، public read API، expensive report generation، أو tenant fairness.
builder.Services.AddRateLimiter(options =>
{
options.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
options.AddFixedWindowLimiter("login", limiter =>
{
limiter.PermitLimit = 5;
limiter.Window = TimeSpan.FromMinutes(1);
limiter.QueueLimit = 0;
});
options.AddConcurrencyLimiter("reports", limiter =>
{
limiter.PermitLimit = 3;
limiter.QueueLimit = 2;
limiter.QueueProcessingOrder = QueueProcessingOrder.OldestFirst;
});
});
app.MapPost("/api/login", Login)
.RequireRateLimiting("login");
app.MapPost("/api/reports", CreateReport)
.RequireRateLimiting("reports");في multi-tenant system قد تحتاج partition per authenticated user/tenant؛ IP partition وحده غير عادل خلف NAT أو reverse proxy. لا تثق في forwarded headers إلا بعد ضبط trusted proxies. Rate limiting application-level لا يمنع كل volumetric DDoS؛ استخدم edge/WAF protections أيضاً. وثّق 429 و Retry-After، ولا تجعل queue كبيرة تخفي overload وتزيد latency.
CORS Preflight و Credentials
Browser يفرض Same-Origin Policy. لما JavaScript من https://app.example.com يطلب API على origin مختلف، browser قد يرسل CORS preflight OPTIONS قبل request الفعلي إذا method/header ليست simple. Server يرد بـ Access-Control-Allow-Origin/Methods/Headers. لو تستخدم cookies أو credentials، لا تجمع Allow-Credentials مع wildcard origin؛ حدد origins صراحةً. CORS headers تسمح لل browser بقراءة response، لكنها لا تمنع غير المتصفح من إرسال requests.
اختبر preflight من browser/devtools أو integration test. Postman لا يطبق browser CORS enforcement، لذلك نجاح request في Postman لا يثبت أن Angular/mobile web يعمل. CORS ليست authentication ولا authorization ولا CSRF protection.
Health، Versioning، Pagination
Health checks: live يجيب: هل process قادر يستمر؟ لا تفشل liveness لمجرد أن قاعدة البيانات مؤقتاً غير متاحة وإلا قد تدخل في restart loop. ready يجيب: هل instance مستعد لاستقبال traffic؟ يمكن أن يختبر dependencies الأساسية، لكن انتبه من جعل كل dependency اختيارية سبباً لإسقاط كل instances.
API versioning: versioning يحافظ على contract compatibility عندما يحدث تغيير كاسر. يمكن أن تكون النسخة في URL أو header أو media type. لا تضف version لمجرد تغيير internal implementation. وثّق سياسة deprecation و sunset وخطة ترحيل المستهلكين.
Pagination: لا ترجع آلاف السجلات في response واحدة. Offset pagination سهلة للفهم لكنها تصبح مكلفة مع offsets عميقة وقد تتأثر بالصفوف التي تضاف أثناء التنقل. Cursor/keyset pagination تعتمد على ترتيب ثابت ومفتاح فريد؛ غالباً أفضل للـ feeds الكبيرة.
var page = await db.Products
.Where(p => p.IsActive &&
(lastCreatedAt == null ||
p.CreatedAt < lastCreatedAt ||
(p.CreatedAt == lastCreatedAt && p.Id < lastId)))
.OrderByDescending(p => p.CreatedAt)
.ThenByDescending(p => p.Id)
.Take(pageSize + 1)
.Select(p => new ProductResponse(p.Id, p.Name, p.Price))
.ToListAsync(cancellationToken);
var hasMore = page.Count > pageSize;
if (hasMore) page.RemoveAt(pageSize);الـ compound cursor يحل مشكلة تساوي CreatedAt بإضافة Id كـ tiebreaker. يجب أن يكون ordering ثابتاً، وأن تحد pageSize بحد أقصى، وأن لا تثق في cursor مرسل من العميل من غير validation أو توقيع إن كان يحمل query state حساساً.
Health Checks و API Versioning بتفاصيل عملية
Health check endpoint يجب أن يفرق بين liveness و readiness. Liveness لا يستعلم عن كل dependency؛ هدفه كشف أن process نفسها غير قابلة للتشغيل. Readiness قد يقيّم dependencies الحرجة، ويُستخدم من load balancer لتجنب توجيه traffic إلى instance غير جاهزة. تجنب فحص dependency بعمق في كل ثانية لكل replica؛ health probing نفسه قد يصبح load إضافياً.
builder.Services.AddHealthChecks()
.AddCheck("self", () => HealthCheckResult.Healthy(), tags: ["live"])
.AddDbContextCheck<AppDbContext>("database", tags: ["ready"]);
app.MapHealthChecks("/health/live", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("live")
});
app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
Predicate = check => check.Tags.Contains("ready")
});API versioning: عند إضافة v2، حدد هل هي نسخة contract جديدة أم تغيير غير كاسر. تغييرات مثل إضافة optional response field غالباً backward compatible لكثير من clients، بينما تغيير type أو معنى field أو required input قد يكون breaking. لا تفترض أن إضافة path /v2 وحدها كافية؛ انشر OpenAPI منفصل واكتب deprecation policy وحدد مدة الدعم.
Pagination/filtering/sorting جزء من versioned contract: sort columns يجب أن تكون allow-listed، filters typed ومحددة، page size له سقف، و cursor format يجب أن يظل compatible أو يحمل version. لا تعتمد على query string كـ SQL fragment.
Health Checks و Versioning و Pagination Contract
Health endpoints ليست مجرد ping. Liveness تسأل هل process نفسها حية وقادرة على الاستمرار؛ readiness تسأل هل instance مستعدة لاستقبال traffic. لو liveness فحصت SQL server و SQL وقع، orchestrator قد يعيد تشغيل كل instances في loop ويزيد المشكلة. خلي dependency checks الحرجة في readiness مع timeouts و caching للنتيجة عند الحاجة.
API versioning يحمي client contracts. حدد strategy واحدة أو أكثر: URL segment مثل /v1، header، أو media type. أهم من مكان النسخة هو سياسة breaking changes: ما الذي يعتبر breaking؟ متى deprecated؟ كم مدة دعم version قديمة؟ وهل OpenAPI docs منفصلة؟ لا تضف version جديد لكل internal refactor.
Pagination جزء من contract. Offset مناسب لقوائم صغيرة/إدارة، keyset مناسب لتصفح مستمر على data كبيرة ومتغيرة. اجعل sort keys allow-listed، page size bounded، و cursor opaque. لا تقبل query string كأنه SQL ORDER BY fragment.
ETag و If-Match و Idempotency-Key
ETag validator يمثل version للـ representation أو resource state. العميل يقرأ resource ويحصل على ETag، ثم يرسل If-Match عند التعديل. لو النسخة تغيرت، server يرجع 412 Precondition Failed أو conflict وفق contract. ده يمنع lost updates لما عميلين يعدّلوا نفس السجل. لا تعتمد على timestamp ضعيف الدقة لو ممكن تتكرر القيمة؛ استخدم rowversion أو concurrency token مناسب.
var product = await db.Products.SingleOrDefaultAsync(p => p.Id == id, token);
if (product is null) return Results.NotFound();
// The API compares the supplied If-Match validator with the current version.
if (!ETagMatches(requestIfMatch, product.Version))
return Results.StatusCode(StatusCodes.Status412PreconditionFailed);
product.ChangePrice(newPrice);
try
{
await db.SaveChangesAsync(token);
return Results.NoContent();
}
catch (DbUpdateConcurrencyException)
{
return Results.StatusCode(StatusCodes.Status412PreconditionFailed);
}Idempotency-Key يحل مشكلة مختلفة: client أرسل POST لإنشاء عملية دفع، الشبكة قطعت قبل response، فيعيد نفس request. server يخزن key ضمن caller/tenant scope مع request fingerprint وحالة العملية والنتيجة. لو key نفسه مع نفس الطلب، يرجع النتيجة السابقة؛ لو key نفسه مع payload مختلف، يرفضه. المفتاح لازم يكون له expiry وتنظيف وسياسة concurrency، ولا يكفي وضعه في memory cache لو العملية مالية durable.
Pagination و Filtering و Sorting كـ Public Contract
API list endpoint يجب أن تحدد default page size و maximum page size، sorting keys المسموحة، filters، response envelope، و pagination metadata. لا تقبل property name من client وتضعه مباشرة في dynamic SQL. استخدم allow-list mapping من اسم public sort إلى expression محدد في code. استخدم cursor pagination عند dataset كبير ومتغير، offset pagination عندما تكون البساطة أهم والبيانات صغيرة.
IQueryable<Product> query = db.Products.AsNoTracking();
query = sortBy?.ToLowerInvariant() switch
{
"price" => descending ? query.OrderByDescending(p => p.Price)
: query.OrderBy(p => p.Price),
"name" => descending ? query.OrderByDescending(p => p.Name)
: query.OrderBy(p => p.Name),
_ => query.OrderBy(p => p.Id)
};
var pageSize = Math.Clamp(requestedPageSize, 1, 100);
var items = await query.Take(pageSize).ToListAsync(token);في المثال اختصرنا skip/cursor لأجل sorting فقط. لازم تضيف deterministic tie-breaker عند paging، وتوثق sort default، وتمنع filter expressions المفتوحة. الـ query contract جزء من API surface ويتطلب versioning/compatibility مثل response DTO.
Health Checks: Liveness و Readiness
Liveness يختبر process health، و readiness يختبر قدرة instance على استقبال traffic. افصلهم في routes/tags. فحص database readiness قد يستخدم bounded timeout ولا يعمل query ثقيلة في كل probe. لو DB وقع، readiness قد تزيل instance من load balancer؛ liveness تظل healthy حتى لا يحصل restart loop. لو process deadlocked أو لا تستجيب، liveness failure قد تستدعي restart.
لا تعرض تفاصيل dependencies أو connection strings في public health response. اعمل authorization/network restriction لو health endpoint يعرض diagnostic detail. واختبر behavior في deployment/orchestrator؛ تعريف endpoint وحده لا يجعل platform تستخدمه.
File Upload و Background Processing
في upload استخدم multipart/form-data، ضع limits على حجم request والملف، افحص content type لكن لا تعتبره دليلاً موثوقاً، لا تستخدم اسم الملف المرسل كمسار على القرص، خزّن باسم generated، وافحص malware عند الحاجة. الملفات الكبيرة قد تحتاج streaming بدلاً من buffering الكامل.
أما background processing فلا تربط عملاً طويلاً بعمر HTTP request. BackgroundService مناسب للمهام الداخلية البسيطة، لكن queue in-memory قد تفقد العمل عند restart ولا تقدم durable retries. للمهام المهمة استخدم persistent queue/job system مثل Hangfire أو message broker مع idempotent handlers. لا تستخدم Task.Run داخل controller كأنه job queue.
var extension = Path.GetExtension(upload.FileName).ToLowerInvariant();
var allowed = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{ ".pdf", ".png", ".jpg" };
if (!allowed.Contains(extension))
return Results.BadRequest("Unsupported file type.");
if (upload.Length is <= 0 or > 10 * 1024 * 1024)
return Results.BadRequest("File size is not allowed.");
var storageName = $"{Guid.NewGuid():N}{extension}";
var destination = Path.Combine(storageRoot, storageName);
await using var output = File.Create(destination);
await upload.CopyToAsync(output, cancellationToken);المثال يوضح generated name وحجم/امتداد allow-list فقط؛ production upload يحتاج أيضاً stream limits، content inspection، authorization، storage خارج web root، cleanup policy، quota، و malware scanning حسب طبيعة الملف.
File Upload Security و Streaming
امتداد الملف و Content-Type المرسل من العميل مش دليل موثوق على نوع المحتوى. اعمل allow-list، افحص file signature عند الحاجة، ضع limits على body والملف والعدد، خزن خارج web root باسم generated، افحص malware بحسب المخاطر، وامنع path traversal. اسم الملف الأصلي ممكن تحتفظ به كـ display metadata بعد sanitization، لكنه لا يصبح filesystem path.
الملفات الكبيرة تحتاج streaming لتجنب تحميل كل المحتوى في RAM. ضع per-user quotas و timeouts و cancellation. لا تجعل upload endpoint public لمجرد أنه يستقبل file؛ تحقق من صلاحية المستخدم على resource destination، وسجّل audit metadata بدون تسجيل محتوى حساس.
const long MaxBytes = 10 * 1024 * 1024;
if (file is null || file.Length <= 0 || file.Length > MaxBytes)
return Results.BadRequest("File size is not allowed.");
var extension = Path.GetExtension(file.FileName).ToLowerInvariant();
var allowed = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
{ ".pdf", ".png", ".jpg" };
if (!allowed.Contains(extension))
return Results.BadRequest("Unsupported file extension.");
var storageKey = $"{Guid.NewGuid():N}{extension}";
var path = Path.Combine(storageRoot, storageKey);
await using var target = File.Create(path);
await file.CopyToAsync(target, cancellationToken);ده مثال boundary مبسط، مش upload security كاملة: production يحتاج content sniffing، limits على multipart parser، scanning، authorization، cleanup، encryption/retention policy حسب البيانات.
Background Processing: Hosted Service ولا Job Queue؟
الـ HTTP request عمره قصير ومربوط باتصال client. لو controller بدأ Task.Run ثم رجع 202، العملية قد تضيع عند process restart، وقد تستخدم scoped services بعد انتهاء scope، ومفيش durable retry أو visibility. BackgroundService مناسب worker داخلي مستمر أو queue بسيطة داخل نفس process، لكنه لا يجعل in-memory queue durable. Hangfire أو broker/queue system أنسب لو المهمة لازم تعيش عبر restarts وتحتاج retries/monitoring.
عند تشغيل scoped dependency داخل BackgroundService، أنشئ scope لكل work item باستخدام IServiceScopeFactory. لا تحتفظ بـ DbContext في singleton worker. صمم handler idempotent لأن job قد تعاد بعد timeout أو crash. خزن status و attempt count و last error لو business يحتاج متابعة.
public sealed class CleanupWorker(
IServiceScopeFactory scopeFactory,
ILogger<CleanupWorker> logger) : BackgroundService
{
protected override async Task ExecuteAsync(CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
try
{
await using var scope = scopeFactory.CreateAsyncScope();
var cleanup = scope.ServiceProvider.GetRequiredService<IExpiredDataCleanup>();
await cleanup.RunAsync(stoppingToken);
}
catch (OperationCanceledException) when (stoppingToken.IsCancellationRequested)
{
break;
}
catch (Exception ex)
{
logger.LogError(ex, "Cleanup iteration failed");
}
await Task.Delay(TimeSpan.FromMinutes(5), stoppingToken);
}
}
}لو exception خرجت من ExecuteAsync، سلوك host عند failure يعتمد على host options/runtime configuration؛ لا تترك worker ينهار بصمت. قرر هل retry، stop host، أم log-and-continue، مع backoff و health visibility. Background task ليست بديلاً عن message broker لما تحتاج distributed delivery.
File Upload: Multipart و Limits و Storage
Multipart form يحمل file parts و form fields. استخدم IFormFile للملفات الصغيرة/المتوسطة عندما buffering مناسب، و streaming للملفات الكبيرة. حدد max request body size و per-file size، وعدد الملفات، ومدة upload. اسم الملف القادم من client غير موثوق؛ لا تستخدمه في Path.Combine. استخدم random storage key، وخزن original display name بعد sanitization منفصلاً.
افصل metadata عن binary storage: database قد تحتفظ key/size/content type/hash/owner/status، والملف نفسه في object storage أو file storage آمن. تحقق من authorization وال quota قبل وبعد upload حسب التصميم، واحذف orphaned files عند فشل transaction. لا تضع ملفات المستخدم مباشرة في static web root.
Caching و HttpClient Resilience
Output caching يخزن response الناتج وفق policy؛ لا تفعله على بيانات شخصية أو responses تختلف حسب المستخدم من غير policy صحيحة. HybridCache يقدم abstraction يجمع local/distributed caching في الإصدارات الحديثة، لكنه لا يلغي أسئلة invalidation و cache stampede. تفاصيل caching في درس قواعد البيانات.
استخدم IHttpClientFactory أو typed clients بدلاً من إنشاء HttpClient لكل request أو استخدام Singleton HttpClient مع تغييرات DNS غير مدروسة. resilience policies قد تجمع timeout و retry و circuit breaker؛ أعد المحاولة فقط للأخطاء العابرة والعمليات الآمنة أو المحمية بـ idempotency. لا تعمل retry عمياء على POST قد ينشئ عملية ثانية.
builder.Services.AddHttpClient<ExchangeRateClient>(client =>
{
client.BaseAddress = new Uri("https://rates.example.net/");
client.Timeout = TimeSpan.FromSeconds(8);
})
.AddStandardResilienceHandler();
public sealed class ExchangeRateClient(HttpClient http)
{
public Task<RateDto?> GetAsync(string currency, CancellationToken token)
=> http.GetFromJsonAsync<RateDto>($"rates/{Uri.EscapeDataString(currency)}", token);
}
public sealed record RateDto(string Currency, decimal Value);Idempotency-Key مفيد في عمليات الإنشاء/الدفع: خزّن key مع caller scope وحالة العملية والنتيجة، وارفض إعادة استخدامه بمحتوى مختلف. ETag/If-Match يوفر optimistic concurrency: لا تقبل update إذا كان resource version تغير منذ أن قرأه العميل.
Output Caching vs Data Caching
Data cache يخزن result/data من service أو repository، والـ application يقرر invalidation. Output cache يخزن HTTP response وفق endpoint policy. HTTP response caching يعتمد على HTTP cache semantics و client/proxy behavior؛ Output Cache server-side feature له policy و store. لا تخلطهم مع Redis cache abstraction.
لا تخزن response تحتوي بيانات مستخدم أو tenant في cache مشترك بدون variation/partition آمن. لا تفعّل caching على POST commands. راجع VaryByQueryKeys/headers/policy و authorization. Cache hit قد يتجاوز جزءاً من endpoint execution، فافهم أين authentication/authorization تحدث وكيف تتعامل مع personalized content. Caching لا يعالج N+1 أو query سيئة وحده؛ قس قبل وبعد.
Timeout Budget و Retry Policy
Request deadline يجب أن يتوزع على كل downstream calls. لو client ينتظر 8 ثوانٍ، لا تجعل DB command timeout 30 ثانية ثم HTTP timeout 60 ثانية؛ العملية ستظل معلقة بعد أن client فقد الاهتمام. مرر cancellation، وضع timeout لكل dependency، واجعل overall budget معروفاً. Retry يستخدم فقط مع transient failures وبحد أقصى، مع backoff+jitter. Circuit breaker يمنع الاستمرار في ضرب dependency فاشلة، و bulkhead يحد concurrency حتى failure في dependency واحدة لا يستهلك كل request capacity.
لا تعمل retry عمياء على POST أو payment. حتى GET قد يكون له side effects إذا endpoint مصمم بشكل سيئ. اكتب idempotency semantics في contract، وسجل retry count/circuit state في metrics. Resilience policies يجب أن تتناسق مع client retries و gateway retries حتى لا يحدث retry amplification.
Observability و Integration Testing
Structured logs تقول ماذا حدث، metrics تقول كم مرة/كم استغرق، traces تربط spans عبر services. Correlation ID مفيد داخل النظام؛ distributed trace context عبر W3C Trace Context يسمح بتتبع end-to-end. OpenTelemetry يوفّر APIs/SDK/exporters؛ لا تجعل tracing يسجل payload أو PII.
Integration tests تختبر التطبيق من HTTP boundary باستخدام WebApplicationFactory<Program>: routing، serialization، filters، middleware، DI، auth setup، والـ response codes. لا تجعل كل test يعتمد على نفس قاعدة بيانات مشتركة. Testcontainers يفيد في تشغيل dependency حقيقية داخل container أثناء الاختبار بدلاً من mock لسلوك SQL لا يماثل الواقع.
public sealed class ProductsApiTests(WebApplicationFactory<Program> factory)
: IClassFixture<WebApplicationFactory<Program>>
{
[Fact]
public async Task Unknown_product_returns_404()
{
var client = factory.CreateClient();
var response = await client.GetAsync("/api/products/999999");
Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
}
}قِس performance قبل التحسين؛ profiler يحدد bottleneck، BenchmarkDotNet يقارن method-level code، و k6/NBomber يختبران HTTP load. API Gateway/YARP قد يجمع routing و auth/edge policies لكن لا تستخدمه كبديل لتصميم service boundaries. SSE مناسب لتدفق server-to-client أحادي الاتجاه؛ webhook يرسل event إلى consumer؛ polling يسأل دورياً. Feature flags تفصل deployment عن release، لكن flags القديمة تتحول إلى conditional complexity ويجب تنظيفها.
Integration Testing: اختبر التطبيق من برّه
Unit test للـ service سريع ويعزل business rules. Integration test عبر WebApplicationFactory<Program> يشغّل host in-memory ويختبر routing و middleware و DI و serialization و filters و HTTP status. Testcontainers يقدر يشغّل SQL Server/PostgreSQL حقيقي للاختبارات التي تعتمد على database behavior، بدلاً من SQLite أو mocks إذا كان provider behavior مهماً.
public sealed class ProductsApiTests
: IClassFixture<WebApplicationFactory<Program>>
{
private readonly HttpClient _client;
public ProductsApiTests(WebApplicationFactory<Program> factory)
=> _client = factory.CreateClient();
[Fact]
public async Task Missing_product_returns_404_problem()
{
var response = await _client.GetAsync("/api/products/999999");
Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
Assert.Equal("application/problem+json",
response.Content.Headers.ContentType?.MediaType);
}
}في الاختبارات لا تعتمد على production secrets أو production database. استبدل external services ب fakes عندما تختبر application behavior، واستخدم container حقيقي لما يكون الهدف اختبار provider/migration/transaction/SQL behavior. اختبر failure paths أيضاً: timeout، invalid payload، unauthorized، conflict، و cancellation.
Outbox و Webhooks و API Gateway و Feature Flags
خطر شائع: تحفظ Order في DB ثم ترسل event إلى broker؛ لو نجح commit وفشل publish، تصبح البيانات محفوظة لكن event ضاع. Outbox pattern يحل dual-write: اكتب business change و outbox row في نفس database transaction، ثم background dispatcher ينشر الرسالة ويعلّمها published. Consumer لازم يكون idempotent؛ غالباً at-least-once delivery تعني احتمال تكرار الرسالة.
Webhook outgoing لازم يكون موقّعاً، مثلاً HMAC-SHA256 على timestamp + raw request body، والـ receiver يقارن signature بشكل constant-time ويتحقق من timestamp/replay window. استخدم delivery ID، retries مع exponential backoff+jitter، حد أقصى لمحاولات الإرسال، و dead-letter/failed deliveries page. لا تعتمد على IP allow-list وحده كإثبات authenticity.
YARP API Gateway/Reverse Proxy يمكنه routing و load balancing و transformations، لكن لا تجعل gateway يحتوى كل business logic أو يصبح giant monolith. BFF يخصص API لواجهة محددة (موبايل أو SPA) لتقليل round trips، مع الانتباه لتكرار logic. Feature flags تفصل deploy عن release؛ flags تحتاج owner و expiry/cleanup حتى لا تتراكم branches منتهية الصلاحية.
Outbox و Webhooks: ضمانات التكامل
لو كتبت order في SQL ثم نشرت message إلى broker، عندك dual-write problem: ممكن SQL commit ينجح والـ publish يفشل، أو العكس. Outbox pattern يخزن business row و outbox message في نفس transaction. Worker يقرأ رسائل pending، ينشرها، ثم يعلّمها published. النشر غالباً at-least-once، لذلك consumer لازم يكون idempotent ويتعامل مع duplicate message IDs.
Webhook هو HTTP callback إلى نظام خارجي. لازم تحدد event ID، signature، timestamp/replay window، retry policy، timeout، maximum attempts، وحالة delivery. وقّع raw body مع timestamp باستخدام HMAC، وقارن signature بطريقة constant-time. لا تثق في IP address فقط، ولا تعيد محاولة 4xx بلا تمييز؛ 429 و5xx قد يستحقان retry، بينما 400 غالباً خطأ contract.
var signedPayload = Encoding.UTF8.GetBytes($"{timestamp}.{rawBody}");
var key = Encoding.UTF8.GetBytes(webhookSecret);
var expected = HMACSHA256.HashData(key, signedPayload);
var supplied = Convert.FromHexString(signatureHex);
var valid = CryptographicOperations.FixedTimeEquals(expected, supplied);
if (!valid || IsOutsideReplayWindow(timestamp))
return Results.Unauthorized();الـ snippet يوضح signature verification فقط؛ تأكد من parsing آمن، طول signature المتوقع، التعامل مع encoding، secret rotation، وعدم قبول replay. API Gateway/YARP يوجّه traffic ويطبق edge concerns، لكنه لا يعوض outbox أو business transaction design.
Background Work و Outbox Reliability
فرق بين background work best-effort و durable business work. تنظيف cache قد يكون best-effort؛ إرسال فاتورة أو نشر event بعد order commit قد يكون business-critical. في الحالة الثانية استخدم durable job/message/outbox، لا in-memory queue فقط. Outbox يخزن event في نفس transaction مع business state ثم dispatcher ينشره. Consumer يتعامل مع duplicates عن طريق inbox/deduplication أو idempotent update.
حدد retry policy لكل failure class، و dead-letter visibility، و manual replay process، و retention. لا تعمل retry إلى ما لا نهاية؛ الرسالة السامة قد تستهلك resources باستمرار. راقب queue age و failed job count و oldest pending item.
Production Readiness للـ API
قبل نشر API، تأكد من health endpoints، structured logs، trace context، metrics، exception handling، rate limits، request size limits، timeouts، cancellation، graceful shutdown، secrets management، HTTPS، CORS policy، auth policies، OpenAPI contract، و integration tests. دي مش إضافات اختيارية بعد كتابة endpoints؛ هي جزء من API design.
Graceful shutdown مهم لأن host قد يستقبل termination signal أثناء deploy/scale-in. امنع استقبال requests جديدة، واترك in-flight requests تكمل ضمن grace period، وأوقف background workers بشكل منظم. لا تعتمد على in-memory queue لو فقدان العمل غير مقبول. راقب startup failure بسبب invalid options أو migrations، ولا تجعل health check تقول ready قبل اكتمال initialization الضروري.
Resilience لا تعني retry لكل شيء. حدد timeout لكل dependency، maximum retry attempts، jitter، circuit breaker، bulkhead/concurrency limit، و fallback لو business يسمح. اجمع metrics للـ retries/circuit state حتى تعرف إن resilience policy نفسها لا تخفي outage مستمرة.
API Production Checklist بالتفصيل
| Area | Questions before release |
|---|---|
| Contract | Methods, routes, DTOs, status codes, pagination, versioning documented? |
| Security | Authentication, resource authorization, CORS, CSRF, input limits? |
| Reliability | Timeouts, cancellation, retries, idempotency, outbox where needed? |
| Operations | Health/readiness, structured logs, metrics, traces, graceful shutdown? |
| Performance | Query shape, pagination, caching policy, payload size, load test? |
| Testing | Unit, integration, database integration, negative paths? |
لا تعتبر كل check checkbox ميكانيكية؛ اربطها بمخاطر الـ endpoint. Public read endpoint يختلف عن payment command أو admin import. لكن كل endpoint يجب أن يكون له owner و contract و monitoring وسلوك failure مفهوم.
Knowledge Check
هل يمكن استخدام Output Cache على endpoint يرجع بيانات الحساب الحالي؟
متى يكون Retry غير آمن؟
ما الفرق بين liveness و readiness؟
لماذا نستخدم WebApplicationFactory؟
هل CORS يغلق الوصول للـ API من خارج المتصفح؟
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
خريطة التغطية: 35 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.