buf

بوف

يعد buf CLI أفضل أداة للعمل مع مخازن البروتوكول المؤقتة. وهو يوفر:

• جهاز Linter يفرض اختيارات وبنية جيدة لتصميم واجهة برمجة التطبيقات (API).
• كاشف التغيير الجذري الذي يفرض التوافق على مستوى الكود المصدري أو السلك.
• مولد يستدعي المكونات الإضافية الخاصة بك بناءً على قوالب قابلة للتكوين.
• منسق يقوم بتنسيق ملفات Protobuf الخاصة بك وفقًا لمعايير الصناعة.
• التكامل مع سجل مخطط Buf، بما في ذلك إدارة التبعية الكاملة.

تثبيت

البيرة المنزلية

يمكنك تثبيت buf باستخدام Homebrew (نظام التشغيل macOS أو Linux):

brew install bufbuild/buf/buf

يتم تثبيت هذا:

• ثنائيات buf و protoc-gen-buf-breaking و protoc-gen-buf-lint
• البرامج النصية لإكمال Shell لـ Bash وFish وPowershell وzsh

طرق أخرى

للتعرف على طرق التثبيت الأخرى، راجع وثائقنا الرسمية، والتي تغطي:

• تثبيت buf عبر npm
• تثبيت buf على نظام التشغيل Windows
• استخدام buf كصورة Docker
• التثبيت كثنائي، من كرة القطران، ومن المصدر من خلال إصدارات GitHub
• التحقق من الإصدارات باستخدام المفتاح العمومي minisign

الاستخدام

توفر واجهة المساعدة الخاصة بـ Buf ملخصات للأوامر والأعلام:

buf --help

للحصول على معلومات استخدام أكثر شمولاً، راجع وثائق Buf، وخاصة هذه الأدلة:

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (لاستخدام BSR)

CLI يكسر سياسة التغيير

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

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

أهدافنا لProtobuf

هدف Buf هو استبدال النموذج الحالي لتطوير واجهة برمجة التطبيقات (API)، الذي يتمحور حول REST/JSON، بنموذج يعتمد على المخطط . يوفر تعريف واجهات برمجة التطبيقات باستخدام IDL فوائد عديدة مقارنة بـ REST/JSON، ويعتبر Protobuf هو IDL الأكثر استقرارًا والمعتمد على نطاق واسع في الصناعة. لقد اخترنا البناء على هذا الأساس الموثوق به على نطاق واسع بدلاً من إنشاء رقم دولي جديد من الصفر.

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

على الرغم من أننا نعتزم إجراء تحسين تدريجي على buf CLI وBSR، إلا أننا واثقون من أن الأساس الأساسي لمثل هذا النظام البيئي موجود بالفعل .

سجل مخطط Buf

يعد Buf Schema Registry (BSR) عبارة عن منصة SaaS لإدارة واجهات برمجة تطبيقات Protobuf الخاصة بك. فهو يوفر سجلاً مركزيًا ومصدرًا واحدًا للحقيقة لجميع أصول Protobuf الخاصة بك، بما في ذلك ليس فقط ملفات .proto ولكن أيضًا المكونات الإضافية البعيدة. على الرغم من أن BSR يوفر واجهة مستخدم بديهية للمتصفح، إلا buf يمكّنك من تنفيذ معظم المهام المتعلقة بـ BSR من سطر الأوامر، مثل دفع مصادر Protobuf إلى السجل وإدارة المستخدمين والمستودعات.

BSR غير مطلوب لاستخدام buf . لقد جعلنا الميزات الأساسية لـ buf CLI متاحة لجميع مستخدمي Protobuf.

المزيد من ميزات CLI المتقدمة

في حين أن ميزات buf الأساسية يجب أن تغطي معظم حالات الاستخدام، فقد قمنا بتضمين بعض الميزات الأكثر تقدمًا لتغطية حالات الحافة:

• الاكتشاف التلقائي للملفات . يقوم Buf بتوجيه شجرة الملفات الخاصة بك وإنشاء ملفات .proto الخاصة بك وفقًا لتكوين البنية الذي قمت بتوفيره، مما يعني أنك لم تعد بحاجة إلى تحديد --proto_paths يدويًا. ومع ذلك، لا يزال بإمكانك تحديد ملفات .proto يدويًا من خلال علامات CLI في الحالات التي يلزم فيها تعطيل اكتشاف الملفات.
• تكوين قاعدة دقيقة الحبيبات لفحص التغييرات وكسرها. على الرغم من أننا نوصي بالإعدادات الافتراضية، يمكنك دائمًا تحديد المجموعة الدقيقة من القواعد التي تتطلبها حالة الاستخدام الخاصة بك، مع توفر 40 قاعدة بيانات و53 قاعدة تغيير كسرية.
• تنسيقات الأخطاء القابلة للتكوين لمخرجات CLI. يقوم buf بإخراج المعلومات في file:line:column:message بشكل افتراضي لكل خطأ في الوبر وتغييرات انقطاعية يواجهها، ولكن يمكنك أيضًا تحديد إخراج JSON وMSVS وJUnit وGithub Actions.
• تكامل المحرر مدفوع بمخرجات الأخطاء الدقيقة لـ buf . نحن نقدم حاليًا تكاملات الفحص لكل من Vim وVisual Studio Code وJetBrains IDEs مثل IntelliJ وGoLand، ولكننا نخطط لدعم المحررين الآخرين مثل Emacs في المستقبل.
• استهداف المدخلات العالمية يمكّنك Buf من تنفيذ إجراءات مثل الفحص والكشف عن التغيير ليس فقط ضد ملفات .proto المحلية ولكن أيضًا ضد نطاق واسع من المدخلات الأخرى، مثل كرات القطران وملفات ZIP ومستودعات Git البعيدة وملفات الصور المعدة مسبقًا.
• سرعة . يقوم مترجم Protobuf الداخلي الخاص بـ Buf بتجميع مصادر Protobuf الخاصة بك باستخدام جميع النوى المتاحة دون المساس بالمخرجات الحتمية، وهو أسرع بكثير من protoc . وهذا يسمح بتقديم تعليقات شبه فورية، وهو أمر ذو أهمية خاصة لميزات مثل تكامل المحرر.

الخطوات التالية

بمجرد تثبيت buf ، نوصي بإكمال البرنامج التعليمي لـ CLI، والذي يوفر نظرة عامة واسعة النطاق ولكن عملية حول الوظائف الأساسية لـ CLI. تستغرق الجولة حوالي 10 دقائق حتى تكتمل.

بعد الانتهاء من الجولة، قم بمراجعة بقية المستندات الخاصة بمجالات اهتمامك المحددة.

مجتمع

للحصول على المساعدة والمناقشة حول Protobuf وأفضل الممارسات والمزيد، انضم إلينا على Slack.

للحصول على تحديثات بشأن Buf CLI، اتبع هذا الريبو على GitHub.

لطلبات الميزات أو الأخطاء أو الأسئلة الفنية، راسلنا عبر البريد الإلكتروني على [email protected]. للاستفسارات العامة أو التضمين في إصداراتنا التجريبية القادمة، راسلنا عبر البريد الإلكتروني على [email protected].