buf

Buf

O buf CLI é a melhor ferramenta para trabalhar com buffers de protocolo. Ele fornece:

• Um linter que impõe boas escolhas e estrutura de design de API.
• Um detector de alterações significativas que impõe compatibilidade no código-fonte ou no nível da conexão.
• Um gerador que invoca seus plugins com base em modelos configuráveis.
• Um formatador que formata seus arquivos Protobuf de acordo com os padrões da indústria.
• Integração com o Buf Schema Registry, incluindo gerenciamento completo de dependências.

Instalação

Cerveja caseira

Você pode instalar buf usando Homebrew (macOS ou Linux):

brew install bufbuild/buf/buf

Isso instala:

• Os binários buf , protoc-gen-buf-breaking e protoc-gen-buf-lint
• Scripts de conclusão de shell para Bash, Fish, Powershell e zsh

Outros métodos

Para outros métodos de instalação, consulte nossa documentação oficial, que abrange:

• Instalando buf via npm
• Instalando buf no Windows
• Usando buf como imagem Docker
• Instalando como binário, a partir de um tarball e da fonte por meio de versões do GitHub
• Verificando liberações usando uma chave pública minisign

Uso

A interface de ajuda do Buf fornece resumos de comandos e sinalizadores:

buf --help

Para obter informações de uso mais abrangentes, consulte a documentação do Buf, especialmente estes guias:

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (para usar o BSR)

Política de alteração significativa da CLI

Nunca faremos alterações significativas em uma determinada versão principal da CLI. Depois que buf atingiu a v1.0, você não pode esperar nenhuma alteração significativa até a v2.0. Mas como não temos planos de lançar uma versão 2.0, provavelmente nunca quebraremos a CLI buf .

Esta política de alterações significativas não se aplica a comandos por trás do buf beta gate, e você deve esperar alterações significativas em comandos como buf beta registry . A política entra em vigor, entretanto, quando esses comandos ou sinalizadores são retirados da versão beta.

Nossos objetivos para o Protobuf

O objetivo do Buf é substituir o paradigma atual de desenvolvimento de API, centrado em REST/JSON, por um paradigma orientado por esquema . Definir APIs usando um IDL oferece vários benefícios em relação ao REST/JSON, e o Protobuf é de longe o IDL mais estável e amplamente adotado no setor. Optamos por desenvolver essa base amplamente confiável em vez de criar um novo IDL do zero.

Mas, apesar de seus méritos técnicos, usar o Protobuf tem sido mais desafiador do que deveria ser. O Buf CLI e o BSR são os pilares do nosso esforço para mudar isso para sempre e tornar o Protobuf confiável e fácil de usar tanto para proprietários de serviços quanto para clientes – em outras palavras, para criar um ecossistema Protobuf moderno .

Embora pretendamos melhorar gradativamente o buf CLI e o BSR, estamos confiantes de que a base básica para tal ecossistema já está estabelecida.

O registro do esquema Buf

O Buf Schema Registry (BSR) é uma plataforma SaaS para gerenciar suas APIs Protobuf. Ele fornece um registro centralizado e uma única fonte de verdade para todos os seus ativos Protobuf, incluindo não apenas seus arquivos .proto , mas também plug-ins remotos. Embora o BSR forneça uma UI de navegador intuitiva, buf permite que você execute a maioria das tarefas relacionadas ao BSR a partir da linha de comando, como enviar fontes do Protobuf para o registro e gerenciar usuários e repositórios.

O BSR não é obrigado a usar buf . Disponibilizamos os principais recursos da CLI buf para todos os usuários do Protobuf.

Recursos CLI mais avançados

Embora os recursos principais do buf devam cobrir a maioria dos casos de uso, incluímos alguns recursos mais avançados para cobrir casos extremos:

• Descoberta automática de arquivos . Buf percorre sua árvore de arquivos e cria seus arquivos .proto de acordo com a configuração de compilação fornecida, o que significa que você não precisa mais especificar manualmente --proto_paths . No entanto, você ainda pode especificar arquivos .proto manualmente por meio de sinalizadores CLI nos casos em que a descoberta de arquivos precisa ser desabilitada.
• Configuração de regras refinadas para linting e quebra de alterações. Embora tenhamos padrões recomendados, você sempre pode selecionar o conjunto exato de regras que seu caso de uso exige, com 40 regras de lint e 53 regras de alteração significativa disponíveis.
• Formatos de erro configuráveis ​​para saída CLI. buf gera informações no file:line:column:message por padrão para cada erro de lint e alteração significativa que encontra, mas você também pode selecionar a saída JSON, MSVS, JUnit e Github Actions.
• Integração do editor impulsionada pela saída de erro granular de buf . Atualmente, fornecemos integrações de linting para Vim e Visual Studio Code e IDEs JetBrains, como IntelliJ e GoLand, mas planejamos oferecer suporte a outros editores, como Emacs, no futuro.
• Segmentação por entrada universal . Buf permite que você execute ações como linting e detecção de alterações interrompidas não apenas em arquivos .proto locais, mas também em uma ampla variedade de outras entradas, como tarballs e arquivos ZIP, repositórios Git remotos e arquivos de imagem pré-construídos.
• Velocidade . O compilador Protobuf interno do Buf compila suas fontes Protobuf usando todos os núcleos disponíveis sem comprometer a saída determinística, que é consideravelmente mais rápida que protoc . Isso permite feedback quase instantâneo, o que é de especial importância para recursos como integração de editores.

Próximas etapas

Depois de instalar buf , recomendamos concluir o tutorial da CLI, que fornece uma visão geral ampla, mas prática, da funcionalidade principal da CLI. O passeio leva cerca de 10 minutos para ser concluído.

Depois de concluir o tour, confira o restante da documentação para suas áreas específicas de interesse.

Comunidade

Para obter ajuda e discussão sobre Protobuf, práticas recomendadas e muito mais, junte-se a nós no Slack.

Para atualizações sobre o Buf CLI, siga este repositório no GitHub.

Para solicitações de recursos, bugs ou dúvidas técnicas, envie um email para [email protected]. Para dúvidas gerais ou inclusão em nossos próximos betas de recursos, envie um email para [email protected].