buf

buf

La CLI buf es la mejor herramienta para trabajar con Protocol Buffers. Proporciona:

• Un linter que impone buenas opciones de diseño y estructura de API.
• Un detector de cambios importantes que impone la compatibilidad a nivel de código fuente o de cable.
• Un generador que invoca tus complementos basándose en plantillas configurables.
• Un formateador que formatea sus archivos Protobuf de acuerdo con los estándares de la industria.
• Integración con Buf Schema Registry, incluida la gestión total de dependencias.

Instalación

cerveza casera

Puedes instalar buf usando Homebrew (macOS o Linux):

brew install bufbuild/buf/buf

Esto instala:

• Los binarios buf , protoc-gen-buf-breaking y protoc-gen-buf-lint
• Scripts de finalización de Shell para Bash, Fish, Powershell y zsh

Otros métodos

Para conocer otros métodos de instalación, consulte nuestra documentación oficial, que cubre:

• Instalando buf a través de npm
• Instalación buf en Windows
• Usando buf como imagen de Docker
• Instalación como binario, desde un tarball y desde el código fuente a través de versiones de GitHub
• Verificación de versiones mediante una clave pública minisign

Uso

La interfaz de ayuda de Buf proporciona resúmenes de comandos e indicadores:

buf --help

Para obtener información de uso más completa, consulte la documentación de Buf, especialmente estas guías:

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

Política de cambios importantes de CLI

Nunca realizaremos cambios importantes dentro de una versión principal determinada de la CLI. Después de que buf alcanzó la versión 1.0, no puede esperar cambios importantes hasta la versión 2.0. Pero como no tenemos planes de lanzar una versión 2.0, probablemente nunca romperemos la CLI buf .

Esta política de cambios importantes no se aplica a los comandos detrás de la puerta buf beta , y debe esperar cambios importantes en comandos como buf beta registry . Sin embargo, la política entra en vigor cuando esos comandos o indicadores salen de la versión beta.

Nuestros objetivos para Protobuf

El objetivo de Buf es reemplazar el paradigma actual de desarrollo de API, centrado en REST/JSON, con un paradigma basado en esquemas . Definir API utilizando un IDL proporciona numerosos beneficios sobre REST/JSON, y Protobuf es, con diferencia, el IDL más estable y ampliamente adoptado en la industria. Hemos elegido construir sobre esta base ampliamente confiable en lugar de crear un nuevo IDL desde cero.

Pero a pesar de sus méritos técnicos, utilizar Protobuf ha sido durante mucho tiempo más desafiante de lo necesario. Buf CLI y BSR son las piedras angulares de nuestro esfuerzo por cambiar eso para siempre y hacer que Protobuf sea confiable y fácil de usar tanto para los propietarios de servicios como para los clientes; en otras palabras, crear un ecosistema de Protobuf moderno .

Si bien tenemos la intención de mejorar gradualmente la CLI buf y el BSR, confiamos en que ya se han establecido las bases básicas para dicho ecosistema.

El registro del esquema Buf

Buf Schema Registry (BSR) es una plataforma SaaS para administrar sus API de Protobuf. Proporciona un registro centralizado y una única fuente de confianza para todos sus activos de Protobuf, incluidos no sólo sus archivos .proto sino también los complementos remotos. Aunque BSR proporciona una interfaz de usuario intuitiva para el navegador, buf le permite realizar la mayoría de las tareas relacionadas con BSR desde la línea de comandos, como enviar fuentes de Protobuf al registro y administrar usuarios y repositorios.

No es necesario que el BSR utilice buf . Hemos puesto las funciones principales de la CLI buf a disposición de todos los usuarios de Protobuf.

Funciones CLI más avanzadas

Si bien las funciones principales de buf deberían cubrir la mayoría de los casos de uso, hemos incluido algunas funciones más avanzadas para cubrir los casos extremos:

• Descubrimiento automático de archivos . Buf recorre su árbol de archivos y construye sus archivos .proto de acuerdo con la configuración de compilación proporcionada, lo que significa que ya no necesita especificar --proto_paths manualmente. Sin embargo, aún puede especificar archivos .proto manualmente a través de indicadores CLI en los casos en que sea necesario deshabilitar la detección de archivos.
• Configuración de reglas detalladas para cambios de linting y ruptura. Si bien tenemos valores predeterminados recomendados, siempre puede seleccionar el conjunto exacto de reglas que requiere su caso de uso, con 40 reglas de pelusa y 53 reglas de cambios importantes disponibles.
• Formatos de error configurables para salida CLI. buf genera información en file:line:column:message de forma predeterminada para cada error de pelusa y cambio importante que encuentra, pero también puede seleccionar la salida de acciones JSON, MSVS, JUnit y Github.
• Integración del editor impulsada por la salida de error granular de buf . Actualmente ofrecemos integraciones de linting para Vim y Visual Studio Code y IDE de JetBrains como IntelliJ y GoLand, pero planeamos admitir otros editores como Emacs en el futuro.
• Orientación por entrada universal . Buf le permite realizar acciones como linting y detección de cambios no solo en archivos .proto locales sino también en una amplia gama de otras entradas, como archivos tarball y ZIP, repositorios Git remotos y archivos de imágenes prediseñados.
• Velocidad . El compilador interno de Protobuf de Buf compila sus fuentes de Protobuf utilizando todos los núcleos disponibles sin comprometer la salida determinista, que es considerablemente más rápida que protoc . Esto permite recibir comentarios casi instantáneos, lo cual es de especial importancia para funciones como la integración del editor.

Próximos pasos

Una vez que haya instalado buf , le recomendamos completar el tutorial de CLI, que proporciona una descripción general amplia pero práctica de la funcionalidad principal de CLI. El recorrido dura unos 10 minutos en completarse.

Después de completar el recorrido, consulte el resto de los documentos para sus áreas de interés específicas.

Comunidad

Para obtener ayuda y debates sobre Protobuf, mejores prácticas y más, únete a nosotros en Slack.

Para obtener actualizaciones sobre Buf CLI, siga este repositorio en GitHub.

Para solicitudes de funciones, errores o preguntas técnicas, envíenos un correo electrónico a [email protected]. Para consultas generales o inclusión en nuestras próximas versiones beta de funciones, envíenos un correo electrónico a [email protected].