Software Engineer Encyclopedia
0%
Domain 03 · Backend Engineering & Web Development · Topic 3.5

DTOs والـ Validation وإدارة الأخطاء

DTOs, Validation & Errors

حدود API آمنة، input validation، DataAnnotations وFluentValidation، mapping، Problem Details، exception taxonomy ومنع تسريب البيانات.

  • Intermediate
  • ~16 min read
  • 7 sections
  • 13 code examples
  • 1 diagrams
  • 4 questions
  • Priority L1 · Essential
  • .NET 10 LTS · C# 14

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

C# و.NET (المجال 02) والـ HTTP/Networking (درس 1.2).

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

DEEPBuild predictable API responses and safe error handling.

01

Entity vs DTO: متكشفش شكل الداتابيز

Request contracts and response models
Deep dive

Entity نموذج داخلي له identity وسلوك/علاقات وقواعد persistence. DTO نموذج نقل بيانات مصمم لغرض API محدد. فصل الاثنين يمنع over-posting، ويمنحك حرية تغيير database schema دون كسر client contract، ويساعدك في إخفاء internal fields. لا تحتاج DTO لكل class؛ استخدمها عند boundary أو projection حسب الحاجة.

C#Safe create/update DTOs
public sealed record CreateUserRequest(string Email, string DisplayName);
public sealed record UpdateProfileRequest(string DisplayName);
public sealed record UserResponse(int Id, string Email, string DisplayName);

public sealed class User
{
    public int Id { get; private set; }
    public string Email { get; private set; }
    public string DisplayName { get; private set; }
    public bool IsAdmin { get; private set; }
    public User(string email, string displayName)
        => (Email, DisplayName) = (email, displayName);
}

static UserResponse Map(User user)
    => new(user.Id, user.Email, user.DisplayName);

لو استخدمت Entity مباشرة كـ input، مهاجم قد يرسل IsAdmin=true أو يغير ownership property لم تقصد فتحها. الـ DTO allow-list يحدد بالضبط ما يمكن تعديله.

تصميم Request و Response DTOs كعقد مستقل

Request DTO يصف ما يسمح العميل بإرساله في use case معينة، و Response DTO يصف ما تسمح أنت بعرضه. لا تجعل Create و Update و List و Details تشترك في DTO واحد لمجرد أن معظم الحقول متشابهة. كل operation لها allowed fields مختلفة. مثال: العميل قد يحدد عنوان الشحن عند إنشاء order، لكنه لا يحدد Total أو PaymentStatus؛ هذه قيم يحسبها النظام.

C#Separate contracts for separate operations
public sealed record CreateOrderRequest(
    int ShippingAddressId,
    IReadOnlyList<CreateOrderLine> Items);

public sealed record CreateOrderLine(int ProductId, int Quantity);

public sealed record OrderDetailsResponse(
    int Id,
    string Status,
    decimal Total,
    DateTimeOffset CreatedAt,
    IReadOnlyList<OrderLineResponse> Items);

public sealed record OrderLineResponse(
    int ProductId, string ProductName, int Quantity, decimal UnitPrice);

Response contract لا ينبغي أن يكشف navigation properties أو internal audit columns أو password hash. كمان لا تعرض EF entity مباشرة لتجنب serialization cycles و lazy-loading surprises وربط API بالـ schema. عند إضافة field جديد، فكر في backward compatibility للـ mobile clients القديمة.

Nullability و Partial Updates في DTOs

في update DTO، nullable property قد تعني أن القيمة optional، لكن هل null معناها «لا تغيّر» أم «امسح القيمة»؟ ده contract decision. لو الاتنين مطلوبين، استخدم presence wrapper/JsonPatch أو DTO مخصص يميز field omitted عن explicit null. نفس المشكلة تظهر مع default value للـ int/bool: غياب field قد يتحول إلى 0 أو false وتفقد معرفة هل العميل أرسله.

مع C#‎ nullable reference types، compiler يساعدك داخل code لكنه لا يضمن أن JSON client أرسل قيمة. JSON deserialization والـ validation هما boundary. عيّن defaults بحذر، واستخدم required members/validation حسب framework version، واختبر JSON cases المختلفة.

DTO Evolution و Backward Compatibility

DTO public contract ممكن يعيش أطول من C#‎ class نفسها. لا تغير property names/types عشوائياً، ولا تجعل field كانت optional required فجأة. عند إضافة property، حدد default behavior للـ old clients. عند تغيير enum، راجع generated clients و switch expressions. استخدم versioning عند breaking change، أو additive migration عندما ممكن.

لا تجعل DTO يرث من Entity أو يشارك نفس base class لمجرد إعادة استخدام properties؛ ده يربط public API بالـ persistence model. استخدم composition/record types واضحة، واعمل mapping explicit عند boundary. إذا كان عندك list DTO و details DTO مختلفين، ده مقصود لتقليل payload وإخفاء fields غير لازمة.

DTO Anti-patterns

  • Entity as request: يفتح overposting ويربط API بالـ persistence.
  • One DTO for every operation: create/update/details/list لها fields مختلفة.
  • Huge response graph: يسبب cycles و over-fetching وتسريب fields.
  • Mapping with hidden I/O: يخلي mapping غير predictable ويصعب اختباره.
  • Validation only in UI: client can bypass it.
  • Check-then-insert without DB constraint: race condition.
  • Returning exception.Message: information disclosure.

DTO design مش هدفه زيادة classes لذاتها. استخدم request/response models لما boundary needs them، واجعلها صغيرة ومقصودة. لو internal method يمرر domain object داخل نفس layer، لا تنشئ DTO جديداً بلا سبب.

DTOs كـ Security Boundary

DTO يقلل mass assignment لكنه لا يحل authorization وحده. ممكن DTO يسمح بـ ShippingAddressId، لكن لازم تتأكد أن العنوان يخص المستخدم الحالي. وممكن response DTO يخفي password hash، لكن يجب أيضاً حماية logs/cache/export endpoints. فكر في DTO كـ allow-list للبيانات التي تعبر boundary، ثم طبّق access control على resource نفسها.

لـ multi-tenant APIs، لا تثق في TenantId من body أو query كأنه tenant context موثوق. استخرج tenant من authenticated identity أو verified host/claim، ثم تحقق من resource belongs-to tenant. لو endpoint admin يسمح باختيار tenant، اجعل ذلك policy منفصلة وموثقة.

02

Input Validation: Syntax ثم Semantics

Data annotations, custom, cross-field rules
Deep dive

Validation طبقات: syntactic (هل البريد بصيغة مقبولة؟)، semantic/business (هل الكمية متاحة؟)، authorization (هل caller يستطيع تعديل الكيان؟). DataAnnotations سهلة للقواعد البسيطة، custom validation تضيف rule خاصة، و FluentValidation تجعل القواعد المركبة قابلة للتركيب والاختبار. لا تجعل validation بديلاً عن database constraints؛ race conditions تظل ممكنة.

C#DataAnnotations and cross-field validation
public sealed class BookingRequest : IValidatableObject
{
    [Required, StringLength(80, MinimumLength = 2)]
    public string CustomerName { get; init; } = "";

    [Required]
    public DateOnly StartDate { get; init; }

    [Required]
    public DateOnly EndDate { get; init; }

    public IEnumerable<ValidationResult> Validate(ValidationContext context)
    {
        if (EndDate <= StartDate)
            yield return new ValidationResult(
                "EndDate must be after StartDate.",
                new[] { nameof(EndDate), nameof(StartDate) });
    }
}

مع controller APIs و [ApiController] يعاد 400 تلقائياً عند invalid ModelState. مع Minimal APIs توجد validation mechanisms حديثة في ‎.NET 10، لكن تحقق من framework behavior والـ package/version لأن النمط يختلف عن MVC model validation.

C#FluentValidation validator
public sealed class CreateProductValidator : AbstractValidator<CreateProductRequest>
{
    public CreateProductValidator()
    {
        RuleFor(x => x.Name).NotEmpty().MaximumLength(120);
        RuleFor(x => x.Price).GreaterThan(0);
        RuleFor(x => x.Currency).NotEmpty().Length(3);
    }
}

Async validation مثل التأكد من uniqueness عبر DB يحتاج cancellation token ويجب ألا يسبب N+1 database calls. حتى لو تحققت أن email غير مستخدم، ضع unique constraint في DB لأن طلبين متزامنين قد ينجحان في validation قبل insert.

Validation في كل Layer من غير تكرار عشوائي

Boundary validation تتحقق من الشكل والحجم والصيغة: required، max length، numeric range، date parse. Application validation تتحقق من شروط use case: هل المنتج موجود؟ هل المستخدم يملك المورد؟ Domain validation تحمي invariants: لا يمكن إتمام order ملغي. Database constraints تحمي integrity تحت concurrency: unique index و foreign key و check constraint. بعض القواعد تظهر في أكثر من مكان لأسباب مختلفة، لكن مصدر الحقيقة business rule لازم يبقى واضحاً.

مثلاً التحقق من أن البريد غير مستخدم في validator يعطي رسالة مبكرة، لكنه لا يمنع race condition بين طلبين متزامنين. لازم unique index في DB، ثم تترجم duplicate-key exception إلى conflict response مناسب. لا تعتمد على pre-check وحده.

C#Cross-field validation without database assumptions
public sealed class DateRangeRequest : IValidatableObject
{
    public DateOnly Start { get; init; }
    public DateOnly End { get; init; }

    public IEnumerable<ValidationResult> Validate(ValidationContext context)
    {
        if (End <= Start)
            yield return new ValidationResult(
                "End must be after Start.",
                [nameof(End), nameof(Start)]);
    }
}

FluentValidation: تركيب قواعد قابلة للاختبار

FluentValidation مناسبة لما القواعد تكبر وتحتاج composition و conditional rules و RuleSets و async checks. افصل validator عن controller/endpoint، واختبره مباشرة. Async rules التي تستعلم عن DB لازم تستخدم cancellation token، وتتجنب query لكل عنصر في collection. لا تضع business workflow كامل داخل validator؛ validator يفحص preconditions، والـ use case ينفذ العملية.

C#Validator with conditional and collection rules
public sealed class CreateInvoiceValidator : AbstractValidator<CreateInvoiceRequest>
{
    public CreateInvoiceValidator()
    {
        RuleFor(x => x.CustomerId).GreaterThan(0);
        RuleFor(x => x.Currency).NotEmpty().Length(3);
        RuleFor(x => x.Lines).NotEmpty().Must(lines => lines.Count <= 100);

        RuleForEach(x => x.Lines).ChildRules(line =>
        {
            line.RuleFor(x => x.ProductId).GreaterThan(0);
            line.RuleFor(x => x.Quantity).InclusiveBetween(1, 500);
        });

        RuleFor(x => x.DueDate)
            .GreaterThan(DateOnly.FromDateTime(DateTime.UtcNow))
            .When(x => x.PaymentTerms == PaymentTerms.Deferred);
    }
}

ملاحظة: قواعد التاريخ التي تعتمد على current time قد تجعل الاختبار حساساً للوقت؛ الأفضل حقن TimeProvider أو تمرير clock abstraction عندما يكون الوقت جزءاً من business rule. كذلك تحقق من package registration/version عند استخدام auto-validation integration؛ لا تفترض أن كل integration يدعم async validators بالطريقة نفسها.

اختبار Validation و Error Contracts

لا تختبر validator فقط على happy path. اختبر null/empty، boundary lengths، negative numbers، cross-field rules، collection limits، async dependency unavailable، cancellation، والـ duplicate race condition عند مستوى DB integration. في API integration tests، تحقق من status code و Problem Details content type و field error keys، وليس فقط أن response 400.

لا تعتمد على ترتيب errors في JSON إلا لو contract ينص عليه؛ قارن keys/values. اجعل error code stable، والرسالة البشرية قابلة للتغيير أو الترجمة. لا تعرض stack trace أو raw SQL أو internal exception type.

C#Assert the error contract
var response = await client.PostAsJsonAsync("/api/products",
    new { name = "", price = -1 });

Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
var problem = await response.Content.ReadFromJsonAsync<ValidationProblemDetails>();
Assert.NotNull(problem);
Assert.Contains("name", problem.Errors.Keys);
Assert.Contains("price", problem.Errors.Keys);

Validation Edge Cases: Culture و Dates و Money

الأرقام والتواريخ قد تتأثر بالـ culture إذا استخدمت form/query parsing أو parsing يدوي. JSON numbers لها semantics ثابتة نسبياً، لكن custom string parsing يجب أن يحدد culture/format. استخدم DateTimeOffset للـ timestamps التي تمثل لحظة زمنية، و UTC internally، و DateOnly للأيام التقويمية مثل تاريخ الميلاد/الحجز إذا لا يوجد time zone. لا تعامل local time كأنه UTC.

Money يحتاج currency و precision واضحين. decimal أفضل من float/double في business calculations، لكن لازم تحدد rounding rules والـ currency minor units. Validator يتأكد من shape/range؛ domain service يطبق business policy مثل allowed currencies أو max discount.

Async Validation و Uniqueness Race

Async validator قد يسأل repository هل username/email موجود. ده مفيد لرسالة friendly قبل تنفيذ command، لكنه ليس guarantee. بين check و insert ممكن request آخر يحفظ نفس القيمة. لذلك database unique index هو الحماية النهائية. عند duplicate exception، ترجم provider-specific error إلى application conflict. لا تستخدم check-then-insert وحده.

كمان لا تعمل query واحدة لكل item في collection validator؛ اجمع IDs واعمل batch existence check. مرر CancellationToken، وحدد timeout، ولا تجعل validator ينفذ business transaction كاملة.

03

Mapping Strategies

Manual mapping, Mapperly, AutoMapper
Practical

Manual mapping مناسب عندما التحويلات قليلة أو فيها business decisions واضحة. Mapperly source generator ينتج code وقت build ويمكنك مراجعة الناتج. AutoMapper يعمل runtime mapping بالـ conventions/configuration ومفيد في DTO-heavy applications لكنه قد يخفي query behavior أو يفشل عند runtime لو config غير مختبرة. لا تحوّل EF entity بعد materialization إذا كان projection إلى DTO داخل LINQ أكثر كفاءة.

C#Project only requested columns
var response = await db.Products
    .Where(p => p.Id == id)
    .Select(p => new ProductResponse(p.Id, p.Name, p.Price))
    .SingleOrDefaultAsync(cancellationToken);

Manual Mapping و Mapperly و AutoMapper

Manual mapping واضح وسهل تتبع debugging، لكنه قد يتكرر. Mapperly source generator ينتج mapping code وقت build فيكون الأداء واضحاً ولا يحتاج reflection mapping runtime. AutoMapper مناسب في بعض التطبيقات ذات DTO mapping الكثير، لكن profile configuration يجب اختباره، ولا تستخدم ProjectTo إلا مع provider يدعم التعبير الناتج. لا تخفِ business decisions داخل mapping profile.

أهم نقطة في EF Core هي projection: لو احتجت 4 أعمدة، لا تحمل entity كاملة ثم تحولها إلى DTO. استخدم Select حتى قاعدة البيانات ترجع الأعمدة المطلوبة فقط. هذا يقلل memory و network payload، ويمنع accidental navigation loading.

C#Projection instead of materialize-then-map
var page = await db.Products
    .AsNoTracking()
    .Where(p => p.IsPublished)
    .OrderBy(p => p.Name)
    .Select(p => new ProductListItem(
        p.Id, p.Name, p.Price, p.Category.Name))
    .Take(50)
    .ToListAsync(cancellationToken);

Manual Mapping خطوة بخطوة

Manual mapping مش مجرد نقل properties بنفس الاسم. ممكن يحول enum إلى public string، يخفي fields، يجمع child data، أو يحول value object إلى primitive. خليه pure قدر الإمكان: لا يعمل DB query ولا يرسل email ولا يقرر business rule. لو mapping يحتاج data إضافية، اعمل projection/query service تجيب البيانات المطلوبة ثم map.

C#Map an internal entity to a public response
static OrderDetailsResponse ToResponse(Order order) => new(
    Id: order.Id,
    Status: order.Status.ToString(),
    Total: order.Total.Amount,
    Currency: order.Total.Currency,
    CreatedAt: order.CreatedAt,
    Items: order.Items.Select(item => new OrderLineResponse(
        item.ProductId,
        item.ProductNameSnapshot,
        item.Quantity,
        item.UnitPrice.Amount)).ToArray());

لاحظ أن response لا يعرض internal navigation graph بالكامل. ProductNameSnapshot قد يكون القيمة التي احتفظ بها order وقت الشراء، وليس اسم المنتج الحالي؛ ده domain decision وليس mapping convenience. اختبر mapping على null/empty collection و enum unknown values عند deserializing legacy data.

اختبار DTO Mapping و Error Translation

Mapping tests مهمة لما التحويل فيه قواعد مثل status enum mapping، hidden fields، snapshots، money/currency، أو nullable semantics. اختبر أن internal properties لا تظهر في response، وأن unknown enum values لا تتحول إلى معنى مضلل، وأن collections الفارغة تبقى empty arrays حسب contract. اختبر mapping errors إلى HTTP statuses بشكل exhaustive.

لكن لا تختبر كل property trivially في كل DTO لو mapping direct وبسيط جداً؛ ركز على mapping الذي يحمل decisions أو security implications. واستخدم API integration tests لتأكيد أن serializer فعلاً ينتج JSON schema المتوقع.

04

Error Taxonomy و Problem Details

Expected failures vs unexpected exceptions
Deep dive

لا تستخدم exception كـ if statement في كل business validation. صنّف النتائج: validation errors (400/422 حسب contract)، not found (404)، conflict (409)، forbidden (403)، و infrastructure failure (عادة 500 أو 503 حسب الحالة). Domain error ينبغي أن يحمل معنى business، لا تفاصيل SQL. Application layer يمكنها تحويل domain result إلى HTTP Problem Details.

C#Mapping a typed application error
public abstract record AppError(string Code, string Message);
public sealed record ProductNotFound(int Id)
    : AppError("product.not_found", $"Product {Id} was not found.");
public sealed record PriceConflict()
    : AppError("product.price_conflict", "The price changed.");

static IResult ToHttpResult(AppError error) => error switch
{
    ProductNotFound => Results.Problem(
        statusCode: StatusCodes.Status404NotFound,
        title: "Product not found",
        extensions: new Dictionary<string, object?> { ["code"] = error.Code }),
    PriceConflict => Results.Problem(
        statusCode: StatusCodes.Status409Conflict,
        title: "Conflict",
        extensions: new Dictionary<string, object?> { ["code"] = error.Code }),
    _ => Results.Problem(statusCode: 500, title: "Unexpected error")
};

Exception logging يكون عند boundary واحد غالباً، مع stack trace للـ internal logs. لا تسجل نفس exception في repository ثم service ثم controller. لا ترجع exception.Message مباشرة للعميل؛ قد تحتوي connection strings أو paths أو SQL details. Error code ثابت يصلح للـ client logic، أما message فتصلح للعرض ولا يعتمد عليها البرنامج كـ protocol.

Problem Details و Correlation و Error Logging

العميل يحتاج error contract ثابت؛ فريق التشغيل يحتاج traceId و stack trace داخلي. لا تخلط الاثنين. response قد يحتوي status/title/code/traceId ورسائل validation آمنة. logs الداخلية قد تحتوي exception type و stack و dependency context، لكن لا تسجل secrets أو access tokens أو بيانات شخصية غير لازمة. سجّل exception مرة واحدة عند boundary مناسب حتى لا تتكرر نفس المشكلة في كل layer.

اختار status code حسب semantics: 400 malformed/invalid request، 401 no valid authentication، 403 authenticated but not allowed، 404 resource absent، 409 state conflict، 412 failed HTTP precondition، 422 semantic validation عند اعتماد contract بهذا الشكل، 429 rate limited، 500 unexpected server failure، 503 temporarily unavailable. لا تجعل status code مجرد انعكاس لنوع exception.

Error Catalog و Consistent HTTP Mapping

في API كبيرة، اعمل catalog للأخطاء المتوقعة: product.not_found، inventory.insufficient_stock، order.invalid_transition، customer.duplicate_email. كل error له stable code وتصنيف/status mapping. ده يمنع كل endpoint من اختراع status/message مختلفة لنفس business condition.

لا تجعل code يحمل تفاصيل متغيرة مثل product ID أو SQL state. التفاصيل تذهب في safe extensions أو logs. ولا تستخدم HTTP status كبديل عن code؛ 409 قد يمثل أكثر من business conflict، والعميل قد يحتاج يميز بينهم.

Exception Boundaries و Logging Ownership

Repository لا ينبغي أن يحول كل SqlException إلى 404. Service لا ينبغي أن يلتقط كل Exception ويرجع null. Controller لا ينبغي أن يكرر try/catch لكل action. خلي exceptions غير المتوقعة تصعد إلى global exception handler، وخلي expected business failures ممثلة في Result/domain errors. سجل الاستثناء مرة واحدة عند boundary مع traceId، واحتفظ بالـ stack داخلياً.

لو عندك exception معروف مثل unique constraint violation، ترجمها عند boundary القريبة من database/provider إلى application error مناسب، ثم حوّلها إلى HTTP 409. لا تجعل Application layer تعتمد على SQL Server exception number إلا لو عندها abstraction واضح يفصل provider details.

Expected vs Unexpected Failures

Validation failure من input غالباً 400/422. Resource not found غالباً 404. State conflict 409. Unauthorized 401 و forbidden 403. Infrastructure outage قد تكون 503 أو 500 حسب القدرة على استعادة الخدمة. Expected business branch لا يحتاج exception كل مرة؛ Result/error union قد يكون أوضح. Unexpected bug أو invariant breach يستحق exception مع diagnostics.

لا تجعل null يمثل كل failures؛ null لا يوضح هل not found أم forbidden أم dependency failure. ولا تستخدم exceptions كبديل عن normal branching في high-frequency validation. اجعل error mapping centralized واختبر كل mapping.

Mapping Domain Errors إلى Problem Details

Domain/Application layers لا ينبغي أن ترجع IActionResult أو IResult؛ دي types تخص HTTP boundary. خلي application ترجع Result أو typed errors، والـ API layer يحولها إلى HTTP. ده يسمح باستخدام نفس use case من HTTP endpoint أو background job أو message consumer من غير ربطها بـ ASP.NET Core.

C#Application error to HTTP mapping at the boundary
static IResult ToHttpResult(AppError error) => error switch
{
    ValidationError e => Results.ValidationProblem(e.Errors),
    ResourceNotFound e => Results.Problem(
        statusCode: StatusCodes.Status404NotFound,
        title: "Resource not found",
        extensions: new Dictionary<string, object?> { ["code"] = e.Code }),
    StateConflict e => Results.Problem(
        statusCode: StatusCodes.Status409Conflict,
        title: "The current state does not allow this operation",
        extensions: new Dictionary<string, object?> { ["code"] = e.Code }),
    _ => Results.Problem(statusCode: 500, title: "Unexpected error")
};

اجعل mapping exhaustive قدر الإمكان. لو ظهر error type جديد ولم يتم التعامل معه، لا تسقطه بصمت إلى 200 أو 400. أضف tests لكل error/status mapping.

Error Response Checklist

  • Status code يعبر عن HTTP semantics.
  • Problem Details content type مضبوط.
  • Stable machine-readable code موجود عند الحاجة.
  • Validation errors مربوطة بأسماء fields في public DTO.
  • Trace ID يساعد support بدون كشف internals.
  • لا يوجد stack trace أو SQL/connection details.
  • الـ logs الداخلية تسجل exception مرة واحدة.
  • الـ client يستطيع تحديد هل يصلح input أو يعيد المحاولة أو يطلب صلاحية.
05

Value Objects و Primitive Obsession

Validation close to the domain concept
Practical

لو كل email مجرد string وكل money مجرد decimal، يصبح ممكن تمرير قيمة غلط إلى method. Value Object يغلّف concept بقواعد construction/equality واضحة. مش لازم كل primitive يتحول class؛ استخدمه عندما الاسم والقواعد لها معنى domain مستقر.

C#EmailAddress value object
public sealed record EmailAddress
{
    public string Value { get; }

    private EmailAddress(string value) => Value = value;

    public static bool TryCreate(string? raw, out EmailAddress? email)
    {
        email = null;
        if (string.IsNullOrWhiteSpace(raw) || raw.Length > 254) return false;
        var normalized = raw.Trim();
        if (!MailAddress.TryCreate(normalized, out _)) return false;
        email = new EmailAddress(normalized.ToLowerInvariant());
        return true;
    }
}

هذا تحقق شكلي فقط؛ صحة mailbox الفعلية تحتاج confirmation flow. استخدم value object لتثبيت invariant في domain، بينما API validation تحوّل input غير صالح إلى 400/422 بدل ظهور exception غير متوقع.

06

اختيار مكان Validation

Boundary, application, domain, and database
Deep dive
LayerWhat to validateExample
HTTP boundaryShape, required fields, format, max lengthEmail syntax, pageSize limit
ApplicationUse-case preconditions and permissions orchestrationCaller may update this resource
DomainBusiness invariantsCannot ship a cancelled order
DatabaseConcurrency-safe constraintsUnique index, FK, check constraint

تكرار بعض checks مقصود لأن layers تحمي boundaries مختلفة، لكن تجنب نسخ نفس business rule حرفياً في 4 أماكن. اجعل domain هو authority للقواعد التجارية، والـ DB تحمي integrity تحت concurrency، والـ API تعطي feedback جيداً للمستخدم.

Validation Layers: مين مسؤول عن إيه؟

HTTP Boundary · shape / format / sizeApplication · use-case preconditionsDomain · business invariantsDatabase · integrity / concurrency
كل طبقة تحمي نوعاً مختلفاً من صحة البيانات.

لو كل شيء في controller، domain invariant ممكن يتم تجاوزها من background job. لو كل شيء في database، client يحصل على رسائل سيئة وغير مفهومة. لو كل شيء في validator، race conditions تظل موجودة. وزّع المسؤولية: boundary تعطي feedback مبكر، application تنسق use case، domain يحمي business truth، database تحمي integrity حتى تحت concurrency.

07

Knowledge Check

DTO and error design
Basics
لماذا لا نستقبل EF entity مباشرة في POST؟
لتجنب over-posting وكشف حقول داخلية وربط public contract بقاعدة البيانات.
هل email uniqueness check في validator كافٍ؟
لا؛ لازم unique constraint في قاعدة البيانات لمقاومة التزامن والسباق.
متى أستخدم Result ومتى Exception؟
Result للأخطاء المتوقعة التي تمثل branch طبيعي من business operation؛ Exception للأحداث غير المتوقعة أو الفشل الاستثنائي، مع عدم تحويل كل شيء إلى ceremony.
هل تفاصيل exception تظهر في Problem Details؟
لا في production. أرسل عنواناً عاماً و traceId/code، واحتفظ بالتفاصيل في protected logs.
↗

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

References & further reading

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

مصادر تعليمية ومتقدمة — Third-party & advanced reading

خريطة التغطية: 17 عنصر من الـ Roadmap ومكان شرحه في الدرس
RoadmapEntities vs DTOs§01
RoadmapRequest DTOs vs Response DTOs§01
RoadmapInput Validation§02
RoadmapData Annotations§02
RoadmapCustom Validation§02
RoadmapCross-Field Validation§02
RoadmapObject Mapping§01
RoadmapValidation Error Responses§04
RoadmapGlobal Exception Handling§04
RoadmapProblem Details§04
RoadmapDomain vs Infrastructure Exceptions§04
RoadmapException Logging§04
RoadmapPreventing Sensitive Data Leakage§04
SuggestedFluentValidation vs Data Annotations§02
SuggestedManual mapping vs Mapperly vs AutoMapper trade-offs§01
SuggestedValue objects instead of primitive obsession§01
SuggestedMapping Result errors to Problem Details§04

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

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