غالبًا ما يتلخص إنشاء ميزات واجهة سطر الأوامر (CLI) في:

• إصدار نقطة (نقاط) نهاية واجهة برمجة التطبيقات الجديدة.
• إنشاء إجراءات CLI جديدة تحتاج إلى تغييرات في واجهة برمجة التطبيقات.
• ندرك أنه تم ارتكاب أخطاء في واجهة برمجة التطبيقات (API) التي أصدرتها للتو.
• حاول إصلاح واجهة برمجة التطبيقات لهذه الميزة دون خلق المزيد من المشاكل في المستقبل.
• حاول أن تتذكر ما كنت تحاول تحقيقه في واجهة سطر الأوامر (CLI) ثم قم بتحقيقه بالفعل.  
• GOTO: أدرك أنه تم ارتكاب أخطاء.

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

كنت هناك، فعلت ذلك. كنا نعلم أننا بحاجة إلى تجاوز نهج الشلال.

إليكم قصة كيف وصلنا إلى هذا الهدف وبعض الأدوات التي ساعدتنا على طول الطريق.

قبالة لبداية سطحية

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

بالعودة إلى العملية، فهي تبدأ باقتراح الميزات. أردنا الخروج من المجرد، ولكن ليس إذا كان ذلك يعني التنفيذ غير المكتمل. لقد قمنا بتزييفها باستخدام "رسومات تخطيطية"، مستوحاة من أسلوب رسم Google Docs CLI الذي يصفه Github هنا.

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

منذ ذلك الحين وجدنا طريقة أفضل لالتقاط مخرجات CLI المتحركة، ولكن شرح ذلك يتطلب بعض الانعطاف.

هل حتى اختبار؟

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

يركز Teatest على الاختبارات الذهبية، حيث يلتقط مخرجات جيدة معروفة ثم يؤكد أن المخرجات المستقبلية تستمر في مطابقتها. مما أعادنا مرة أخرى إلى التقاط مخرجات CLI المتحركة بدقة عالية. لقد أعطانا Teatest فكرة رائعة عن حل قائم على الإطار، مثل دفتر الصور المتحركة، والذي بنينا عليه:

─── SigninHeader ───────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
─── SigninInput --──────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    ? What is your username?
    ? user
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signing in to your CLI account… ⠋
─── SigninInput ────────────────────────────────────────────────────────────────
# Signin To Your CLI Account `cli auth signin`
    * Signed in to your CLI account: [email protected]

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

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

مع وجود رسوماتنا المستقبلية والمستقبلية، دعنا نعود إلى البدء بنقاط نهاية واجهة برمجة التطبيقات الجديدة.

تصميم API وCLI معًا

نحن نعمل على واجهة برمجة التطبيقات (API) وواجهة سطر الأوامر (CLI) في وقت واحد، لأن أفضل التصميمات لها تنشأ من التكامل المحكم. نحن قادرون على القيام بذلك، مع تجنب مخاطر الشلال، من خلال تكرار التصميمات في سياقات أرخص وانتظار التنفيذ حتى يتم ترسيخ المتطلبات. بالنسبة لواجهات برمجة التطبيقات الخاصة بنا، هذا يعني الرسم باستخدام OpenAPI:

openapi: 3.1.0
info:
  contact:
    email: [email protected]
  description: An example API.
  title: Example API
  version: 0.0.1
servers:
  - url: https://api.example.com
tags:
  - description: account operations
    name: account
paths:
  '/v0/auth/signin':
    post:
      description: Signin to CLI.
      operationId: auth_signin
      responses:
        '200':
          content:
            'application/json':
              schema:
                additionalProperties: false
                properties:
                  email:
                    description: Email address for authenticated user.
                    example: [email protected]
                    type: string
                required:
                  - email
                type: object
          description: Successful signin.
      summary: Signin to CLI.
      tags:
        - account

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

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

تنفيذ واجهات برمجة التطبيقات

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

الاختبار باستخدام المحاكاة والوكلاء

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

سحب كل ذلك معا

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

سنستمر في تكرار عمليتنا، وآمل أن تتعلم شيئًا منها وأود أن أتعلم منك. ماذا جربت وأين تفتخر وما الذي بقي محبطا؟