ما هو تطوير واجهات برمجة التطبيقات بمنهجية المواصفات أولاً؟

معظم أخطاء واجهات برمجة التطبيقات (API) ليست أخطاء برمجية. إنها أخطاء في الاتفاق. كانت الواجهة الأمامية تتوقع userId، وأرسلت الواجهة الخلفية user_id، ولم يلاحظ أحد ذلك حتى مرحلة ضمان الجودة (QA). يعالج تطوير واجهات برمجة التطبيقات القائم على المواصفات أولاً هذا من خلال جعل العقد أول شيء تكتبه، وليس آخر شيء توثقه.

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

ماهو تطوير الـ API المعتمد على المواصفات أولاً

تطوير واجهات برمجة التطبيقات القائم على المواصفات أولاً يعني أنك تكتب عقدًا قابلاً للقراءة آليًا، وعادةً ما يكون وثيقة OpenAPI، قبل أن تقوم بتنفيذ نقطة النهاية (endpoint). يصف هذا العقد كل مسار ومعلمة وجسم طلب وشكل استجابة ورمز حالة. بمجرد وجوده، يصبح مصدر الحقيقة لكل من يتعامل مع واجهة برمجة التطبيقات.

المواصفات ليست وثائق تتأخر عن الكود. بل هي تقود. تبني فرق الواجهة الأمامية (frontend) بناءً على نموذج (mock) يتم إنشاؤه منها. يكتب قسم ضمان الجودة (QA) الاختبارات بناءً عليها. تقوم الواجهة الخلفية (backend) بالتنفيذ لتلبية متطلباتها. عندما تتفق الفرق الثلاثة على نفس الملف، يتوقف التكامل عن كونه لعبة تخمين.

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

دورة حياة التطوير القائم على المواصفات أولاً مقابل التطوير القائم على الكود أولاً

ينتج كلا النهجين نفس نقاط النهاية. لكنهما يختلفان في توقيت ظهور المشاكل ومن يمكنه البدء في العمل بالتوازي.

العمود الأيمن هو المكافأة. عندما يوجد العقد أولاً، تتوقف ثلاثة فرق عن إعاقة بعضها البعض وتبدأ في البناء بناءً على تعريف واحد مشترك.

مثال عملي على OpenAPI

دعنا نصمم نقطة نهاية صغيرة /users خطوة بخطوة. سنقوم ببنائها على أجزاء بحيث يكون كل جزء واضحًا، ثم نجمع الملف كاملاً.

ابدأ برأس الوثيقة. هذا يعلن عن إصدار OpenAPI والبيانات الوصفية الأساسية.

openapi: 3.0.3
info:
 title: Users API
 version: 1.0.0
servers:
 - url: https://api.example.com/v1

بعد ذلك، حدد مخطط User ضمن components. تحديدها مرة واحدة يتيح لك الرجوع إليها في كل مكان، بحيث يبقى الشكل متناسقًا عبر الطلبات والاستجابات.

components:
 schemas:
 User:
 type: object
 required: [id, email, createdAt]
 properties:
 id:
 type: string
 format: uuid
 email:
 type: string
 format: email
 name:
 type: string
 createdAt:
 type: string
 format: date-time

الآن أضف المسار GET /users. يقوم بسرد المستخدمين ويدعم معامل الاستعلام limit. لاحظ كيف تعيد الاستجابة استخدام مخطط User باستخدام $ref بدلاً من إعادة تعريفه.

paths:
 /users:
 get:
 summary: List users
 operationId: listUsers
 parameters:
 - name: limit
 in: query
 schema:
 type: integer
 default: 20
 maximum: 100
 responses:
 "200":
 description: A list of users
 content:
 application/json:
 schema:
 type: array
 items:
 $ref: "#/components/schemas/User"

أضف عملية POST /users لإنشاء مستخدم. يحدد نص الطلب ما يجب على العميل إرساله، وتعيد استجابة 201 السجل الذي تم إنشاؤه.

 post:
 summary: Create a user
 operationId: createUser
 requestBody:
 required: true
 content:
 application/json:
 schema:
 type: object
 required: [email]
 properties:
 email:
 type: string
 format: email
 name:
 type: string
 responses:
 "201":
 description: User created
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/User"
 "400":
 description: Invalid request body

هذا عقد كامل وصالح. يسمي كل حقل، ويحدد email كحقل مطلوب، ويضع حدًا أقصى لـ limit عند 100، ويعلن عن استجابات النجاح والخطأ. لم يكتب أحد سطرًا واحدًا من كود الخادم بعد، لكن الاتفاقية مؤمنة.

إنشاء النماذج والاختبارات والوثائق من المواصفات

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

النماذج (Mocks). يقوم خادم النماذج بقراءة مواصفاتك ويعيد استجابات أمثلة تتطابق مع كل مخطط. تتيح تلميحات format: uuid و format: email للأدوات إنشاء بيانات عينة واقعية. تستدعي واجهتك الأمامية GET /users وتحصل على مصفوفة مستخدمين منسقة جيدًا في اليوم الأول، قبل وقت طويل من وجود المعالج الحقيقي. عندما تتغير المواصفات، يتغير النموذج معها.

الاختبارات. نظرًا لأن المواصفات تعلن عن الحقول المطلوبة والأنواع وأكواد الحالة، فإنها تعمل أيضًا كـ "أوراكل" للاختبار. تؤكد اختبارات العقد أن الاستجابة الحقيقية لـ POST /users تعيد 201 مع نص يتطابق مع مخطط User، و 400 عندما يكون email مفقودًا. أنت لا تخترع التأكيدات. أنت تتحقق من أن التنفيذ يتطابق مع ما اتفقت عليه بالفعل.

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

هذا أيضًا ما يجعل التطوير القائم على المواصفات يتوافق جيدًا مع سير عمل واجهة برمجة التطبيقات الأصلي لـ Git: المواصفات هي ملف نص عادي، لذا يظهر كل تغيير في العقد كفرق قابل للمراجعة في طلب سحب (pull request). يمكن للمراجع أن يرى أن شخصًا ما أعاد تسمية email أو أسقط حقلاً مطلوبًا قبل الشحن.

القيام بذلك في Apidog

يدعم Apidog هذا من البداية إلى النهاية من خلال وضع المواصفات أولاً (Spec-First Mode). بدلاً من التعامل مع ملف OpenAPI كتصدير، فإنه يتعامل مع الملف كمشروع. تقوم بتحرير YAML مباشرة ويتبع باقي مساحة العمل.

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

الجزء الذي يحافظ على مصداقية هذا هو مزامنة Git ثنائية الاتجاه. تعيش مواصفاتك في مستودع، وتتدفق التغييرات في كلا الاتجاهين. قم بتحرير YAML في محرر النصوص الخاص بك وادفع التغييرات، وسيتلقاها Apidog. قم بالتحرير في Apidog، وستهبط التغييرات كتثبيت (commit) يمكن لفريقك مراجعته. لا يعيش العقد أبدًا في مكانين في وقت واحد. إذا كنت تريد مقارنة أعمق لموقع هذا النهج مقارنة بنهج التصميم أولاً البحت، فراجع المواصفات أولاً مقابل التصميم أولاً في Apidog.

قائمة مراجعة للنهج المعتمد على المواصفات أولاً

استخدم هذا قبل أن تعتبر المواصفات جاهزة للبناء عليها:

• تتحقق المواصفات مقابل مخطط OpenAPI بدون أخطاء.
• تعلن كل نقطة نهاية عن استجابتها الناجحة واستجابة خطأ واحدة على الأقل.
• تعيش الأشكال المشتركة في components/schemas ويتم الرجوع إليها باستخدام $ref، ولا يتم نسخها.
• يتم وضع علامة required على الحقول المطلوبة، ويتم تعيين التنسيقات (uuid، email، date-time) حيثما ينطبق.
• يتم تثبيت ملف المواصفات في نظام التحكم بالإصدار ومراجعته في طلبات السحب.
• يعمل خادم وهمي من المواصفات، ويمكن للواجهة الأمامية الوصول إليه.
• تتحقق اختبارات العقد من الاستجابات الحقيقية مقابل المخططات المعلنة.
• يتم عرض الوثائق المنشورة من نفس الملف، بدون نسخة يتم صيانتها يدويًا.

إذا تم التحقق من كل مربع، يمكن لفرقك البناء بالتوازي بناءً على اتفاق واحد بدلاً من ثلاثة تخمينات.

الأسئلة الشائعة

هل تطوير واجهة برمجة التطبيقات القائم على المواصفات أولاً هو نفسه التصميم أولاً؟

في الغالب نعم. تصف مصطلحات "التصميم أولاً" و"العقد أولاً" نفس المبدأ: اكتب الواجهة قبل التنفيذ. "المواصفات أولاً" هو الاسم الأكثر حرفية لأن ملف مواصفات OpenAPI هو المخرج الملموس الذي تبدأ به. عمليًا، تُستخدم المصطلحات بالتبادل.

هل يجب علي كتابة YAML يدويًا؟

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

كيف أمنع المواصفات والكود من التباعد؟

اجعل المواصفات هي مصدر الحقيقة وفرضها. احتفظ بالمواصفات في Git بحيث تتم مراجعة التغييرات كـ "فروقات" (diffs). قم بتشغيل اختبارات العقد في التكامل المستمر (CI) بحيث يفشل البناء عندما تتوقف الاستجابة عن مطابقة المخطط. مع المزامنة ثنائية الاتجاه، تبقى التعديلات في أي من المكانين متوافقة، مما يزيل السبب الأكثر شيوعًا للتباين.

تطوير واجهة برمجة التطبيقات القائم على المواصفات أولاً هو تغيير صغير في الترتيب مع تغيير كبير في النتيجة. اكتب العقد، وافق عليه، ثم ابنِ عليه. إذا كنت ترغب في تجربة الدورة الكاملة، افتح وضع المواصفات أولاً (Spec-First Mode) في Apidog ووجهه إلى مستودعك.