هل برونو أسلوب الطلب أولاً؟ متى تحتاج أداة تصميم أولاً

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

جرّب Apidog اليوم

الطلبات أولاً مقابل التصميم أولاً، باختصار

النهجان لا يحلان المشكلة نفسها:

• الطلبات أولاً يسأل: كيف أستدعي نقطة النهاية هذه؟
• التصميم أولاً يسأل: كيف يجب أن تبدو نقطة النهاية قبل أن يكتب أي فريق الكود؟

البعد	الطلبات أولاً (برونو)	التصميم أولاً (مبني على OpenAPI)
القطعة الأولية	طلب يمكنك إرساله	عقد API عبر مواصفات OpenAPI
الأفضل لـ	استكشاف واختبار APIs موجودة	تصميم APIs جديدة أو مشتركة قبل التنفيذ
مصدر الحقيقة	مجموعة الطلبات	المواصفات
مراجعة متعددة الفرق	غالبًا بعد وجود نقاط النهاية	قبل كتابة كود الخادم
واجهة تصميم مرئية	غير موجودة افتراضيًا	مصمم مرئي + محرر مخطط
خطر الانجراف	قد تتأخر المجموعة عن API الحقيقية	المواصفات تبقى العقد المرجعي
قصة Git	قوية عبر ملفات .bru	قوية عندما تتم مزامنة المواصفات مع Git

الاختيار العملي يعتمد على المرحلة: هل الـ API موجودة وتريد اختبارها؟ أم أنك تصمم عقدًا سيعتمد عليه أكثر من فريق؟

نموذج برونو للطلبات أولاً

برونو يؤدي دور عميل API محلي أولاً. الطلبات تُحفظ كملفات نصية .bru داخل مجلد تملكه، ويمكن مراجعتها ودمجها مثل بقية ملفات المشروع. هذا هو جوهر سير عمل واجهة برمجة التطبيقات الأصيل لـ Git الذي تفضله فرق كثيرة.

مثال مبسط لفكرة الطلب المخزن كملف نصي:

meta {
  name: Get user
  type: http
}

get {
  url: https://api.example.com/users/123
  body: none
  auth: none
}

headers {
  Accept: application/json
}

هذا النموذج عملي عندما يكون الهدف هو:

1. فتح خدمة تعمل بالفعل.
2. إرسال طلبات HTTP بسرعة.
3. فحص الاستجابة.
4. إضافة assertions أو scripts.
5. تتبع التغييرات في Git.

حيث يتألق برونو:

• استكشاف API موجودة: وجّه الطلب إلى خدمة قيد التشغيل، أرسل، افحص، وكرر.
• محلي أولاً ومتوافق مع Git: الفروقات قابلة للقراءة، والطلبات تعيش بجانب الكود.
• البرمجة النصية والاختبار: يمكن استخدام scripts قبل/بعد الطلب، متغيرات بيئية، وتأكيدات.
• ملكية الملفات: التنسيق نصي والملفات تحت سيطرتك.

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

تكلفة عدم وجود طبقة تصميم أو عقد

تظهر حدود الطلبات أولاً عندما لا تكون الـ API موجودة بعد، أو عندما يحتاج أكثر من فريق إلى الاتفاق على شكلها قبل التنفيذ.

1. لا يوجد نموذج تصميم مركزي

في أدوات الطلبات أولاً، نقطة البداية هي طلب HTTP، مثل:

POST /users
Content-Type: application/json

{
  "name": "Ali",
  "email": "[e-mail]"
}

هذا يوضح مثالًا على الاستدعاء، لكنه لا يعرّف بالضرورة العقد الكامل:

• ما الحقول المطلوبة؟
• ما نوع كل حقل؟
• ما شكل الخطأ؟
• ما الاستجابات الممكنة؟
• هل email يجب أن يكون فريدًا؟
• هل هناك pagination أو filtering؟

في التصميم أولاً، تُعرّف هذه التفاصيل في OpenAPI قبل التنفيذ.

2. خطر انجراف العقد

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

أما في سير عمل مبني على المواصفات، فالعقد هو المرجع:

openapi: 3.1.0
info:
  title: Users API
  version: 1.0.0

paths:
  /users:
    post:
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: User created
        "400":
          description: Invalid request

components:
  schemas:
    CreateUserRequest:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
        email:
          type: string
          format: email

هذا الملف يوضح البنية التي يجب أن يلتزم بها التنفيذ والعملاء.

3. مراجعة أصعب قبل كتابة الكود

مراجعة مجلد طلبات تخبرك كيف تُستدعى endpoints اليوم. لكنها ليست دائمًا أفضل طريقة للموافقة على تصميم API قبل التنفيذ.

في فرق متعددة، تحتاج عادةً إلى مراجعة واضحة لـ:

• الموارد.
• المسارات.
• schemas.
• status codes.
• errors.
• versioning.
• breaking changes.

هذا أسهل عندما يكون هناك عقد OpenAPI من الدرجة الأولى.

برونو ليس أداة سيئة بسبب ذلك؛ هو ببساطة أداة طلبات أولاً، وتصبح حدوده أوضح عندما تستخدمه لتصميم عقود APIs جديدة.

متى يفوز نهج التصميم أولاً

نهج التصميم أولاً مفيد خصوصًا في الحالات التالية.

1. APIs جديدة تمامًا

عندما لا يوجد implementation بعد، ابدأ بالمواصفات:

paths:
  /orders/{orderId}:
    get:
      summary: Get order by ID
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Order found
        "404":
          description: Order not found

بعد الاتفاق على العقد، يمكن للفرق استخدامه كأساس للتوثيق، mocks، ومراجعة التصميم.

2. عقود بين أكثر من فريق

إذا كان فريق الواجهة الخلفية وفريق الواجهة الأمامية يعملان بالتوازي، فإن OpenAPI يصبح نقطة الاتفاق.

سير عمل عملي:

1. صمّم endpoint في OpenAPI.
2. راجع العقد في Pull Request.
3. وافق الفريقان على الشكل.
4. يبدأ فريق الواجهة الأمامية بالعمل مقابل mock أو contract.
5. ينفذ فريق الواجهة الخلفية نفس العقد.
6. تُختبر الاستجابة الفعلية مقابل المواصفات.

3. APIs عامة

عندما يعتمد مطورون خارجيون على API، يصبح العقد والتوثيق جزءًا من المنتج. وجود مواصفات محافظة عليها يساعد في:

• توثيق endpoints.
• توضيح breaking changes.
• توحيد status codes.
• تقليل الغموض في التكامل.

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

Apidog: تصميم أولاً بالإضافة إلى وضع المواصفات أولاً

تم تصميم Apidog لدعم سير عمل التصميم أولاً، مع الحفاظ على تجربة OpenAPI وGit.

يمكنك العمل بطريقتين على نفس المشروع:

1. مصمم مرئي لتحديد endpoints، مخططات الطلبات والاستجابات، والمكونات القابلة لإعادة الاستخدام دون كتابة YAML يدويًا.
2. وضع المواصفات أولاً لكتابة مستند OpenAPI مباشرة كمصدر الحقيقة.

الفكرة العملية هنا أن المصمم المرئي ومحرر المواصفات يبقيان العقد نفسه متزامنًا. يمكن لمهندس الخلفية العمل على OpenAPI الخام، بينما يراجع عضو آخر التصميم بصريًا.

مثال على سير عمل قابل للتطبيق:

1. ابدأ بتعريف المسار /users في OpenAPI.
2. أضف schema للطلب والاستجابة.
3. راجع العقد مع فريق الواجهة الأمامية.
4. اربط المواصفات مع Git.
5. مرر التعديل عبر Pull Request.
6. بعد الموافقة، ابدأ التنفيذ والاختبار بناءً على العقد.

يدعم وضع المواصفات أولاً أيضًا مزامنة Git ثنائية الاتجاه: تعيش المواصفات في المستودع كملف حقيقي، وتتدفق التغييرات في كلا الاتجاهين، ويمر تصميم API عبر نفس Pull Requests والمراجعات مثل الكود. هذه هي الخاصية الأصلية لـ Git التي يقدّرها مستخدمو برونو، لكنها تُطبّق على العقد بدل مجموعة الطلبات. التفاصيل موجودة في وثائق وضع المواصفات أولاً.

النتيجة هي سير عمل يغطي السؤالين:

• صمّم العقد أولاً عندما تحتاج إلى اتفاق قبل التنفيذ.
• اختبر الطلبات لاحقًا عندما تصبح endpoints متاحة.

للمزيد حول نقطة التقاء هذه النماذج، راجع المواصفات أولاً مقابل التصميم أولاً في Apidog.

الاختيار حسب نضج الفريق

طريقة عملية لاتخاذ القرار: طابق الأداة مع مرحلة API في دورة حياتها.

استخدم الطلبات أولاً عندما:

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

انتقل إلى التصميم أولاً عندما:

• تبني API جديدة.
• يعتمد فريق آخر على endpoints الخاصة بك.
• تحتاج إلى مراجعة تصميم قبل الكود.
• تريد توثيقًا واضحًا من العقد.
• تريد تقليل أخطاء التكامل الناتجة عن الغموض.

في مؤسسة أكبر

عندما تمتلك المؤسسة APIs عامة أو داخلية كثيرة، يصبح التصميم أولاً أقرب إلى ضرورة تشغيلية. المواصفات تعمل كـ:

• عقد.
• توثيق.
• أداة مراجعة.
• مرجع للفرق.
• آلية حوكمة.

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

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

هل برونو يعتمد على الطلبات أولاً أم التصميم أولاً؟

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

هل يمكنني القيام بعمل تصميم أولاً في برونو؟

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

هل يجب أن أتخلى عن Git للانتقال إلى التصميم أولاً؟

لا. يمكن تطبيق نموذج Git، الملفات النصية، الفروقات القابلة للقراءة، والمراجعة عبر Pull Requests على المواصفات نفسها. وضع المواصفات أولاً في Apidog يحافظ على مستند OpenAPI داخل المستودع بمزامنة ثنائية الاتجاه، لذلك لا يعني التصميم أولاً التخلي عن Git.