ملخص سريع
يعني نهج "التصميم أولاً" أن مواصفات واجهة برمجة التطبيقات (API) الخاصة بك تُكتب قبل رمز التنفيذ الخاص بك – وأن المواصفات هي المحرك لكل ما يتبع ذلك: النماذج الوهمية (mocks)، والتوثيق، والاختبارات، ومقاطع العملاء (client stubs). يزيل اختيار منصة تدعم سير العمل هذا من البداية إلى النهاية الاحتكاك المستمر المتمثل في الحفاظ على تزامن الكود والوثائق. تشرح هذه المقالة نهج "التصميم أولاً" وتقيّم شكل الأدوات الجيدة، مع Apidog كمنصة كاملة تعتمد "التصميم أولاً".
Apidogجرّب Apidog مجانًا
مقدمة
يتعلم معظم المطورين بناء واجهات برمجة التطبيقات (APIs) باستخدام نهج "الكود أولاً". تكتب مسارًا، وتضيف بعض التعليقات التوضيحية، وتشغل مولّدًا، وتحصل على التوثيق. يعمل الأمر. حتى يتوقف عن العمل.
تنجرف الوثائق. تصبح التعليقات التوضيحية قديمة. يغيّر مهندس جديد تنسيق الاستجابة ولكنه ينسى تحديث الديكور. بعد ستة أشهر، تقول الوثائق إن واجهة برمجة التطبيقات تُرجع مصفوفة من السلاسل، بينما الاستجابة الفعلية تُرجع مصفوفة من الكائنات تحتوي على حقل value.
يعكس نهج "التصميم أولاً" هذا الوضع. المواصفات هي مصدر الحقيقة. يشتق الكود والوثائق والنماذج الوهمية جميعها منها. عندما تتغير المواصفات، يتغير كل شيء معًا – لأن كل شيء تم إنشاؤه منها.
هذا ليس تمييزًا نظريًا. الفرق التي تعتمد نهج "التصميم أولاً" تُبلغ عن مفاجآت تكامل أقل، وتطوير واجهة أمامية أسرع (لأن النماذج الوهمية متاحة من اليوم الأول)، وتوثيق دقيق لأنه لم يكن أبدًا مخرجات ثانوية.
لكن "التصميم أولاً" يتطلب أدوات تجعل كتابة المواصفات سريعة بما يكفي لتكون عملية. إذا استغرق تحديد نقطة نهاية في أداة المواصفات 20 دقيقة وكتابة معالج المسار 5 دقائق، فلن يستخدم أحد أداة المواصفات. يجب أن تجعل المنصة نهج "التصميم أولاً" أسرع من "الكود أولاً"، وليس أبطأ.
ماذا يعني "التصميم أولاً" عمليًا
"التصميم أولاً" هو سير عمل، وليس تقنية. إليك كيف يبدو في كل مرحلة من مراحل تطوير واجهة برمجة التطبيقات:
قبل كتابة أي كود
يُعرّف تصميم واجهة برمجة التطبيقات (API) كمواصفات OpenAPI. يشمل ذلك:
- جميع مسارات نقاط النهاية وطرق HTTP
- تعريفات معلمات الطلب (المسار، الاستعلام، الرأس)
- مخططات نص الطلب لنقاط نهاية POST/PUT/PATCH
- مخططات الاستجابة لجميع رموز الحالة (200، 400، 401، 422، 500)
- متطلبات المصادقة
- أوصاف الحقول والأمثلة
تتم معظم القرارات الهامة في مراجعة التصميم هذه: التسمية، وهياكل البيانات، وأنماط معالجة الأخطاء.
أثناء التطوير
تُنشر المواصفات على خادم وهمي (mock server). يبني مهندسو الواجهة الأمامية بناءً على هذا النموذج الوهمي. وينفذ مهندسو الواجهة الخلفية بناءً على المواصفات، معتبرين إياها وثيقة متطلباتهم. يعمل كلا الفريقين بالتوازي دون حجب بعضهما البعض.
بعد التنفيذ
تتحقق الاختبارات الآلية من أن التنفيذ الفعلي يطابق المواصفات. أي انحراف عن العقد يؤدي إلى فشل الاختبار.
عندما تتغير المتطلبات
تُحدّث المواصفات أولاً. يراجع كلا الفريقين التغيير. تُحدّث النماذج الوهمية تلقائيًا. وتُشير الاختبارات إلى أي تنفيذ لا يتبع المواصفات المحدثة.
ما تحتاجه منصة "التصميم أولاً"
ليست كل أدوات واجهة برمجة التطبيقات تدعم سير عمل "التصميم أولاً". إليك ما يفرق بين الأدوات التي تدعمها وتلك التي لا تدعمها.
محرر واجهة برمجة تطبيقات مرئي
تُعد YAML الخام وسيط تصميم ضعيفًا. يسمح لك المحرر المرئي بالتركيز على بنية واجهة برمجة التطبيقات ودلالاتها دون صراع مع مسافات بادئة YAML. يجب أن يُنشئ المحرر OpenAPI صالحًا، ويدعم إعادة استخدام المخططات (المكونات)، ويتحقق من الصحة في الوقت الفعلي.
التحقق من صحة OpenAPI
يجب أن تكون المواصفات صالحة كـ OpenAPI قبل استخدامها لأي شيء. يلتقط التحقق المضمن الأخطاء أثناء التحرير بدلاً من وقت إنشاء الكود أو إنشاء النموذج الوهمي.
توليد نماذج وهمية تلقائيًا من المواصفات
اكتب المواصفات، واحصل على نموذج وهمي. لا توجد خطوات إضافية. يجب أن يُرجع النموذج الوهمي بيانات تحترم أنواع الحقول وتنسيقاتها وقيودها من المخطط. هذا ما يجعل التطوير المتوازي عمليًا.
معاينة التوثيق مع أمثلة واقعية
يجب أن تُعرض المواصفات في توثيق قابل للقراءة يمكنك مشاركته مع أصحاب المصلحة خلال مرحلة التصميم. يجب أن يتمكن أعضاء الفريق غير التقنيين من قراءتها وتقديم الملاحظات.
سير عمل مراجعة الفريق
يتعامل نهج "التصميم أولاً" مع تغييرات المواصفات مثل تغييرات الكود: يقترح شخص تغييرًا، يراجعه الآخرون، ثم تتم الموافقة عليه أو تنقيحه. تحتاج المنصة إلى تعليقات غير متزامنة وتتبع التغييرات.
التصدير إلى OpenAPI القياسية
يجب أن تكون المواصفات قابلة للنقل. يجب أن تكون قادرًا على تصديرها إلى OpenAPI القياسية واستخدامها مع أي أداة لاحقة: مولّدات الكود، بوابات واجهة برمجة التطبيقات، أطر عمل الاختبار.
Apidog كمنصة تعتمد "التصميم أولاً"
تم بناء بنية Apidog حول المواصفات كأثر أساسي. علامة تبويب التصميم، وخادم النماذج الوهمية، ومشغّل الاختبار، والتوثيق كلها متصلة بنفس تعريف واجهة برمجة التطبيقات الأساسي.
محرر OpenAPI المرئي
تستخدم واجهة تصميم Apidog التحرير القائم على النماذج. كل نقطة نهاية هي نموذج منظم: المسار، الطريقة، المعلمات، نص الطلب، الاستجابات. تُعرّف حقول المخطط باستخدام أداة اختيار النوع، ومحرر الوصف، وقواعد التحقق، وتعليق النموذج الوهمي.
ليس عليك كتابة YAML إلا إذا أردت ذلك. يوفر Apidog عرضًا خامًا يُظهر تمثيل YAML أو JSON للمواصفات ويسمح لك بتحريرها مباشرة إذا كنت تفضل ذلك. تتزامن التغييرات في العرض المرئي مع العرض الخام والعكس صحيح.
تُعد مكونات المخطط (Schema components) من الدرجة الأولى. قم بتعريف مخطط UserProfile في قسم المكونات. أشر إليه باستخدام $ref في أي نقطة نهاية. غيّر المخطط مرة واحدة، وستعكس كل نقطة نهاية تشير إليه هذا التغيير.
معاينة التوثيق في الوقت الفعلي
بينما تصمم نقطة نهاية، يتم تحديث عرض التوثيق في الوقت الفعلي. يمكنك معاينة كيف ستظهر نقطة النهاية في التوثيق المنشور دون مغادرة واجهة التصميم. تعرض المعاينة أوصافًا معروضة، وجداول مخططات بأنواع الحقول وقيودها، وأمثلة على الاستجابات.
شارك رابط التوثيق مع مديري المنتجات أو قادة الواجهة الأمامية خلال مرحلة التصميم للمراجعة. لا يحتاجون إلى تثبيت أي شيء.
النماذج الوهمية الذكية: من المواصفات إلى النموذج الوهمي العامل
عند حفظ نقطة نهاية جديدة في مصمم Apidog، يكون خادم النموذج الوهمي جاهزًا على الفور. يظهر عنوان URL للنموذج الوهمي في الواجهة. يُنشئ النموذج الوهمي بيانات استجابة بناءً على مخططاتك:
- تعيد حقول السلسلة التي تحتوي على
format: emailعناوين بريد إلكتروني صالحة - تعيد حقول الأعداد الصحيحة التي تحتوي على
minimumوmaximumقيمًا ضمن النطاق - تعيد حقول التعداد (Enum) قيم تعداد مختارة عشوائيًا
- تتبع الكائنات والمصفوفات المتداخلة بنية المخطط المتداخل
- يتم حل المكونات ذات
$refومحاكاتها بشكل صحيح
يمكنك أيضًا تعيين قواعد نماذج وهمية مخصصة لسيناريوهات معينة: إرجاع 404 عندما يكون معامل المسار 0، أو إرجاع حمولة محددة لقيمة معامل استعلام محددة.
مراجعة الفريق وتتبع التغييرات
تكون تغييرات مواصفات واجهة برمجة التطبيقات (API) في Apidog مرئية لجميع أعضاء مساحة العمل. يمكن إضافة التعليقات إلى نقاط نهاية أو حقول محددة. يتتبع سجل التغييرات من قام بتغيير ماذا ومتى.
بالنسبة لسير عمل "التصميم أولاً"، هذا يعني أن تغييرات المواصفات تمر بنفس ثقافة المراجعة لتغييرات الكود، دون الحاجة إلى أداة أو عملية منفصلة.
"التصميم أولاً" مقابل "الكود أولاً": المقايضات الفعلية
"التصميم أولاً" ليس متفوقًا عالميًا. إليك مقارنة صادقة.
مزايا "التصميم أولاً":
- يمكن للواجهة الأمامية والخلفية العمل بالتوازي (فائدة كبيرة في السرعة)
- التوثيق دقيق لأنه المصدر، وليس مشتقًا
- تظهر مشاكل التكامل مبكرًا، أثناء مراجعة التصميم، وليس متأخرًا، أثناء التكامل
- عقود واجهة برمجة التطبيقات صريحة وقابلة للتحقق
- تمر تغييرات واجهة برمجة التطبيقات بعملية مراجعة افتراضيًا
عيوب "التصميم أولاً":
- وقت مبدئي لتعريف المواصفات قبل كتابة الكود
- أدوات المواصفات تتطلب منحنى تعلم
- تتطلب الانضباط للحفاظ على تزامن التنفيذ مع المواصفات
- الإفراط في تحديد المواصفات مبكرًا يمكن أن يقيدك بقرارات قبل فهمك للمجال
مزايا "الكود أولاً":
- تطوير أولي أسرع للمشاريع الصغيرة والتجريبية
- عملية أقل للمطورين الفرديين الذين يكررون بسرعة
- لا توجد أداة مواصفات لتعلمها
عيوب "الكود أولاً":
- التوثيق دائمًا مخرج ثانوي ويميل إلى الانجراف
- يجب على الواجهة الأمامية انتظار الواجهة الخلفية قبل أن يبدأ عمل التكامل
- العقد ضمني، مما يجعل التغييرات المدمرة أصعب في الكشف عنها
- إعادة هيكلة واجهات برمجة التطبيقات تتطلب تحديثات يدوية للتوثيق
بالنسبة للفرق التي تضم أكثر من مهندس يعمل على واجهة برمجة تطبيقات، عادةً ما يحقق نهج "التصميم أولاً" نتائج أفضل. يؤتي الانضباط القائم على المواصفات ثماره بشكل أكبر في الميزات التي تتطلب تنسيقًا كبيرًا بين الواجهة الأمامية والخلفية.
أدوات تدعم سير عمل "التصميم أولاً"
Apidog
منصة كاملة تعتمد "التصميم أولاً": محرر مرئي، نماذج وهمية فورية، توثيق، اختبار، ومراجعة فريق في أداة واحدة. تغطي الطبقة المجانية مجموعة الميزات الكاملة. يعد توليد النماذج الوهمية القوي ميزة تنافسية حقيقية.
Stoplight Studio
محرر OpenAPI الأفضل في فئته مع تدقيق Spectral لفرض النمط. لا يوجد خادم نماذج وهمية مدمج أو مشغّل اختبار. الأفضل للمؤسسات التي تحتاج إلى أدوات حوكمة. مكلف للفرق الصغيرة.
SwaggerHub
منصة تحرير وتعاون OpenAPI ناضجة. مستخدمة على نطاق واسع في الشركات. قدرة محدودة على النماذج الوهمية. لا يوجد اختبار. جيدة للمؤسسات التي تعتمد بشكل كبير على المواصفات والموجودة بالفعل في نظام Swagger البيئي.
Postman (مع API Builder)
يحتوي Postman على علامة تبويب لتصميم واجهة برمجة التطبيقات تُنشئ مواصفات OpenAPI، لكن سير عمل التصميم والمجموعات يبدو غير متصل. يتطلب خادم النموذج الوهمي إعدادًا يدويًا من المجموعات بدلاً من التوليد التلقائي من المواصفات. يناسب فرق "الكود أولاً" التي ترغب في بعض أدوات التوثيق.
Insomnia (مع وضع المستند)
يدعم Insomnia تحرير مواصفات OpenAPI ويوفر نموذجًا وهميًا أساسيًا. أقل صقلًا من أدوات "التصميم أولاً" المخصصة. جيد للمطورين الفرديين الذين يرغبون في خيار خفيف الوزن.
إعداد سير عمل "التصميم أولاً" في Apidog
الخطوة 1: ابدأ بالمواصفات، وليس بالمجموعة أنشئ مشروعًا جديدًا وافتح علامة تبويب التصميم. قاوم الرغبة في البدء في منشئ الطلبات. حدد على الأقل مسار نقطة النهاية، والطريقة، ومخطط الاستجابة قبل إرسال طلب واحد.
الخطوة 2: حدد المكونات المشتركة أولاً قبل إضافة نقاط النهاية، حدد المخططات التي ستتم إعادة استخدامها: تنسيق استجابة الخطأ، وغلاف الترقيم (pagination wrapper)، وحقول الكيانات المشتركة. هذا يمنع عدم الاتساق لاحقًا.
الخطوة 3: احصل على عنوان URL للنموذج الوهمي مبكرًا انسخ عنوان URL للنموذج الوهمي فور حفظ نقطة النهاية. شاركه مع مهندس الواجهة الأمامية. يمكنهم البدء في البناء بناءً عليه فورًا.
الخطوة 4: راجع الوثائق قبل كتابة الكود عاين التوثيق المُنشأ. إذا كان وصف حقل غير واضح في الوثائق، فسيكون غير واضح للجميع الذين يقرؤون الكود. قم بإصلاحه في المواصفات.
الخطوة 5: قفل المواصفات قبل بدء التنفيذ بمجرد الانتهاء من مراجعة التصميم وحل التعليقات، تعامل مع المواصفات على أنها مغلقة لهذا السبرنت. يجب أن تمر تغييرات التنفيذ التي تتطلب تحديثات المواصفات بعملية مراجعة، لا أن تتم بصمت.
الخطوة 6: تشغيل اختبارات التحقق من صحة المخطط في CI قم بإعداد حزمة اختبار Apidog للتحقق من صحة مخططات الاستجابة في كل تشغيل CI. هذا هو الحاجز الوقائي التلقائي الذي يحافظ على تزامن التنفيذ والمواصفات.
الأسئلة الشائعة
هل "التصميم أولاً" مخصص فقط لواجهات برمجة تطبيقات REST؟لا. ينطبق مبدأ "التصميم أولاً" على أي بروتوكول يمكنك من خلاله تعريف عقد: GraphQL schema-first، gRPC مع protobuf، AsyncAPI للأنظمة القائمة على الأحداث. يدعم Apidog تصميم REST و GraphQL. بالنسبة لـ gRPC، تخدم ملفات proto نفس الغرض المتمثل في العقد أولاً.
هل نحتاج إلى تعريف كل نقطة نهاية قبل بدء التطوير؟لا. يمكنك اعتماد "التصميم أولاً" على مستوى الميزة: حدد المواصفات للميزة التي أنت على وشك بنائها قبل كتابة الكود، حتى لو كانت أجزاء أخرى من قاعدة الكود تعتمد على "الكود أولاً". يعمل التبني التدريجي.
كيف يعمل "التصميم أولاً" مع دورات Agile؟تحدد جلسات التصميم في بداية الدورة عقد واجهة برمجة التطبيقات لميزات تلك الدورة. تعمل الواجهة الأمامية والخلفية بالتوازي أثناء الدورة. تصبح مراجعة المواصفات جزءًا من تخطيط الدورة.
ماذا لو احتاج التنفيذ إلى الانحراف عن المواصفات الأصلية؟يحدث ذلك. العملية الصحيحة هي تحديث المواصفات أولاً، والحصول على موافقة أصحاب المصلحة (خاصة الواجهة الأمامية)، ثم تحديث التنفيذ. هذا يحافظ على المواصفات كمصدر للحقيقة بدلاً من التنفيذ.
هل يمكننا توليد نماذج أولية للخادم من تصدير OpenAPI الخاص بـ Apidog؟نعم. قم بتصدير المواصفات من Apidog كـ OpenAPI 3.x، ثم استخدم أي مولّد كود قياسي لإنشاء نماذج أولية للخادم. يدعم openapi-generator أكثر من 50 لغة وإطار عمل للخادم.
كيف نتعامل مع ترقيم إصدارات المواصفات؟يحتفظ Apidog بسجل التغييرات داخل المشروع. بالنسبة لتغييرات الإصدارات الرئيسية التي يتم الاحتفاظ بها بالتوازي (الإصدار 1 والإصدار 2 كلاهما نشط)، تعمل المشاريع أو الفروع المنفصلة بشكل جيد.
يتطلب "التصميم أولاً" استثمارًا صغيرًا في الانضباط مقدمًا ويسدد بشكل كبير في تقليل تكاليف التكامل. يجب أن تجعل المنصة التي تختارها هذا الاستثمار الأولي منخفضًا قدر الإمكان. إذا كانت كتابة المواصفات مؤلمة، فستتخطاها الفرق. إن محرر Apidog المرئي، وتوليد النماذج الوهمية الفوري، ومعاينة التوثيق تجعل "التصميم أولاً" هو مسار المقاومة الأقل بدلاً من مسار الفضيلة الأعظم.