bufplugin go

bufplugin-go

Dies ist das GO SDK für das Bufplugin -Framework. bufplugin-go bietet derzeit die Pakete für Check-, CheckUtil und kontrolliert, um die Autor- und Testen von benutzerdefinierten FINT- und Breaking Change-Plugins zu vereinfachen. Es wickelt die bufplugin API mit PluginRPC-Go in einfach zu verwendenden Schnittstellen und Konzepten, die sich um die Standard-Protoreflect-API organisieren, die den größten Teil des GO-Protobuf-Ökosystems versorgt. bufplugin-go bufplugin-go ist auch der Rahmen, mit dem das BUF-Team alle integrierten FINT- und BESTELLEN Änderungsregeln innerhalb der BUF-Cli-Veränderung verzeichnet. Wir haben dafür gesorgt, während Sie es so einfach wie möglich halten, damit Sie es verwenden können. Wenn Sie heute einen Fussel- oder Breaking Change-Plugin autorieren möchten, sollten Sie bufplugin-go verwenden.

Verwenden

Ein Plugin ist nur ein Binärdauer Ihres Systems, das die Bufplugin -API implementiert. Sobald Sie ein Plugin installiert haben, fügen Sie einfach einen Verweis und seine Regeln in Ihrem buf.yaml hinzu. Wenn Sie beispielsweise das BUF-Plugin-Timestamp-Suffix-Beispiel-Plugin auf Ihrem $PATH installiert haben:

 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

Alle Konfiguration funktioniert wie erwartet: Sie können use weiterhin benutzen, except ignore , ignore_only und verwenden und verwenden // buf:lint:ignore Kommentar ignoriert, genau wie Sie es für die integrierten Regeln tun würden.

Plugins können genannt werden, was Sie möchten, aber wir empfehlen, nach der Übereinstimmung mit dem Voraus der Klarheit nach dem Voraus der Brügen mit buf-plugin- zu folgen.

Angesichts der folgenden Datei:

# foo.proto
syntax = "proto3" ;

package foo ;

import "google/protobuf/timestamp.proto" ;

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

Der folgende Fehler wird von buf lint zurückgegeben:

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

Beispiele

In diesem Fall sind Beispiele mehr als tausend Wörter wert, und wir empfehlen Ihnen, die Beispiele in Schach/Intern/Beispiel/CMD zu lesen, um loszulegen:

• BUF-Plugin-Timestamp-Suffix: Ein einfaches Plugin, das eine einzelne Lint-Regel implementiert, TIMESTAMP_SUFFIX , das überprüft, ob alle google.protobuf.Timestamp Felder ein einheitliches Suffix für ihren Feldnamen haben. Dieses Suffix kann über Plugin -Optionen konfiguriert werden.
• BUF-Plugin-Feld-Lower-Snake-Case: Ein einfaches Plugin, das eine einzelne Lint-Regel implementiert, PLUGIN_FIELD_LOWER_SNAKE_CASE , die überprüft, ob alle Feldnamen lower_snake_case sind.
• BUF-Plugin-Field-Option-Safe-for-ML: Wahrscheinlich die interessantesten Beispiele. Ein Plugin, das eine Lint -Regel FIELD_OPTION_SAFE_FOR_ML_SET implementiert, und ein Breaking -Änderungsregel FIELD_OPTION_SAFE_FOR_ML_STAYS_TRUE , die beide zur Kategorie FIELD_OPTION_SAFE_FOR_ML gehören. Dadurch werden Eigenschaften um eine Beispiel für benutzerdefinierte Option acme.option.v1.safe_for_ml erzwungen, die darauf hinweisen soll, ob ein Feld in ML -Modellen sicher verwendet werden kann oder nicht. Eine Organisation möchte vielleicht sagen, dass alle Felder in allen Schemata explizit als sicher oder unsicher gekennzeichnet sein und sich kein Feld von sicher zu unsicher wechselt. Dieses Plugin würde diese organisatorische Seite durchsetzen. Das Beispiel zeigt die Implementierung mehrerer Regeln, die Kategorisierung und Berücksichtigung von benutzerdefinierten Optionswerten.
• BUF-Plugin-Syntax-spezifiziert: Ein einfaches Plugin, das eine einzelne Lint-Regel implementiert, PLUGIN_SYNTAX_SPECIFIED , die prüft, dass alle Dateien eine explizite syntax Deklaration haben. Dies zeigt, dass in der bufplugin -API zusätzliche Metadaten verwendet werden, die über das sind, was ein FileDescriptorProto bietet.

Alle diese Beispiele haben eine main.go -Plugin -Implementierung und eine main_test.go -Testdatei, in der das checktest zum Testen des Plugin -Verhaltens verwendet wird. Das checktest -Paket verwendet Protokompile, um Test .proto im laufenden Fliegen zu kompilieren, sie gegen Ihre Regeln auszuführen und die daraus resultierenden Annotationen mit einer Erwartung zu vergleichen.

Hier ist ein kurzes Beispiel für eine Plugin -Implementierung - dies ist alles, was es braucht:

 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 ist derzeit in der Beta und kann sich ändern, wenn wir mit frühen Anwälten zusammenarbeiten. Wir beabsichtigen, bis Ende 2024 einen stabilen V1.0 zu versenden. Wir glauben jedoch, dass die API in der Nähe ihrer endgültigen Form ist.

Legal

Angeboten unter der Apache 2 -Lizenz.