تعامل معظم فرق API العقد على أنه مجرد فكرة لاحقة. يكتبون التعليمات البرمجية أولاً، ثم ينشئون مواصفات، ثم يراقبون انفصال الاثنين. تصميم واجهة برمجة التطبيقات الأصيل لـ Git يقلب هذا الترتيب. أنت تعامل عقد API كرمز مصدر، وتضع له إصدارًا في Git، وتراجع كل تغيير بنفس الطريقة التي تراجع بها منطق التطبيق.
يدور هذا الدليل حول الانضباط، وليس أداة واحدة. ستتعلم كيفية تصميم العقود في الفروع، ومراجعتها في طلبات السحب، وتحويل المواصفات الملتزم بها إلى نماذج وهمية (mocks) واختبارات ووثائق. الهدف هو سير عمل يكون فيه سجل Git الخاص بك هو سجل واجهة برمجة التطبيقات الخاصة بك.
إذا كنت تعرف بالفعل كيف تبدو أدوات "Spec-First" وتريد جولة تعريفية بالمنتج، فاقرأ المقال المصاحب حول سير عمل واجهة برمجة التطبيقات الأصيل لـ Git. يركز هذا المقال على الممارسة.
ماذا يعني "أصيل لـ Git" لعمل واجهات برمجة التطبيقات
يعني "أصيل لـ Git" أن تعريف واجهة برمجة التطبيقات الخاصة بك يعيش في مستودعك كملف نص عادي. ليس في قاعدة بيانات سحابية خاصة. وليس خلف تسجيل دخول خاص ببائع. ملف .yaml أو .json يجلس بجانب التعليمات البرمجية الخاصة بك، يتم تتبعه بواسطة نفس نظام التحكم في الإصدار الذي يستخدمه فريقك بالفعل.
قارن هذا بالأدوات المقيدة بالسحابة. تخزن العديد من منصات تصميم واجهة برمجة التطبيقات العقد في الواجهة الخلفية الخاصة بها. يمكنك التعديل عبر واجهة مستخدم ويب، ويعيش الإصدار الأساسي على خوادمهم. يحتوي مستودعك على تصدير قديم في أحسن الأحوال. عندما تكون قاعدة بيانات البائع هي مصدر الحقيقة، لا يخبرك سجل Git الخاص بك شيئًا عن كيفية تطور واجهة برمجة التطبيقات.
يعكس النموذج الأصيل لـ Git هذه العلاقة. الملف في main هو العقد. كل شيء آخر، بما في ذلك أي واجهة مستخدم رسومية (GUI)، هو عرض على هذا الملف. هذا التحول الوحيد يفتح سجل التاريخ، والمساءلة، والتراجع، والمراجعة لواجهة برمجة التطبيقات الخاصة بك.
إعداد أصيل لـ Git له ثلاث خصائص. المواصفات هي ملف نصي في المستودع. تتدفق التغييرات من خلال عمليات Git العادية مثل التفريع (branch)، والالتزام (commit)، والدمج (merge). وكل نتيجة لاحقة، من النماذج الوهمية (mocks) إلى الوثائق، تستمد من الملف الملتزم به بدلاً من قاعدة بيانات منفصلة.
لماذا تصميم وتطوير واجهات برمجة التطبيقات في Git
أنت تثق بالفعل بـ Git في أهم أصولك: التعليمات البرمجية الخاصة بك. عقد واجهة برمجة التطبيقات الخاصة بك يستحق نفس المعاملة.
التاريخ هو السبب الأول. عندما يسأل شخص ما "متى أضفنا معلمة ترقيم الصفحات cursor"، يجيب git log في ثوانٍ. يحمل الالتزام الذي قدمها رسالة ومؤلفًا وتاريخًا. لا توجد لقطات شاشة، ولا حفريات سجل التغييرات.
المساءلة هي الثانية. قم بتشغيل git blame على ملف المواصفات وسترى بالضبط من غير كل سطر ولماذا. يعود اسم حقل مربك إلى طلب السحب الذي أضافه، مع المناقشة المرفقة. تصبح المساءلة تلقائية.
التراجع هو الثالث. تصميم سيء يتم نشره. مع Git، يمكنك git revert الدمج ويعود العقد إلى حالته السابقة. يتم إعادة إنشاء مولدات التعليمات البرمجية، والنماذج الوهمية (mocks)، والوثائق من الملف الذي تم التراجع عنه. لا توجد عملية تنظيف يدوية في نظام منفصل.
المراجعة هي الرابعة، وهي ما تقل الفرق عن استخدامه. طلب السحب هو المكان الطبيعي لمناقشة تصميم واجهة برمجة التطبيقات قبل أن يصبح حقيقة. يعلق المراجعون على سطر + يضيف حقلاً مطلوبًا. تبقى المحادثة بجانب التغيير إلى الأبد.
مصدر واحد للحقيقة يربط كل هذا معًا. عندما يكون العقد ملفًا واحدًا في main، لا يوجد أي غموض حول أي إصدار هو الحقيقي. الواجهة الأمامية والخلفية وضمان الجودة والوثائق جميعها تقرأ نفس السطر من YAML. هذا هو الوعد الأساسي لـ سير عمل مواصفات واجهة برمجة التطبيقات المعتمد على Git.
حلقة تصميم واجهة برمجة التطبيقات الأصيلة لـ Git
تتكون الحلقة من خمس خطوات: تصميم العقد، الالتزام، فتح طلب سحب (PR)، المراجعة، والدمج. يأتي التنفيذ بعد الدمج، وليس العكس.
ابدأ بكتابة العقد. لنفترض أنك تضيف نقطة نهاية لاسترداد فواتير المستخدم. تقوم بإنشاء فرع وتعديل ملف OpenAPI.
# openapi.yaml (excerpt added on branch feat/invoices-list)
paths:
/users/{userId}/invoices:
get:
operationId: listUserInvoices
summary: List invoices for a user
parameters:
- name: userId
in: path
required: true
schema: { type: string, format: uuid }
- name: status
in: query
required: false
schema:
type: string
enum: [draft, open, paid, void]
responses:
"200":
description: A page of invoices
content:
application/json:
schema:
$ref: "#/components/schemas/InvoiceList"
"404":
description: User not found
قم بالالتزام بهذا التغيير برسالة واضحة: git commit -m "Add GET /users/{userId}/invoices contract". الالتزام صغير ومركّز. يصف قرار تصميم واحد.
الآن افتح طلب سحب. يعرض الفرق للمراجعين بالضبط ما هو جديد: مسار واحد، عملية واحدة، معلمتان، استجابتان. يناقش زملاؤك التسمية، وقيم التعداد (enum)، وما إذا كان 404 هو الرمز الصحيح للمستخدم المفقود. قد يضغطون من أجل ترقيم الصفحات باستخدام المؤشر قبل وجود سطر واحد من التعليمات البرمجية للمعالج.
بمجرد الموافقة على طلب السحب (PR)، قم بدمجه. يتضمن العقد في main الآن نقطة نهاية الفواتير. يأتي التنفيذ بعد ذلك، وهو مقيد بالمواصفات التي اتفقتم عليها جميعًا. هذا الترتيب هو ما يعنيه الناس بتطوير واجهة برمجة التطبيقات التي تعتمد على المواصفات أولاً: الاتفاق يسبق التعليمات البرمجية.
المكافأة هي أن مناقشات التصميم تحدث بتكلفة زهيدة. تغيير حقل YAML في المراجعة يكلف دقائق. تغيير نقطة نهاية مشحونة، منفذة، وموثقة يكلف أيامًا.
استراتيجية التفريع لعقود واجهة برمجة التطبيقات
تعامل مع تغييرات العقد مثل أي تغيير آخر: فرع واحد لكل وحدة عمل منطقية. فرع واحد لكل نقطة نهاية أو لكل تعديل يحافظ على طلبات السحب صغيرة والفروقات قابلة للقراءة.
سمِّ الفروع بحيث يكون القصد واضحًا. استخدم بادئة تشير إلى فئة التغيير. هذا يساعد المراجعين و CI على توجيه العمل.
| نوع التغيير | بادئة الفرع | مثال | وزن المراجعة |
|---|---|---|---|
| نقطة نهاية جديدة | feat/api- |
feat/api-invoices-list |
قياسي |
| حقل إضافي | feat/api- |
feat/api-invoice-currency |
خفيف |
| تغيير جذري | break/api- |
break/api-remove-legacy-id |
ثقيل، يحتاج إلى موافقة |
| إصلاح خطأ في المواصفات | fix/api- |
fix/api-status-enum-typo |
خفيف |
| إعادة هيكلة فقط | chore/api- |
chore/api-reorder-schemas |
خفيف |
تحمل البادئة معنى. فرع break/api- يخبر المراجعين بالتباطؤ وفحص كل مستهلك. فرع chore/api- يشير إلى عدم وجود تغيير دلالي، لذا يمكن للمراجعة أن تسير بسرعة.
تختار أيضًا نموذج تفريع. تطوير يعتمد على الجذع (Trunk-based development) يناسب معظم فرق واجهة برمجة التطبيقات. تدمج الفروع قصيرة الأجل في main يوميًا، وتبقى المواصفات قريبة من خط واحد للحقيقة. Gitflow، مع فروع develop و release طويلة الأمد، يناسب الفرق التي تجمع تغييرات واجهة برمجة التطبيقات في إصدارات مجدولة.
| النموذج | الأفضل لـ | مقايضة واجهة برمجة التطبيقات |
|---|---|---|
| يعتمد على الجذع | التسليم المستمر، الفرق الصغيرة | يتطور العقد بخطوات صغيرة؛ ألم دمج أقل |
| Gitflow | الإصدارات المجدولة، الشحن المنظم | تتباعد المواصفات في develop؛ عمليات دمج أكبر وأكثر خطورة |
بالنسبة لمعظم أعمال واجهة برمجة التطبيقات، فضل الأسلوب المعتمد على الجذع. التغييرات الصغيرة والمتكررة في العقد تنتج فروقات صغيرة ومتكررة. تسمح الفروع طويلة الأمد للمواصفات بالابتعاد، وتصبح تعارضات دمج YAML سيئة بسرعة عندما يعيد فرعان هيكلة نفس الملف.
مراجعة تصميم واجهة برمجة التطبيقات في طلبات السحب
طلب سحب المواصفات هو مراجعة تصميم، وليس فحصًا نحويًا. ينظر المراجعون إلى الدلالات، وتغطي بعض الأسئلة معظم المخاطر.
هل هذا يكسر المستهلكين الحاليين؟ إزالة حقل، أو إعادة تسمية مسار، أو تشديد نوع كلها تغييرات جذرية. يتحقق المراجع مما إذا كان التغيير إضافيًا أم جذريًا، وتتطلب التغييرات الجذرية زيادة في الإصدار أو مسارًا للإهمال.
هل التسمية متسقة؟ إذا كانت كل نقطة نهاية مجموعة تستخدم أسماء جمع، فإن المسار الفردي الجديد يبرز. إذا كانت الأخطاء تعيد حقل code في مكان آخر، فيجب أن تفعل نقطة النهاية الجديدة ذلك أيضًا. يفرض المراجعون الأنماط التي أنشأتها واجهة برمجة التطبيقات بالفعل.
هل هو سهل المقارنة؟ حافظ على استقرار YAML بحيث تبقى الفروقات صغيرة. رتب المفاتيح بشكل متسق. أضف مسارات جديدة في مكان يمكن التنبؤ به. يمكن للمراجع قراءة فرق بخمسة أسطر في ثوانٍ، ولكن الملف الذي أعيد ترتيبه ينتج فرقًا بمائة سطر يخفي التغيير الحقيقي.
تغيير جذري سهل للمراجع. تشير أسطر - بالضبط إلى ما يختفي.
# Diff a reviewer sees in the PR
parameters:
- name: status
in: query
schema:
type: string
- enum: [draft, open, paid, void]
+ enum: [draft, open, paid, void, uncollectible]
```هذا الفرق إضافي إلى التعداد (enum)، لذا فهو آمن. قارنه بسطر - الذي يزيل void بالكامل، مما قد يكسر أي عميل يرسل تلك القيمة. يجعل الفرق الاختلاف مرئيًا في لمحة.
شجع المراجعين على التعليق مباشرةً على المواصفات، بنفس الطريقة التي يعلقون بها على التعليمات البرمجية. تبقى المناقشة مرتبطة بالسطر وتستمر في السجل المدمج.
من التصميم إلى التطوير
بمجرد أن يكون العقد في main، يصبح المصدر لكل شيء لاحق. أنت تقوم بالتوليد، ولا تكتب يدويًا.
يأتي توليد التعليمات البرمجية (Codegen) أولاً. تنتج أدوات مثل openapi-generator قوالب خادم وعملاء مكتوبين من الملف الملتزم به. تملأ المعالجات الخاصة بك منطق الأعمال، لكن أشكال الطلب والاستجابة تتطابق مع العقد بالبناء. لا يمكن أن تختلف المواصفات والتعليمات البرمجية حول تنسيق الاتصال.
تأتي النماذج الوهمية (Mocks) بعد ذلك. يقرأ خادم وهمي المواصفات ويعيد استجابات مثال لكل نقطة نهاية. يبني مطورو الواجهة الأمامية مقابل النموذج الوهمي قبل وجود الواجهة الخلفية. يبدأون لحظة دمج العقد، وليس بعد أسابيع.
تتبعها الاختبارات. تؤكد اختبارات العقد أن الخادم قيد التشغيل يتطابق مع المواصفات. أرسل طلبًا، تحقق من صحة الاستجابة مقابل المخطط، وافشل البناء إذا تباعدا. هذا هو الحاجز ضد انحراف المواصفات/التعليمات البرمجية.
يتم إنشاء الوثائق أيضًا. يتم عرض الوثائق المرجعية مباشرةً من ملف OpenAPI. عندما يتغير العقد، تتغير الوثائق في نفس الالتزام. لا يوجد تحديث منفصل للوثائق يمكن نسيانه.
المبدأ متسق. كل نتيجة تستمد من ملف واحد ملتزم به. أعد الإنشاء عند كل دمج، وستظل نماذجك الوهمية (mocks)، وعملاؤك، واختباراتك، ووثائقك متوافقة تمامًا مع العقد.
اتفاقيات الفريق التي تتوسع
الاتفاقيات هي ما يمنع سير العمل الأصيل لـ Git من الانهيار مع نمو الفريق. قررها مبكرًا ودوّنها.
أولاً، اختر بين ملف مواصفات واحد أو عدة ملفات. ملف openapi.yaml واحد بسيط ولكنه يصبح غير عملي بعد بضع عشرات من نقاط النهاية. تقسيمها إلى ملفات متعددة مع مراجع $ref يحافظ على قابلية قراءة كل ملف، على حساب خطوة التجميع. النمط الشائع هو ملف واحد لكل مورد، يتم تجميعه في مواصفات واحدة في وقت البناء.
ثانيًا، ضع الإصدارات عمدًا. ارفع قيمة info.version في OpenAPI عند كل تغيير ذي معنى، واتبع نظام ترقيم الإصدارات الدلالي. ترفع التغييرات الإضافية الإصدار الثانوي. ترفع التغييرات الجذرية الإصدار الرئيسي وعادة ما تعني بادئة مسار جديدة مثل /v2/.
ثالثًا، احتفظ بسجل للتغييرات. يسجل ملف CHANGELOG.md بجانب المواصفات ما تغير ولماذا بعبارات بشرية. سجل Git دقيق ولكنه مطول؛ سجل التغييرات هو الملخص القابل للقراءة الذي يمسحه مستهلكوك بالفعل.
رابعًا، احمِ المواصفات باستخدام CODEOWNERS. اطلب من مشرفي واجهة برمجة التطبيقات الموافقة على أي تغيير في ملف العقد. هذا يمنع المساهمين ذوي النوايا الحسنة من نشر تصاميم غير متسقة.
# .github/CODEOWNERS
/api/openapi.yaml @api-stewards
/api/paths/ @api-stewards
خامسًا، استخدم المدقق (lint) في CI. يلتقط المدقق مشاكل الأسلوب والاتساق قبل المراجعة. قم بتشغيله على كل طلب سحب بحيث يراجع البشر التصميم، وليس التنسيق.
# .github/workflows/api-lint.yml
name: API Lint
on:
pull_request:
paths: ["api/"]
jobs:
spectral:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run Spectral
run: npx @stoplight/spectral-cli lint api/openapi.yaml --fail-severity warn
مع استخدام المدقق (linting) في CI بالإضافة إلى CODEOWNERS، يحصل كل تغيير في العقد على فحوصات آلية ومشرف بشري. يتوسع هذا الدمج من ثلاثة مهندسين إلى ثلاثمائة.
المزالق الشائعة وكيفية تجنبها
لتصميم واجهات برمجة التطبيقات الأصيلة لـ Git أنماط فشل يمكن التنبؤ بها. معرفتها تمكنك من التصميم لتجاوزها.
انحراف المواصفات/التعليمات البرمجية هو الأسوأ. يقول العقد شيئًا؛ يقوم الخادم قيد التشغيل بشيء آخر. امنعه باختبارات العقد في CI التي تتحقق من صحة الاستجابات الحية مقابل المواصفات الملتزم بها. إذا تباعدا، يفشل البناء. يصبح الانحراف خط أنابيب معطلاً، وليس مفاجأة إنتاجية.
طلبات السحب العملاقة هي الفخ التالي. فرع واحد يضيف عشرين نقطة نهاية ينتج فرقًا غير قابل للمراجعة. يتصفح المراجعون، ويوافقون، ويفوتهم المشاكل. قسّم العمل إلى نقطة نهاية واحدة أو تغيير واحد لكل طلب سحب. تحصل الفروقات الصغيرة على مراجعة حقيقية.
تتسبب النتائج المكتوبة يدويًا في عدم اتساق صامت. عندما يكتب شخص عميلاً يدويًا بدلاً من إنشائه، يبتعد العميل عن المواصفات. قم بإنشاء العملاء والقوالب والوثائق من الملف الملتزم به في كل مرة. عامل النتائج المكتوبة يدويًا لواجهة برمجة التطبيقات كعلامة تحذير.
تثير تعارضات دمج YAML إحباط الفرق في الفروع طويلة الأمد. يعيد فرعان هيكلة نفس الملف ولا يمكن لـ Git التوفيق بينهما. تجنب هذا باستخدام فروع قصيرة الأجل، وترتيب مفاتيح مستقر، وتخطيط ملفات مقسم بحيث تلامس التغييرات ملفات مختلفة. التطوير المعتمد على الجذع بالإضافة إلى طلبات السحب الصغيرة يزيل معظم التعارضات قبل أن تبدأ.
النمط عبر الأربعة هو نفسه. حافظ على التغييرات صغيرة، استمد النتائج من المواصفات، ودع CI يفرض العقد. الانضباط يتفوق على البطولات.
أين يتناسب Apidog
يمكنك تشغيل سير عمل أصيل لـ Git باستخدام محرر نصوص وواجهة سطر أوامر (CLI). ترغب العديد من الفرق في واجهة مستخدم رسومية (GUI) للتصميم دون التخلي عن Git كمصدر للحقيقة. هذه هي الفجوة التي يملأها وضع "Spec-First Mode" في Apidog.
يحافظ وضع "Spec-First Mode" على ملف OpenAPI في مستودع Git الخاص بك ويدعم المزامنة ثنائية الاتجاه. يمكنك تعديل العقد في مصمم Apidog المرئي أو في المحرر الخاص بك، ويبقى كلاهما متسقًا مع الملف الموجود في مستودعك. يظل الملف في Git هو الأساس، لذا تعمل الفروع وطلبات السحب (PRs) والسجل جميعها تمامًا كما هو موضح هنا. تحصل على واجهة المستخدم الرسومية دون الارتباط بالسحابة. راجع وثائق وضع "Spec-First Mode" للحصول على تفاصيل الإعداد.
النقطة ليست الأداة. بل هي أنه يمكنك الحصول على سطح تصميم مرئي وانضباط أصيل لـ Git في نفس الوقت. يبقى المستودع هو المصدر الوحيد للحقيقة، ويصبح Apidog أحد العروض عليه.
الأسئلة الشائعة
هل تصميم واجهة برمجة التطبيقات الأصيل لـ Git مخصص لـ OpenAPI فقط؟
لا. ينطبق هذا الانضباط على أي تنسيق عقد قائم على النص. OpenAPI هو الأكثر شيوعًا، ولكن نفس سير العمل يعمل مع AsyncAPI، أو ملفات .proto لـ gRPC، أو GraphQL SDL. طالما أن العقد هو ملف نصي يمكنك مقارنته، وتفريعه، ومراجعته، فهو أصيل لـ Git.
كيف أتعامل مع التغييرات الجذرية في سير عمل أصيل لـ Git؟
اجعل التغييرات الجذرية مرئية ومقصودة. استخدم بادئة فرع break/api-، وقم بزيادة الإصدار الرئيسي، واطلب موافقة المشرف عبر CODEOWNERS. حيثما أمكن، أضف الشكل الجديد جنبًا إلى جنب مع الشكل القديم وأهمل المسار القديم في جدول زمني. يشير فرق طلب السحب وزيادة الإصدار معًا إلى التغيير الجذري لكل مستهلك.
هل يجب أن تعيش مواصفات واجهة برمجة التطبيقات في نفس المستودع مثل التعليمات البرمجية؟
عادة نعم، عندما يمتلك فريق واحد كليهما. يعني وضع المواصفات والتنفيذ في نفس المكان أن طلب سحب واحد يمكن أن يغير العقد والمعالج معًا، وتعمل اختبارات العقد في خط أنابيب واحد. ضع المواصفات في مستودع منفصل فقط عندما تستهلك فرق متعددة واجهة برمجة تطبيقات مشتركة واحدة وتحتاج إلى إصدار مستقل.
كيف أمنع تباعد المواصفات والتعليمات البرمجية؟
أضف اختبارات العقد إلى CI. ترسل طلبات حقيقية إلى الخادم قيد التشغيل وتتحقق من صحة كل استجابة مقابل المواصفات الملتزم بها. يؤدي الاختلاف إلى فشل البناء. بالإضافة إلى إنشاء قوالب وعملاء من المواصفات، تجعل اختبارات العقد الانحراف فشلًا في خط الأنابيب بدلاً من خطأ في الإنتاج.
الخاتمة
تصميم واجهة برمجة التطبيقات الأصيل لـ Git هو انضباط، وليس منتجًا. أنت تتعامل مع العقد كرمز مصدر، وتطوره في الفروع، وتراجعه في طلبات السحب، وتنشئ كل نتيجة لاحقة من الملف الملتزم به. يأتي التاريخ والمساءلة والتراجع والمراجعة مجانًا لأن Git يقدمها لك بالفعل.
ابدأ صغيرًا. انقل مواصفاتك إلى المستودع، وأضف خطوة تدقيق (lint)، واطلب مراجعة على تغييرات العقد. ابنِ من هناك باستخدام توليد التعليمات البرمجية (codegen)، والنماذج الوهمية (mocks)، واختبارات العقد. يتراكم سير العمل: كل اتفاقية تجعل الاتفاقية التالية أسهل، ويصبح سجل Git الخاص بك سجلًا كاملاً لكيفية نمو واجهة برمجة التطبيقات الخاصة بك.
إذا كنت تريد سطح تصميم مرئيًا يحافظ على المواصفات في Git، فجرب وضع "Spec-First Mode" في Apidog وشاهد كيف تتناسب المزامنة ثنائية الاتجاه مع سير العمل المذكور أعلاه.