تطوير واجهات Laravel البرمجية

الواجهة البرمجية وعد لشخص ليس في الغرفة. وهذا هو الفارق كله بين بنائها وبناء بقية التطبيق: شاشاتك يمكن أن تتغير مع الشيفرة التي وراءها، والمستهلك لا يمكنه.

أغلب واجهات Laravel التي يُطلب منا إصلاحها بُنيت كأن ذلك غير صحيح.

العقد يُولَّد، لا يُوصَف

المواصفة المكتوبة يدويًا في صفحة ويكي تصبح قديمة خلال دورتين، وأول من يكتشف ذلك مستهلك بنى عليها.

فليأتِ العقد من الشيفرة: موارد بأنواع، وتحقق من الطلبات تُشتق منه المواصفة، ووثيقة OpenAPI مولَّدة تُنشر كجزء من البناء. تغيير شكل استجابة يغيّر الوثيقة في طلب الدمج نفسه. ولا يمكن أن تكون خاطئة إلا إذا كانت الشيفرة خاطئة.

الموارد صريحة لا نموذج يُسلَّم إلى toJson(). إعادة نموذج مباشرة تعني أن عمودًا أُضيف لسبب داخلي صار جزءًا من العقد العام يوم إضافته - وحذفه لاحقًا تغيير كاسر لم تقصد إحداثه أبدًا.

الإصدارات، تُقرَّر قبل الحاجة إليها

الإصدار الأول مجاني والثاني ليس كذلك، فالقرار الجدير بالتبكير هو أين يعيش الإصدار وما الذي يُعدّ كسرًا.

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

ما نضعه سياسة: التغييرات الإضافية تصدر باستمرار، والكاسرة تحصل على إصدار جديد، ويعمل الإصداران بالتوازي مدة متفقًا عليها، ويُبلَّغ المستهلكون بدل أن يكتشفوا.

مصادقة بمالك واحد

Sanctum للعملاء الخاصين بك، وPassport حيث يلزم OAuth2 فعلًا، وفي الحالتين مكان واحد يقرر ما يستطيع الرمز فعله.

العطل الذي نجده هو التكرار: صلاحية تُفحص في policy لمسارات الويب ويُعاد تنفيذها في middleware لمسارات الواجهة البرمجية، فتتباعدان حتى تصير إحداهما خاطئة. التخويل ينتمي إلى policies يستدعيها المدخلان، وتؤكد اختبارات الواجهة الحالات السلبية - ليس أن الشخص الصحيح يستطيع قراءة السجل، بل أن الخطأ لا يستطيع.

تحديد المعدل لكل مستهلك لا لكل عنوان IP، لأن التحديد بالعنوان يعاقب مكتبًا ويُفلت برنامجًا نصيًا. والقدرات محصورة بما وُجد الرمز لأجله، حتى لا يكون رمز جوال مسرَّب رمزَ مدير.

الأجزاء التي تنكسر مع بيانات حقيقية

تقسيم الصفحات. التقسيم بالإزاحة جيد حتى الصفحة أربعمئة، وعندها تقرأ قاعدة البيانات أربعمئة صفحة وترميها لتعطيك واحدة. استخدم تقسيمًا بالمؤشر لكل ما ينمو، ويُقرَّر ذلك وقت التصميم لأن تغييره لاحقًا تغيير كاسر.

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

التضمينات. السماح للمستهلك بطلب علاقات متداخلة ميزة جيدة ومولّد N+1. تحميل مسبق يقوده المطلوب تضمينه، مع حدّ للعمق، وإلا تحولت الراحة إلى انقطاع.

الأخطاء. شكل واحد، موثَّق، برمز يقرؤه الحاسوب لا يتغير حين تتغير الرسالة التي يقرؤها الإنسان. المستهلك الذي يحلّل نصوص أخطائك مستهلك ستكسره بتحسين صياغتك.

كيف يجري التعاقد

تبدأ من المستهلكين. أرسلوا لنا من يستدعي هذه الواجهة، وماذا يفعل بها، والنقطة التي سببت أكثر تذاكر الدعم. هذا يكفي عادةً لتقدير الحجم.

ما يعود إليكم نطاق مكتوب: قائمة النقاط، وقرار الاستيثاق، وسياسة الإصدارات، وما يدخل المرحلة الأولى مقابل ما يُستبعَد عمدًا. يحمل سعرًا وهو الوثيقة التي يشير إليها العقد، فيكون ما توقّعون عليه هو نفسه ما نبنيه.

ثم العمل، في مستودعكم وضمن عملية المراجعة لديكم. والمواصفة تُولَّد وتُنشر من المرحلة الأولى، فيقرؤها مستهلكوكم والواجهة لا تزال قيد البناء.

ماذا تتسلّم

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

وحيث تُضاف الواجهة إلى تطبيق قائم، تتسلّم أيضًا ما يكشفه ذلك العمل عادةً: قائمة بقواعد عمل كانت تعيش في المتحكمات، وأين تعيش الآن كي يتفق المدخلان.

Sanctum أو Passport يحدد كيف يستوثق المستهلكون، وحسمه أسهل كثيرًا من تغييره لاحقًا. والسؤال الأصعب تحته هو هل Laravel أصلًا بيئة التشغيل المناسبة لهذه الواجهة. وإن كانت مهمة الواجهة أساسًا التحدث إلى واجهة غيرك، فالتكامل أنسب.