محاكي صفحات API يكشف التكرار والسجلات المفقودة: مشاريع تخرج هندسة البرمجيات

يقرأ طالب صفحة من قائمة طلبات، ثم يضيف سجلاً جديداً قبل أن يفتح الصفحة التالية. إذا كان الاستعلام يستخدم offset وترتيباً قابلاً للتغير، قد يظهر عنصر مرة ثانية أو يختفي من مسار التصفح. هذا المشروع يعطي مشاريع تخرج هندسة البرمجيات واجهة تشغل القائمة بثلاث سياسات ترقيم، ثم تحقن تغييرات محددة بين الطلبات. توصي AIP-158 بوجود pagination منذ البداية وتشرح استخدام page token، بينما توضح وثائق Calendar API أن الصفحة قد تعيد أقل من الحد الأقصى وأن وجود nextPageToken هو إشارة استمرار. وجود token بحد ذاته لا يعني أن الخادم احتفظ بلقطة ثابتة للمجموعة.

اكتب ترتيباً لا يتغير عشوائياً

ابدأ بجدول سجلات اصطناعي يحوي createdAt وid وقيمة مرئية. استخدم ترتيباً مركباً مثل createdAt تنازلياً ثم id تنازلياً لتصبح المفاتيح فريدة. اختبر الحالة نفسها بترتيب createdAt وحده؛ عند تساوي التواريخ قد يعيد المحرك سجلات بأي ترتيب مسموح. المبدأ مهم سواء كان المؤشر offset أو cursor: الصفحة التالية تستند إلى ترتيب حتمي. وثق أن أسلوب الاستعلام والفهرس جزء من التنفيذ وليس خاصية تلقائية للتوكن.

حقن تعديلات بين الطلبات

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

جرب مؤشراً مبنياً على آخر مفتاح

في مسار cursor، خزن آخر زوج مرتب شوهد وأرسل token مع الطلب التالي، أو استخدم token معتماً يصدره الخادم. عند متابعة الصفحة، اطلب السجلات التي تقع بعد المفتاح وفق الاتجاه المحدد. أضف إدخالاً جديداً قبل آخر عنصر مقروء وآخر بعده، وراقب أيهما يظهر. اشرح الفارق بين استمرار ترتيب المفتاح وبين ضمان snapshot: المؤشر قد يمنع انزلاق offset، لكنه لا يضمن أن العميل شاهد حالة واحدة ثابتة طوال الرحلة. إذا كان ذلك مطلوباً، يحتاج التصميم إلى حد زمني أو معرّف snapshot يصدره الخادم.

جدول تحقق لخمسة عناصر

افترض أن الترتيب الابتدائي A,B,C,D,E وحجم الصفحة 2. أعادت الصفحة الأولى A,B. أضف X قبل A. قد يبدأ offset 2 عند B ويكرره، بينما cursor بعد B يبدأ من C إذا لم يغير الإدراج المفاتيح السابقة. ثم احذف C قبل الطلب التالي: لن يظهر C، لكن ذلك يعكس تغير المجموعة وليس عيباً حسابياً بحد ذاته. يسجل المختبر ما شاهده المستخدم وما كان موجوداً في كل لحظة. عرّف معيار القبول: هل تنقل المجموعة كما رآها الخادم عند كل طلب، أم تعرض snapshot محدداً؟ لا تستخدم عبارة «لا توجد سجلات مفقودة» دون تحديد زمن الرؤية.

تحقق من عقد الطلب

اختبر أن next token الغائب ينهي المسار، وأن token من استعلام بفلاتر مختلفة لا يقبل مع فلتر جديد إلا إذا نص العقد على ذلك. تشترط AIP-158 ثبات بقية معلمات الطلب، وتسمح بأن تكون الصفحة أقصر من requested size. أضف token منتهي الصلاحية أو تالفاً، وحجم صفحة صفرياً أو سالباً وفق عقد API. لا تكشف token يحوي بيانات حساسة مباشرة؛ اجعله معتماً أو محمياً حسب السياق. هذه اختبارات عقد محلية، ولا تدعي تطابق كل التفاصيل بين مزود وآخر.

كيف تعرض النتيجة بلا رقم مضلل؟

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

مخرجات وحدود النسخة

يسلم الطالب محاكي API وملف seed وسياسات offset وcursor وtrace لكل طلب ومصفوفة قبول تبين الافتراضات. يجب ألا يسمي cursor ضماناً شاملاً لثبات القراءة إن كان يخزن مجرد آخر مفتاح. وكذلك nextPageToken وسيلة متابعة لا وصفاً كاملاً لاتساق المعاملة. يناسب الموضوع مشاريع التخرج في هندسة البرمجيات وقواعد البيانات، ويمكن وصل الواجهة بخدمة تطوير قواعد البيانات وواجهات البرمجة. إذا احتاج النظام إلى رؤية ثابتة عبر صفحات عدة، اجعل snapshot متطلباً صريحاً واختبر دورة حياتها بدلاً من الاعتماد على اسم cursor وحده.