ASP.NET Core / الأساسي: HTTP وتركيب التطبيق / الدرس 4
ربط Minimal APIs ونتائجها
حدد مصادر المدخلات ومعنى DTO والتحقق وبدائل النتائج ذات الأنواع، دون اعتبار المعالج المختصر عقد API كاملا.
في هذه الصفحة
أهداف الدرس
- شرح ربط قيم المسار والاستعلام والجسم والخدمات.
- فصل فشل الربط من رفض قواعد المجال.
- استخدام أنواع نتائج وبيانات وصفية صريحة لنقطة النهاية.
لمعامل المعالج عقد مصدر
قد تربط Minimal APIs قيما من المسار والاستعلام والرؤوس وJSON والنموذج وDI وربط خاص مدعوم. قد يستنتج المصدر من النوع والطريقة والتسجيل، فيغير تعديل بسيط للتوقيع السلوك. استخدم صفات صريحة عندما يعيق الغموض المراجعة. DTO الطلب نموذج حدود لا كيان EF تلقائيا.
لا تربط GET وبعض الطرق الموثقة معاملات جسم اعتباطية ضمنيا كما تفعل POST. صرح بالمصدر عندما يتطلبه العقد، وراع دلالة الطريقة والمخبأ ودعم العميل. لا تختر التوقيع لنجاح ترجمته فقط؛ يبقى المصدر وحد الثقة مسؤوليتين واضحتين.
يحتاج إعلان النقطة مضيفا وخدمات داعمة
يسمي المقتطف مصدر المسار والاستعلام مباشرة. يبقى غير قابل للتشغيل لأن إنشاء التطبيق والخدمات وتنفيذ الطلب والتكامل خارجه. يمثل DTO بيانات العقد المعادة لا مخطط قاعدة. يمكن مراجعة الاختيارات دون خادم.
قد يرفض قيد المسار المرشح قبل المعالج، بينما يرفض المعالج المطابق صفحة تخالف المجال. حدد حالة وشكل كل فئة. لا تفترض أن كل طلب خاطئ يصل إلى الشيفرة نفسها أو يتحقق تلقائيا بصفة جسم.
app.MapGet("/reports/{id:int}",
([FromRoute] int id, [FromQuery] int page) =>
page < 1 ? Results.BadRequest("page must be positive") : Results.Ok(new { id, page }));
لم ينفذ مقتطف التطبيق، وهو يحتاج إلى تعليمات using المناسبة وكائن التطبيق وإعداد المضيف.
الربط تمثيل والتحقق معنى
قد يرفض الربط نصا لا يتحول لعدد أو JSON لا يفك، بينما يظل عدد مربوط مخالفا لشرط الصفحة الموجبة. افحص الشكل والحجم والوجود وعلاقات المجال قبل الأثر. تساعد nullable القصد الساكن ولا تستبدل فحص المدخل المعادي.
يعتمد التحقق التلقائي على الإصدار والتسجيل. لدعم Minimal APIs في 10 إعداد وعقد لا يخلطان بسلوك MVC ApiController. قد تنفذ مرشحات النقاط تحققا مشتركا، لكنها لا تعمل تلقائيا عند نداء المعالج مباشرة في اختبار وحدة.
يجعل كائن النتيجة قصد الاستجابة قابلا للفحص
تعرض TypedResults أنواعا ملموسة تفيد الاختبار والوصف. ينشئ البرنامج Ok ويفحص الحالة والقيمة في الذاكرة؛ ولا ينفذ التسلسل أوتسليم HTTP. يختلف DTO بحالة 200 عن نتيجة تحقق، مهما قصر التوقيعان.
استخدم مجموعة ضيقة موثقة من البدائل. تحفظ Results<T1,T2> الأنواع في توقيع المعالج، وتعطي IResult تجريدا مشتركا أقل تفصيلا. اختر وضوح المستهلك والوصف المولد بدلا من أشكال مجهولة غير مترابطة لكل فشل.
using System;
using Microsoft.AspNetCore.Http;
var result = TypedResults.Ok(new ReportDto(7, "ready"));
Console.WriteLine($"status={result.StatusCode} id={result.Value!.Id} state={result.Value.State}");
internal sealed record ReportDto(int Id, string State);
status=200 id=7 state=ready
يحوي كائن Ok حالة 200 وDTO اصطناعية؛ ولا يختبر التسلسل أو الربط.
مطابقة وصف الواجهة بسلوك التشغيل
تساعد أسماء النقاط ومجموعاتها ووسومها ووصف نتائجها وOpenAPI على فهم السطح، ولا تستبدل التحقق والتفويض. يجب أن يطابق وصف 401 و 403 و 409 التنفيذ، وألا تكشف الأمثلة سرا أو شخصا حقيقيا. افصل توليد الوصف من تنفيذ الطلب.
اختبر الصحيح والمصدر الناقص والخاطئ والطريقة والمجال والنتائج والخطأ عبر الطبقة المناسبة. يفيد اختبار النتيجة المباشر ولا يغطي الربط والوسيط. تظل النقطة الصغيرة محتاجة مالكا للإلغاء والحفظ والآثار التشغيلية.
الأخطاء الشائعة وإصلاحها
يفترض أن DTO المربوطة صالحة للحفظ.
- لماذا يحدث؟
- اختلط فك التسلسل بقواعد المجال.
- كيف تصلحه؟
- تحقق قبل الآثار وحول البيانات إلى المجال صراحة.
- كيف تتجنب تكراره؟
- اختبر قيما صحيحة شكلا لكنها تخالف المجال.
يتوقع اختبار المعالج تنفيذ مرشح نقطة النهاية.
- لماذا يحدث؟
- يتجاوز الاستدعاء المباشر مسار مرشحات الإطار.
- كيف تصلحه؟
- اختبر المرشح والخط منفصلين أو استخدم تكاملا معزولا مدعوما.
- كيف تتجنب تكراره؟
- صرح بالطبقة التي ينفذها كل اختبار.
تعد بيانات OpenAPI الوصفية بأخطاء لا يعيدها المعالج.
- لماذا يحدث؟
- اختلف عقد التوثيق عن عقد التنفيذ.
- كيف تصلحه؟
- طابق بدائل النتائج وتحقق من المسارات التي تعيدها.
- كيف تتجنب تكراره؟
- راجع البيانات الوصفية المولدة مع اختبارات السلوك.
اختبر فهمك
1. يقبل معالج المعامل page من النوع int ويعيد استعلام قاعدة فورا. ما الفحوص التي تظل مطلوبة؟
اعرض الحل المشروح
حدد افتراضي الصفحة إن غابت، ورفض الصفر والسالب والضخم، والحد الأعلى للحجم والترتيب والتفويض والإلغاء. لا يثبت نجاح الربط العددي شيئا منها. طبق قواعد مجال محدودة قبل الاستعلام واختبر الحالة وشكل الخطأ العام. اجعل ثبات الصفحات وكلفة المورد من العقد لا تفاصيل يؤجلها المعالج إلى المزود.
2. ماذا يثبت فحص TypedResults.Ok، وما الذي يظل خارج هذا الاختبار؟
اعرض الحل المشروح
يثبت الفحص حالة وقيمة النتيجة المنشأة. لا يثبت اختيار المسار أو الربط أو خيارات JSON أو تنفيذ الاستجابة أو المصادقة أو التفويض أو النقل. احتفظ بهذا التأكيد المفيد للوحدة وأضف التكامل المناسب للعقد العام بدلا من عد كائن النتيجة وحده تحقق النقطة.
أهم ما تعلمته
- مصدر المدخل وتمثيله والتحقق منه والآثار مراحل منفصلة.
- تحسن النتائج ذات الأنواع إمكان فحصها دون استبدال فحوص التكامل.
- يحتاج التحقق التلقائي المرتبط بإصدار معين إلى إعداد صريح ودليل.