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

ASP.NET Core / المتقدم: التحقق والتشغيل الموثوق / الدرس 18

تطور API وحدود التطبيق

احفظ عقود المدخلات والمخرجات والأخطاء والتفويض والترقيم والعمر العامة أثناء تغيير التنفيذ الداخلي.

وقت القراءة التقريبي: 5 دقيقةتاريخ مراجعة المحتوى
في هذه الصفحة

أهداف الدرس

  • راجع التوافق بما يتجاوز تواقيع الطرائق.
  • صمم تسلسل DTO مستقرا وترقيما محدودا.
  • اجعل قرارات المعمارية وأدلة التحقق قابلة للمراجعة.

يشمل توافق HTTP السلوك ومعنى البيانات

تعرف API مستقرة الطرق والمسارات والحالات وأسماء الحقول وأنواعها ومعنى null والوجود والترتيب وفئات الأخطاء والتفويض ومنع تكرار الأثر وآثار الإلغاء. قد يترجم معالج دون تغيير بينما يكسر خيار تسلسل أو تعديل سياسة العملاء. افصل DTO للطلب والرد من كيانات الحفظ حين تختلف دورات حياتها.

يمكن أن تستخدم استراتيجية الإصدارات مسارا أو ترويسة أو نوع وسائط أو اتفاقية مراجعة أخرى، لكن العملاء يحتاجون عقد ترحيل وإيقاف دعم. ليست إضافة مدخل مطلوب أو تغيير تمثيل عددي أو enum متوافقة تلقائيا. لا تعد بأن التسامح مع الحقول المجهولة يجعل كل تغيير خادم مستقبلي آمنا.

اختبر التمثيل العام المقصود صراحة

يسلسل البرنامج الكامل الأول DTO رد اصطناعية باستخدام JsonSerializerDefaults.Web. يتحقق محليا من أسماء الحقول الناتجة بصيغة camel-case وقيمها. لا يثبت أن التطبيق اختار خيارات JSON نفسها أو تفاوض على نوع المحتوى أو أعاد DTO عبر نقطته. تحتاج هذه الادعاءات إلى مسار HTTP المهيأ.

قد يؤثر تغيير سياسة الأسماء أو محولات enum أو معالجة الأعداد أو تنسيقات التواريخ أو سلوك المطلوب وnull في العملاء. احتفظ بأمثلة بروتوكول ثابتة واختبر الحقول المتوقعة والبيانات الحساسة الغائبة عمدا معا. قد يحوي كائن المجال حقولا داخلية ينبغي ألا تصبح عامة لمجرد أن التسلسل الافتراضي يجدها.

csharp فحص تمثيل DTO اصطناعية بافتراضيات الويب
using System;
using System.Text.Json;

var options = new JsonSerializerOptions(JsonSerializerDefaults.Web);
string json = JsonSerializer.Serialize(new ReportResponse(7, "ready"), options);
if (json != "{\"id\":7,\"state\":\"ready\"}") throw new InvalidOperationException("representation changed");
Console.WriteLine(json);

internal sealed record ReportResponse(int Id, string State);
الناتج المتوقع
{"id":7,"state":"ready"}

يخرج المسلسل المحلي id وstate؛ ولا ينفذ ذلك رد ASP.NET.

يحتاج الترقيم إلى ترتيب مستقر واستمرار محدود

يستخدم البرنامج الثاني معرفات صحيحة فريدة ومؤشرا وحجم صفحة اثنين ونظرة مسبقة بعنصر واحد لمعرفة وجود بيانات أخرى. هو مثال تسلسل محلي، لا اختبار أداء استعلام EF أو اتساق معاملة. في مجموعة حقيقية، تحتاج مفاتيح الفرز غير الفريدة إلى فاصل تعادل وحقول مؤشر تحفظ الترتيب كاملا.

يلبي ترقيم الإزاحة وترقيم مجموعة المفاتيح احتياجات تشغيلية مختلفة ويختلفان في سلوك التغيير والتزامن. حد أحجام الصفحات وتحقق من شكل المؤشر وقيد البيانات بالتفويض وحدد دلالات اللقطة أو البيانات الحية. لا يصبح المؤشر رمز تفويض لمجرد إبهامه. تجنب كشف أسرار داخلية عبر مؤشر مسلسَل.

csharp فحص ترقيم مؤشر محلي محدود
using System;
using System.Linq;

int after = 2, pageSize = 2;
int[] candidates = Enumerable.Range(1, 6).Where(id => id > after).OrderBy(id => id).Take(pageSize + 1).ToArray();
int[] page = candidates.Take(pageSize).ToArray();
bool hasMore = candidates.Length > pageSize;
int? next = hasMore ? page[^1] : null;
Console.WriteLine($"ids={string.Join(",", page)} hasMore={hasMore} next={next}");
الناتج المتوقع
ids=3,4 hasMore=True next=4

تتكون الصفحة من 3 و 4، وتجد النظرة المسبقة بيانات إضافية، فيكون مؤشر المتابعة 4.

أظهر مسؤوليات HTTP والتطبيق والمجال والبنية التحتية

تترجم النقاط والمتحكمات HTTP، وتنسق عمليات التطبيق حالات الاستخدام، وتحمي قواعد المجال الثوابت، وتنفذ البنية التحتية سلوك المزوّد والشبكة والتخزين. ينبغي أن تلائم البنية الدقيقة التطبيق لا تنسخ ترتيب مجلدات رائجا. تسهل الاعتماديات الضيقة والملكية الواضحة الاختبار ومراجعة التغيير.

لا توفر واجهة تلقائيا سلامة معاملات أو تفويضا أو أداء. قد يسرب مستودع يعيد IQueryable غير محدودة هموم المزوّد والعمر إلى كل مستدع. قرر موضع المدخل الموثوق والبيانات المستعارة أو المنسوخة وحد التزام الآثار. احفظ هذه العقود عند استبدال التنفيذ.

يربط قرار الإصدار الدليل بوعد عام

سجل السبب والبدائل وأثر التوافق وترتيب الترحيل والنشر والاختبارات وإشارات التشغيل وشروط التراجع أو التصحيح بإصدار لاحق. قد يحتاج مخطط أو سياسة تخزين أو ربط مطالبات مصادقة أو خيار JSON جديد إلى تنسيق وإن بقيت تواقيع الطرائق كما هي. تحقق من دعم التشغيل والحزم الفعلي مقابل الأساس الصريح، لا إعداد أحدث أو معاينة.

اذكر الفحوص المنفذة وما بقي خارج النطاق. يتحقق المقرر من مكونات إطار محلية آمنة وحسابات اصطناعية فقط؛ ولا يبدأ تطبيق قائم مهيأ أو TestServer أو قاعدة مهيأة أو وكيلا أو سحابة أو نشرا. تظهر المعمارية القابلة للصيانة تلك الحدود التي لم تختبر، حتى يثبتها عمل لاحق مأذون بدلا من افتراضها.

الأخطاء الشائعة وإصلاحها

يتغير إعداد مسلسل دون مراجعة API.

لماذا يحدث؟
عُد الإعداد الداخلي سلوكا غير ملحوظ.
كيف تصلحه؟
اختبر التمثيل العام وأثر الترحيل.
كيف تتجنب تكراره؟
احتفظ بأمثلة DTO ثابتة وعقود للأخطاء.

ينتج مفتاح فرز غير فريد صفحات غير مستقرة.

لماذا يحدث؟
لا يرمز المؤشر الترتيب كاملا.
كيف تصلحه؟
أضف فاصل تعادل مستقرا وحدد دلالات التغيير المتزامن.
كيف تتجنب تكراره؟
اختبر قيم فرز متساوية وسجلات الحدود.

تخفي واجهة معادة استعلام مزوّد مؤجلا وغير محدود.

لماذا يحدث؟
خرجت هموم العمر وكلفة الموارد من حد العملية.
كيف تصلحه؟
اكشف عقود تطبيق محدودة موثقة التنفيذ.
كيف تتجنب تكراره؟
راجع الملكية وتسرب تفاصيل المزوّد.

اختبر فهمك

1. لماذا قد تكسر إضافة حقل طلب مطلوب لا يقبل null العملاء الموجودين رغم ترجمة الخادم بنجاح؟

اعرض الحل المشروح

قد يغفل العملاء القدامى الحقل، فيحدث فشل ربط أو تحقق أو تستخدم قيمة افتراضية تغير معنى المجال. راجع دلالات الوجود وnull والافتراضيات والإصدارات والتوثيق والترحيل. عند التحقق من التوافق، اختبر الحمولات القديمة والجديدة عبر مسار الطلب الحقيقي. لا تصف أنواع الخادم وقت الترجمة ما يرسله عملاء منشورون بالفعل.

2. ما الفحوص الإضافية اللازمة قبل تحويل مثال الترقيم المحلي إلى نقطة EF؟

اعرض الحل المشروح

تحقق من ترجمة المزوّد والفهارس وكلفة الاستعلام ونطاق التفويض والمستأجر والترتيب المستقر الفريد والتحقق من المؤشر والإلغاء وحدود الحجم ودلالات تغير البيانات والعزل. تثبت النظرة المسبقة في الذاكرة حساب التسلسل المحلي فقط. افصل دليل القاعدة من HTTP المستضاف، وتجنب إعادة IQueryable غير مقيدة إلى الطبقة المواجهة للعميل.

أهم ما تعلمته

  • يشمل التوافق التمثيل والحالة والتفويض والترتيب والآثار.
  • تجعل عقود DTO والترقيم المحدودة سلوك المزوّد قابلا للمراجعة.
  • يجب ألا تدعي المعمارية وسجلات الإصدار تحققا لم يحدث.

المراجع الرسمية