bufplugin go

bufplugin-go

هذا هو Go SDK لإطار bufplugin. يوفر bufplugin-go حاليًا حزم الشيكات والفحص والتحقق من CheckTest لجعل الأمر بسيطًا للمؤلف واختبار الإضافات المخصصة وتكسير الإضافات. يلف واجهة برمجة تطبيقات bufplugin باستخدام البرنامج المساعد في واجهات ومفاهيم سهلة الاستخدام التي تنظم حول واجهة برمجة تطبيقات Protoreflect القياسية التي تشغل معظم النظام البيئي Protobuf Go. bufplugin-go bufplugin-go أيضًا الإطار الذي يستخدمه فريق BUF لتأليف جميع قواعد الوبر المبنية وكسر التغيير داخل CLI BUF-لقد تأكدنا مع الحفاظ عليه بسيط قدر الإمكان لك لاستخدامه. إذا كنت ترغب في تأليف مكون الإضافي عن الوبر أو كسر التغيير اليوم ، فيجب عليك استخدام bufplugin-go .

يستخدم

البرنامج المساعد هو مجرد ثنائي على نظامك الذي ينفذ API Bufplugin. بمجرد تثبيت مكون إضافي ، ما عليك سوى إضافة مرجع إليه وقواعده ضمن buf.yaml . على سبيل المثال ، إذا قمت بتثبيت البرنامج المساعد PUF-Plugin-Timestamp-Suffix على $PATH الخاص بك:

 version : v2
lint :
  use :
    - TIMESTAMP_SUFFIX
plugins :
  - plugin : buf-plugin-timestamp-suffix
    options :
      timestamp_suffix : _time # set to the suffix you'd like to enforce

جميع التكوينات تعمل كما تتوقع: يمكنك متابعة تكوين use ، except ، ignore ، ignore_only و USE // buf:lint:ignore التعليق يتجاهل ، تمامًا كما تفعل لقواعد مدمجة.

يمكن تسمية المكونات الإضافية مهما كنت تريد أن تكون ، ومع ذلك نوصي باتباع اتفاقية أسماءك الثنائية مع buf-plugin- من أجل الوضوح.

بالنظر إلى الملف التالي:

# foo.proto
syntax = "proto3" ;

package foo ;

import "google/protobuf/timestamp.proto" ;

message Foo {
  google.protobuf.Timestamp start = 1 ;
  google.protobuf.Timestamp end_time = 2 ;
}

سيتم إرجاع الخطأ التالي من buf lint :

 foo.proto:8:3:Fields of type google.protobuf.Timestamp must end in "_time" but field name was "start". (buf-plugin-timestamp-suffix)

أمثلة

في هذه الحالة ، تستحق الأمثلة ألف كلمة ، ونوصيك بقراءة الأمثلة في الاختيار/داخلي/مثال/cmd للبدء:

• Buf-plugin-timestamp-suffix: مكون إضافي بسيط ينفذ قاعدة الوبر واحدة ، TIMESTAMP_SUFFIX ، التي تتحقق من أن جميع حقول google.protobuf.Timestamp لها لاحقة ثابتة لاسم الحقل. هذه اللاحقة قابلة للتكوين عبر خيارات البرنامج المساعد.
• buf-plugin-field-lower-snake-case: مكون إضافي بسيط يقوم بتطبيق قاعدة LINT واحدة ، PLUGIN_FIELD_LOWER_SNAKE_CASE ، تتحقق من أن جميع أسماء الحقول هي lower_snake_case .
• BUF-Plugin-Field-Option-Safe-For-ML: من المحتمل أن يكون أكثر الأمثلة إثارة للاهتمام. المكون الإضافي الذي ينفذ قاعدة LINT FIELD_OPTION_SAFE_FOR_ML_SET و CROKER RALLE RECL FIELD_OPTION_SAFE_FOR_ML_STAYS_TRUE ، كلاهما ينتمي إلى فئة FIELD_OPTION_SAFE_FOR_ML . هذا يفرض خصائص حول مثال على خيار مخصص acme.option.v1.safe_for_ml ، يهدف إلى الإشارة إلى ما إذا كان الحقل آمنًا للاستخدام في نماذج ML أم لا. قد ترغب المنظمة في القول إنه يجب وضع علامة على جميع الحقول بشكل صريح على أنها آمنة أو غير آمنة عبر جميع مخططاتها ، ولا توجد تغييرات في مجال آمنة إلى غير آمنة. هذا البرنامج المساعد من شأنه أن يفرض هذا المنظمة. يوضح المثال تنفيذ قواعد متعددة ، وتصنيفها ، وأخذ قيم الخيارات المخصصة في الاعتبار.
• BUF-Plugin-Syntax محدد: مكون إضافي بسيط ينفذ قاعدة الوبر واحدة ، PLUGIN_SYNTAX_SPECIFIED ، يتحقق من أن جميع الملفات لها إعلان syntax صريح. يوضح هذا استخدام بيانات تعريف إضافية موجودة في واجهة برمجة تطبيقات bufplugin بما يتجاوز ما يوفره FileDescriptorProto .

تحتوي كل هذه الأمثلة على تطبيق مكون إضافي main.go ، وملف اختبار main_test.go الذي يستخدم حزمة checktest لاختبار سلوك البرنامج المساعد. تستخدم حزمة checktest protocompile لتجميع ملفات test .proto على الطيران ، وتشغيلها مقابل قواعدك ، ومقارنة التعليقات التوضيحية الناتجة مقابل التوقع.

إليك مثال قصير على تطبيق البرنامج المساعد - هذا كل ما يتطلبه:

 package main

import (
	"context"

	"buf.build/go/bufplugin/check"
	"buf.build/go/bufplugin/check/checkutil"
	"google.golang.org/protobuf/reflect/protoreflect"
)

func main () {
	check . Main (
		& check. Spec {
			Rules : [] * check. RuleSpec {
				{
					ID :      "PLUGIN_FIELD_LOWER_SNAKE_CASE" ,
					Default : true ,
					Purpose : "Checks that all field names are lower_snake_case." ,
					Type :    check . RuleTypeLint ,
					Handler : checkutil . NewFieldRuleHandler ( checkFieldLowerSnakeCase , checkutil . WithoutImports ()),
				},
			},
		},
	)
}

func checkFieldLowerSnakeCase (
	_ context. Context ,
	responseWriter check. ResponseWriter ,
	_ check. Request ,
	fieldDescriptor protoreflect. FieldDescriptor ,
) error {
	fieldName := string ( fieldDescriptor . Name ())
	fieldNameToLowerSnakeCase := toLowerSnakeCase ( fieldName )
	if fieldName != fieldNameToLowerSnakeCase {
		responseWriter . AddAnnotation (
			check . WithMessagef (
				"Field name %q should be lower_snake_case, such as %q." ,
				fieldName ,
				fieldNameToLowerSnakeCase ,
			),
			check . WithDescriptor ( fieldDescriptor ),
		)
	}
	return nil
}

func toLowerSnakeCase ( fieldName string ) string {
	// The actual logic for toLowerSnakeCase would go here.
	return "TODO"
}

الحالة: بيتا

يقع Bufplugin حاليًا في الإصدار التجريبي ، وقد يتغير ونحن نعمل مع المتبنين الأوائل. نحن نعتزم شحن V1.0 مستقرة بحلول نهاية عام 2024. ومع ذلك ، نعتقد أن واجهة برمجة التطبيقات هي بالقرب من شكلها النهائي.

قانوني

عرضت تحت رخصة Apache 2.