bufplugin go

BUFPLUGIN-GO

Ini adalah Go SDK untuk kerangka kerja bufplugin. bufplugin-go saat ini menyediakan paket cek, checkutil, dan checkTest untuk membuatnya mudah untuk penulis dan menguji serat khusus dan memecahkan plugin perubahan. Ini membungkus API bufplugin dengan pluginrpc-go dalam antarmuka dan konsep yang mudah digunakan yang mengorganisir di sekitar API Protoreflect standar yang memberi kekuatan sebagian besar ekosistem protobuf GO. bufplugin-go juga merupakan kerangka kerja yang digunakan tim BUF untuk menulis semua aturan serat builtin dan melanggar perubahan dalam Buf CLI-kami telah memastikan bahwa bufplugin-go cukup kuat untuk mewakili aturan perubahan serat dan melanggar yang paling kompleks yang paling kompleks dan melanggar kompleks yang paling kompleks kompleks kompleks yang paling kompleks kompleks yang paling kompleks yang paling kompleks Sambil menjaganya sesederhana mungkin untuk Anda gunakan. Jika Anda ingin menulis plugin ubah serat atau melanggar hari ini, Anda harus menggunakan bufplugin-go .

Menggunakan

Plugin hanyalah biner pada sistem Anda yang mengimplementasikan API bufplugin. Setelah Anda menginstal plugin, cukup tambahkan referensi ke sana dan aturannya di dalam buf.yaml Anda. Misalnya, jika Anda telah menginstal plugin contoh buf-plugin-simestamp-suffix di $PATH Anda:

 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

Semua konfigurasi berfungsi seperti yang Anda harapkan: Anda dapat terus mengonfigurasi use , except , ignore , ignore_only dan menggunakan // buf:lint:ignore komentar mengabaikan, seperti yang Anda lakukan untuk aturan builtin.

Plugin dapat dinamai apa pun yang Anda inginkan, namun kami akan merekomendasikan mengikuti konvensi awalan nama biner Anda dengan buf-plugin- untuk kejelasan.

Mengingat file berikut:

# foo.proto
syntax = "proto3" ;

package foo ;

import "google/protobuf/timestamp.proto" ;

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

Kesalahan berikut akan dikembalikan dari 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)

Contoh

Dalam hal ini, contoh bernilai ribuan kata, dan kami sarankan Anda membaca contoh -contoh dalam cek/internal/contoh/CMD untuk memulai:

• BUF-PLUGIN-SIFFIX: Plugin sederhana yang mengimplementasikan aturan serat tunggal, TIMESTAMP_SUFFIX , yang memeriksa bahwa semua bidang google.protobuf.Timestamp memiliki akhiran yang konsisten untuk nama lapangan mereka. Sufiks ini dapat dikonfigurasi melalui opsi plugin.
• BUF-PLUGIN-Field-Lower-Snake-Case: Plugin sederhana yang mengimplementasikan aturan serat tunggal, PLUGIN_FIELD_LOWER_SNAKE_CASE , yang memeriksa apakah semua nama bidang adalah lower_snake_case .
• Buf-plugin-field-option-safe-for-ml: kemungkinan contoh yang paling menarik. Plugin yang mengimplementasikan aturan lint FIELD_OPTION_SAFE_FOR_ML_SET dan aturan perubahan FIELD_OPTION_SAFE_FOR_ML_STAYS_TRUE , keduanya termasuk dalam kategori FIELD_OPTION_SAFE_FOR_ML . Ini menegakkan properti di sekitar contoh opsi khusus acme.option.v1.safe_for_ml , dimaksudkan untuk menunjukkan apakah suatu bidang aman untuk digunakan dalam model ML. Suatu organisasi mungkin ingin mengatakan bahwa semua bidang harus secara eksplisit ditandai sebagai aman atau tidak aman di semua skema mereka, dan tidak ada perubahan lapangan dari aman menjadi tidak aman. Plugin ini akan menegakkan sisi organisasi ini. Contoh ini memamerkan penerapan beberapa aturan, mengkategorikannya, dan memperhitungkan nilai opsi khusus.
• BUF-PLUGIN-SYNTAX-SCIFIKASI: Plugin sederhana yang mengimplementasikan aturan satu lint, PLUGIN_SYNTAX_SPECIFIED , yang memeriksa bahwa semua file memiliki deklarasi syntax eksplisit. Ini menunjukkan menggunakan metadata tambahan yang ada dalam API bufplugin di luar apa yang disediakan oleh FileDescriptorProto .

Semua contoh checktest memiliki implementasi plugin main.go main_test.go Paket checktest menggunakan protokompilasi untuk mengkompilasi uji .proto file dengan cepat, menjalankannya dengan aturan Anda, dan membandingkan anotasi yang dihasilkan dengan ekspektasi.

Berikut adalah contoh singkat dari implementasi plugin - hanya ini yang diperlukan:

 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"
}

Status: Beta

Bufplugin saat ini dalam beta, dan dapat berubah saat kami bekerja dengan pengadopsi awal. Kami bermaksud mengirimkan v1.0 yang stabil pada akhir 2024. Namun, kami percaya API berada di dekat bentuk akhirnya.

Legal

Ditawarkan di bawah lisensi Apache 2.