bufplugin go

Bufplugin-Go

Это GO SDK для платформы Bufpplugin. В настоящее время bufplugin-go предоставляет пакеты проверки, проверки и проверки, чтобы сделать его простыми для автора и тестирования настраиваемых плагинов Lint и нарушения изменений. Он охватывает API bufplugin PluginRpc-GO в простых в использовании интерфейсах и концепциях, которые организуются вокруг стандартного API ProToreflect, которые поддерживают большую часть экосистемы GO Protobuf. bufplugin-go также является платформой, которую команда BUF использует для создания всех правил Lintin Lint и нарушения изменений в CLI BUF-мы позаботились о том, чтобы bufplugin-go достаточно мощный, чтобы представлять самые сложные правила Lint и нарушение изменений сохраняя это как можно проще для использования. Если вы хотите сегодня создать плагин с ворсом или нарушать изменения, вам следует использовать bufplugin-go .

Использовать

Плагин - это просто двоичный файл в вашей системе, который реализует API Bufplugin. После того, как вы установили плагин, просто добавьте на него ссылку и его правила в вашем buf.yaml . Например, если вы установили плагин Buf-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 и использовать // 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)

Примеры

В этом случае примеры стоят тысячи слов, и мы рекомендуем вам прочитать примеры в проверке/Internal/Пример/CMD, чтобы начать:

• Buf-Plugin-timestamp-suffix: простой плагин, который реализует одно правило Lint, 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 и правило разбитого изменения FIELD_OPTION_SAFE_FOR_ML_STAYS_TRUE , оба принадлежащие к категории FIELD_OPTION_SAFE_FOR_ML . Это обеспечивает соблюдение свойств вокруг примера пользовательской опции acme.option.v1.safe_for_ml , предназначенного для обозначения того, безопасно ли поле для использования в моделях ML. Организация может захотеть сказать, что все поля должны быть явно обозначены как безопасные или небезопасные во всех их схемах, и никакие поля не изменяются от безопасных на небезопасно. Этот плагин обеспечит соблюдение этой организации. В примере отображается реализация нескольких правил, классифицировать их и учитывать пользовательские значения опции.
• Упомянутый Buf-Plugin-Syntax: простой плагин, который реализует одно правило Lint, PLUGIN_SYNTAX_SPECIFIED , который проверяет, что все файлы имеют явное объявление syntax . Это демонстрирует использование дополнительных метаданных, присутствующих в API bufplugin помимо того, что предоставляет FileDescriptorProto .

Все эти примеры имеют реализацию плагина main.go и тестовый файл main_test.go , который использует пакет checktest для проверки поведения плагина. В пакете checktest используется протокомпиляция для составления теста .proto Files на лету, запустите их с вашими правилами и сравнивает полученные аннотации с ожиданиями.

Вот краткий пример реализации плагина - это все, что нужно:

 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 года. Однако мы считаем, что API находится рядом с его окончательной формой.

Юридический

Предлагается по лицензии Apache 2.