بالتأكيد ، أثناء تطوير واجهة برمجة التطبيقات ، ظهرت صعوبات في الوثائق أكثر من مرة: إما أنها غير موجودة ، ثم لا تعرض السلوك الموضح في الكود.
من وجهة نظر المطور ، لا تستغرق كتابة الوثائق (داخلية فقط) وقتًا أقل من كتابة الكود نفسه. هل هذا مألوف؟ ثم مرحبا بكم في القط.
هل هناك مشكلة؟
يعمل فريقنا على تطوير واجهة برمجة التطبيقات (API) لفترة طويلة ، وهو أساس منتجاتنا ، ولكن في ذلك الوقت لم يكن هناك مستخدمون مباشرون ، لذلك لم ير أحد الحاجة لتوثيق شيء للاستخدام الخارجي. مثل كل الفرق ، بدأنا بالوثائق الداخلية - الطريقة الأولى ، ثم الطريقة الأخرى. في مساحتنا في Confluence ، يمكنك العثور على عشرات الصفحات الأخرى التي تعرض معلومات متقاربة جميلة - أي نوع من طريقة API ، ومسار الاستعلام لديها ، والمعلمات وما نحصل عليه في الإخراج.
كل شيء سيكون على ما يرام ، ولكن الرمز يتغير باستمرار وينمو ، واحتياجات العمل تتغير. جنبا إلى جنب مع تغييرات التعليمات البرمجية ، يمكن أن تتغير واجهات برمجة التطبيقات ، مما يؤدي حتما إلى تغييرات على هذه الصفحات. حسنًا ، إذا كانت صفحة واحدة وفقط مرة واحدة. وإذا كان هناك المزيد من التغييرات؟
لقد توصلنا إلى حل (الدراجة الخاصة بنا) ، قدر الإمكان ، أثناء الانخراط في الأنشطة المعتادة للمطور ، وليس التفكير في كتابة وتحديث الوثائق الداخلية.
بعض الحلول
هناك خيارات مختلفة لكيفية ربط الشفرة ومواصفاتها ، ولكن بالنسبة لي أنا أميز اثنين:
- الكود أولاً ، المواصفات التالية
- المواصفات أولا ، رمز المقبل
سأبدأ بالثاني ، كما هو الحال مع الخيار الأقل ملاءمة لنا.
المواصفة أولاً ، الكود التالي يتعلق بإنشاء الكود ، بناءً على المواصفات ، أي الكود غير موجود حتى تكتب المواصفات.
أبسط مثال هو Swagger Codegen.
لدى شركتنا فرق تستخدم هذه الطريقة في منتجاتها ، لكن في حالتنا لم تكن مناسبة للغاية. في الوقت الذي واجهنا فيه حاجة ، قمنا بالفعل بكتابة الكثير من أساليب واجهة برمجة التطبيقات ، لذا من أجل التوثيق ، لم نكن نريد تغيير عمليات التطوير بشكل جذري - أولاً نكتب المسودات ، ثم نقوم بالكود ثم وصف المواصفات فقط.
الكود أولاً ، المواصفات التالية - كل شيء بسيط ، أولاً نكتب الكود ، ثم المواصفات. ولكن بعد ذلك برز السؤال - وإذا كنا لا نريد أن نجعل حركات غير ضرورية بحيث يتم إنشاء المواصفات؟
يستخدم عدد من التطبيقات في شركتنا هذا النهج ، لكنه ليس آليًا بشكل خاص - يتم تقدير طرق واجهة برمجة التطبيقات (API) بجميع أنواع التعليقات التوضيحية ، التي تم بناء المواصفات عليها. لكن هذه التعليقات التوضيحية نفسها لا تتوافق مع الواقع في كثير من الأحيان ، لأن احتياجات وقدرات التطبيق تنمو وتتغير.
قلت لنفسي
"أنت مبرمج" ، وقررت أن أكتب نموذجًا صغيرًا يسمح لي بعدم كتابة كل هذه القمامة الروتينية.
عند القيام بالمهمة التالية وكتابة الاختبار الوظيفي التاسع ، أدركت أن لدينا بالفعل جميع المعلومات المتعلقة بالمواصفات.
لدينا اختبارات وظيفية تحتوي على جميع المعلومات التي نحتاجها تقريبًا:
- ما يسمى
- ما يسمى (المعلمات ، الجسم ، الرؤوس ، وما إلى ذلك)
- ما النتيجة المتوقعة (رمز الحالة ، نص الاستجابة)
لماذا لا تجعل الدراجة الخاصة بك؟
تقريبا كل ما نكتبه عادة في المواصفات لدينا. حالة صغيرة - رمز هذه الحالة.
منذ طلبنا في php ، جاء التفكير لمساعدتي. باستخدام القليل من الانعكاس ، نجمع جميع أساليب واجهة برمجة التطبيقات المتاحة لنا ، ونأخذ البيانات من الاختبارات الوظيفية ، ونستخرج البيانات حول الترخيص ونوعه. من الشروح المعتادة إلى الأساليب ، نحصل على وصف الطريقة نفسها. بعد خلط كل هذا ، والتوابل مع ميزات محددة للإطار المستخدم في حلولنا ، في غضون أسبوعين نحصل على حل لا يتطلب عملياً وقتًا إضافيًا من المطور.
يمثل إنشاء المواصفات الخطوة الأولى فقط - تحتاج إلى الحصول على وثائق من المواصفات التي يمكن أن يوفرها مطور خارجي. أحد متطلبات التوثيق هو أنه ينبغي تقديمه بعدة لغات ، ولكن في الوقت الحالي ، فإننا نقوم فقط بإنشاء الوثائق باللغة الإنجليزية. يكفي حتى الآن ، ولكن سيكون من الضروري توصيل آلية لتلقي التحويلات بمخطط توليد المواصفات الخاص بنا.
المشكلة التي كانت في الأصل حلنا. ولكن مع هذا الحل هناك العديد من المخاطر:
- سعر دعم الدراجة الخاصة بك
- تمديد الوظائف اللازمة
- تحديث وتزامن الترجمات
يجب أن تؤخذ هذه المخاطر في الاعتبار ، وإذا بدأت العمل ، فقم باتخاذ إجراء.