Protofetch

Protobuf 文件的源依赖管理工具。

动机

如果你广泛使用 protobuf 作为服务之间通信的数据格式，或者用于与外部世界共享你的 API，你需要一种方式来获取每个服务的正确版本的 protobuf 文件，并能够依赖于特定版本。这既需要在服务器端，也需要在客户端。没有自动化，这很快就会变得繁琐、易出错，并且总体上难以管理。

为了使其变得可忍受、可用且稳定，需要工具来自动化这项工作并使其可预测。这正是 Protofetch 所追求的。

为什么选择 Protofetch？

Protofetch 致力于以声明式方式处理 protobuf 依赖的复杂性。它使得声明依赖关系和管理它们变得非常简单。

它为你提供了以下能力：

• 依赖特定版本/哈希；
• 依赖于 protobuf 的可预测的构建/测试/CI；
• 易于阅读的 protobuf 依赖的声明性规范；
• 自动化获取依赖及其传递依赖；
• 缓存依赖，以便在多个项目中共享。

路线图

此项目仍在开发中，未来可能会有所变化。我们希望在发布第一个稳定版本之前实现以下目标。

• 根据 git 标签或分支获取依赖；
• 通过修订版本地缓存依赖；
• 获取传递依赖；
• 每个依赖的声明性规则；
  • 允许策略；
  • 拒绝策略；
  • 依赖剪枝（删除不需要的 proto 文件）；
• 防止循环依赖；

入门

您可以从 GitHub 发布页面 下载预构建的二进制文件。

Protofetch 也已发布到 crates.io，因此如果您已安装 Rust 工具链，则可以使用以下命令从源代码构建 Protofetch：cargo install protofetch。

使用方法

# Fetch proto sources, updating the lock file if needed.
protofetch fetch
   
# Verify the lock file, and fetch proto sources. Useful for CI.
protofetch fetch --locked

Protofetch 模块

使用 protofetch 的每个服务都需要一个模块描述符，该描述符使用 toml 格式。此描述符默认称为 protofetch.toml，位于服务存储库的根目录。这可以更改，但强烈不建议更改。

依赖项格式

Protofetch 依赖项 toml 示例

name = "repository name"
description = "this is a repository"

[dep1]
url = "github.com/org/dep1"
protocol = "https"
revision = "1.3.0"
prune = true
allow_policies = ["/prefix/*", "*/subpath/*", "/path/to/file.proto"]

[dep2]
url = "github.com/org/dep2"
protocol = "ssh"
branch = "feature/v2"

[another-name]
protocol = "ssh"
url = "github.com/org/dep3"
revision = "a16f097eab6e64f2b711fd4b977e610791376223"
transitive = true

Git 协议

Protofetch 支持使用 ssh 或 https 访问 Git 存储库。默认情况下，Protofetch 使用 ssh。您可以使用环境变量 PROTOFETCH_GIT_PROTOCOL 配置默认 Git 协议。

您也可以在 protofetch.toml 中设置协议，但仅在 Git 服务器不支持两种协议的情况下才需要这样做。否则，最好留空此字段，让用户选择他们想要的任何协议。

SSH 支持

您需要一个运行的 SSH 代理，并加载了您的 SSH 密钥

ssh-add ~/.ssh/your-private-key

HTTPS 支持

如果您想使用 https，则需要配置 git 使用 credentials helper。

要支持启用 2FA 时的 https，您必须生成一个个人访问令牌并将其设置为密码。在创建令牌时，以下权限是足够的。

传递依赖项支持和修剪

Protofetch 支持方便地拉取传递依赖项。但是，如果依赖项没有定义自己的 protofetch 模块，则需要一些手动工作。

在 A 依赖于 B 的情况下，您应该将此依赖项标记为传递依赖。

这特别有用，尤其是当您利用修剪功能，这允许您仅递归地获取您实际需要的 proto 文件。启用修剪后，protofetch 将递归地找到您的根 proto 依赖的哪些 proto 文件，并获取它们，只要它们被导入（标记为传递依赖项或从其他模块获取）。

此外，您还可以使用 allow_policies 限制从依赖项获取的根 proto 文件。例如，以下模块仅依赖于 A 的文件 /proto/path/example.proto，但由于修剪已启用且 B 已标记为传递依赖，如果允许的文件有任何文件依赖项，它将递归地拉取它们及其依赖项。

重要：如果您使用 prune 功能，也必须使用 transitive 功能。但是，除非您确实需要拉取传递依赖，否则请勿使用 transitive。这是针对没有在其仓库上定义 protofetch 文件的依赖项的解决方案。

name = "repository name"
description = "this is a repository"
proto_out_dir = "proto/src/dir/output"

[A]
protocol = "https"
url = "github.com/org/A"
revision = "1.3.0"
allow_policies = ["/proto/path/example.proto"]
prune = true

[B]
protocol = "ssh"
url = "github.com/org/B"
revision = "5.2.0"
transitive = true