buf

Buf

La CLI buf est le meilleur outil pour travailler avec les tampons de protocole. Il fournit :

• Un linter qui applique de bons choix et une bonne structure de conception d'API.
• Un détecteur de changement avec rupture qui applique la compatibilité au niveau du code source ou du fil.
• Un générateur qui appelle vos plugins en fonction de modèles configurables.
• Un formateur qui formate vos fichiers Protobuf conformément aux normes de l'industrie.
• Intégration avec le Buf Schema Registry, y compris la gestion complète des dépendances.

Installation

Homebrew

Vous pouvez installer buf en utilisant Homebrew (macOS ou Linux) :

brew install bufbuild/buf/buf

Cela installe :

• Les binaires buf , protoc-gen-buf-breaking et protoc-gen-buf-lint
• Scripts de complétion Shell pour Bash, Fish, Powershell et zsh

Autres méthodes

Pour d'autres méthodes d'installation, consultez notre documentation officielle, qui couvre :

• Installer buf via npm
• Installer buf sous Windows
• Utiliser buf comme image Docker
• Installation en tant que binaire, à partir d'une archive tar et à partir des sources via les versions GitHub
• Vérifier les versions à l'aide d'une clé publique minisign

Usage

L'interface d'aide de Buf fournit des résumés des commandes et des indicateurs :

buf --help

Pour des informations d'utilisation plus complètes, consultez la documentation de Buf, en particulier ces guides :

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (pour utiliser le BSR)

Politique de changement de rupture CLI

Nous n’apporterons jamais de modifications majeures dans une version majeure donnée de la CLI. Une fois que buf a atteint la version 1.0, vous ne pouvez vous attendre à aucun changement majeur avant la version 2.0. Mais comme nous n’avons pas l’intention de publier une version 2.0, nous ne briserons probablement jamais la CLI buf .

Cette politique de modification avec rupture ne s'applique pas aux commandes derrière la porte buf beta , et vous devez vous attendre à des modifications avec rupture dans des commandes telles que buf beta registry . Cependant, la politique entre en vigueur lorsque ces commandes ou indicateurs sortent de la version bêta.

Nos objectifs pour Protobuf

L'objectif de Buf est de remplacer le paradigme actuel de développement d'API, centré autour de REST/JSON, par un paradigme basé sur des schémas . La définition d'API à l'aide d'un IDL offre de nombreux avantages par rapport à REST/JSON, et Protobuf est de loin l'IDL le plus stable et le plus largement adopté du secteur. Nous avons choisi de nous appuyer sur cette base largement reconnue plutôt que de créer un nouvel IDL à partir de zéro.

Mais malgré ses mérites techniques, l’ utilisation de Protobuf s’avère depuis longtemps plus difficile qu’elle ne devrait l’être. La CLI Buf et le BSR sont les pierres angulaires de nos efforts visant à changer cela pour de bon et à rendre Protobuf fiable et facile à utiliser pour les propriétaires de services et les clients, en d'autres termes, pour créer un écosystème Protobuf moderne .

Même si nous avons l'intention d'améliorer progressivement le buf CLI et le BSR, nous sommes convaincus que les bases d'un tel écosystème sont déjà en place.

Le registre de schémas Buf

Le Buf Schema Registry (BSR) est une plateforme SaaS pour gérer vos API Protobuf. Il fournit un registre centralisé et une source unique de vérité pour tous vos actifs Protobuf, y compris non seulement vos fichiers .proto mais également les plugins distants. Bien que BSR fournisse une interface utilisateur de navigateur intuitive, buf vous permet d'effectuer la plupart des tâches liées à BSR à partir de la ligne de commande, telles que le transfert des sources Protobuf vers le registre et la gestion des utilisateurs et des référentiels.

Le BSR n'est pas obligé d'utiliser buf . Nous avons mis les fonctionnalités de base de la CLI buf à la disposition de tous les utilisateurs de Protobuf.

Fonctionnalités CLI plus avancées

Bien que les fonctionnalités principales de buf devraient couvrir la plupart des cas d'utilisation, nous avons inclus des fonctionnalités plus avancées pour couvrir les cas extrêmes :

• Découverte automatique des fichiers . Buf parcourt votre arborescence de fichiers et construit vos fichiers .proto conformément à la configuration de construction fournie, ce qui signifie que vous n'avez plus besoin de spécifier manuellement --proto_paths . Cependant, vous pouvez toujours spécifier les fichiers .proto manuellement via les indicateurs CLI dans les cas où la découverte de fichiers doit être désactivée.
• Configuration de règles à granularité fine pour les modifications de peluchage et de rupture. Bien que nous ayons des valeurs par défaut recommandées, vous pouvez toujours sélectionner l'ensemble exact de règles requis par votre cas d'utilisation, avec 40 règles de charpie et 53 règles de modification cassante disponibles.
• Formats d'erreur configurables pour la sortie CLI. buf génère des informations sous file:line:column:message par défaut pour chaque erreur de charpie et modification importante rencontrée, mais vous pouvez également sélectionner la sortie JSON, MSVS, JUnit et Github Actions.
• Intégration de l'éditeur pilotée par la sortie d'erreur granulaire de buf . Nous proposons actuellement des intégrations de linting pour Vim et Visual Studio Code et les IDE JetBrains comme IntelliJ et GoLand, mais nous prévoyons de prendre en charge d'autres éditeurs tels qu'Emacs à l'avenir.
• Ciblage universel des entrées . Buf vous permet d'effectuer des actions telles que la détection des modifications de peluchage et de rupture, non seulement sur les fichiers .proto locaux, mais également sur un large éventail d'autres entrées, telles que les archives tar et les fichiers ZIP, les référentiels Git distants et les fichiers image prédéfinis.
• Vitesse . Le compilateur Protobuf interne de Buf compile vos sources Protobuf en utilisant tous les cœurs disponibles sans compromettre la sortie déterministe, qui est considérablement plus rapide que protoc . Cela permet un retour quasi instantané, ce qui revêt une importance particulière pour des fonctionnalités telles que l’intégration de l’éditeur.

Prochaines étapes

Une fois que vous avez installé buf , nous vous recommandons de suivre le didacticiel CLI, qui fournit un aperçu large mais pratique des fonctionnalités de base de la CLI. La visite dure environ 10 minutes.

Après avoir terminé la visite guidée, consultez le reste de la documentation correspondant à vos domaines d'intérêt spécifiques.

Communauté

Pour obtenir de l'aide et des discussions sur Protobuf, les meilleures pratiques et bien plus encore, rejoignez-nous sur Slack.

Pour les mises à jour sur la CLI Buf, suivez ce dépôt sur GitHub.

Pour les demandes de fonctionnalités, les bogues ou les questions techniques, envoyez-nous un e-mail à [email protected]. Pour des demandes générales ou une inclusion dans nos prochaines fonctionnalités bêta, envoyez-nous un e-mail à [email protected].