铺垫
Protobuf文件的源依赖管理工具.
动机
如果您广泛使用原生生物作为服务的数据格式,与外界通信或分享你的API, 您需要一个方法为每个服务获取正确的原生文件版本,并且能够依赖特定版本. 服务器和客户端都需要这样做. 没有自动化,它可以很快地变得繁琐,容易出错,而且整体上无法管理.
要使它具有可承受性、可用性和稳定性,就需要工具化,使这项工作自动化并具有可预测性。 这就是Protofetch的目的.
为什么是Protofetch?
Protofetch旨在以宣示方式处理原生生物依赖的复杂性. 宣布依赖关系和管理依赖关系是微不足道的.
它让你有能力拥有:
- 依赖特定版本/小时;
- 依靠原生取料的可预见建筑/试验/碳化物;
- 易读取原生生物依赖性的声明性说明;
- 自动获取依赖本身及其过渡性依赖.
- 缓存依赖关系,以便能够在多个项目中共享.
路线图
这个项目仍在发展之中,今后可能会有变化. 我们的目标是在发布第一个稳定版本之前至少实现以下目标.
- 基于 git 标记或分支获取依赖性
- 通过修订本地缓存依赖性
- 获取过渡性依赖性
- 每个受扶养人申报规则
- 允许政策
- 拒绝政策
- 依赖性修剪( 移除)
proto不需要的文件)
- 防止循环依赖
开始
无 :
npm install @coralogix/protofetch
货物 :
Protofetch也被释放到 货箱.io,所以如果安装了 Rust 工具链,可以从源代码中构建Protofetch:
cargo install protofetch
预建二进制 :
您可以下载预建的二进制 GitHub 发布 页 次.
使用量
# 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
# Validate dependencies against their source repositories and reconcile the lock file.
protofetch lock
# Update all locked dependencies.
protofetch update
# Update only selected dependencies.
protofetch update module-a module-b
# Update one dependency to an exact commit.
protofetch update module-a --precise abc123
fetch 使用不与源寄存器联系的缓存锁定承诺 。 它会回收
需要时缺少依赖关系. lock 财务报告和审定财务报表 update 刷新远程校对并验证
分支和修订限制,即使承诺被缓存. lock 保持现有
有锁的,如果有效; update 为所有或选定的依赖选择新承诺.
Protofetch模块
使用前缀的每个服务需要使用模块描述符 toml 格式.
此描述符默认为 protofetch.toml 并位于服务库的根.
这一点是可以改变的,但令人十分沮丧.
| 外地 | 类型 | 需求 | 说明 |
|---|---|---|---|
| 名称 | 字符串 | 强制性 | 定义模块的名称 |
| 说明 | 字符串 | 可选 | 模块说明 |
| 依赖关系 | [依赖 | 可选 | 要获取的依赖性 |
依赖性格式
| 外地 | 类型 | 需求 | 说明 | 示例 |
|---|---|---|---|---|
| url 密码 | 字符串 | 强制性 | 用于检查 protobuf 文件的仓库地址 | "github.com/coralogix/cx-api-users/" |
| 订正 | 字符串 | 可选 | 修改后退出, 可以是标记版本或承诺散列 | v0.2 |
| 分支 | 布尔 | 可选 | 要退职的分行, 获取最后的承诺 | feature/v2 |
| 协议 | 字符串 | 可选 | 要使用的协议 : [sh, https] | ssh |
| 允许政策 | [打 | 可选 | 允许政策规则(* 开头或结尾匹配任意目录深度) | "/prefix/*", (中文(简体) ), "*/subpath/*", (中文(简体) ), "/path/to/file.proto" |
| 否定政策( d) | [打 | 可选 | 拒绝政策规则* 开头或结尾匹配任意目录深度) | "/prefix/*", (中文(简体) ), "*/subpath/*", (中文(简体) ), "/path/to/file.proto" |
| 棱镜 | 嘘 | 可选 | 是否仅通过模块依赖来跟踪原型导入而不是复制 | true 编号 : false |
| 过渡 | 嘘 | 可选 | 标出此依赖性为过渡性 | true 编号 : false |
| 内容( b) | [打 | 可选 | 要导入的子目录 | ["/myservice", "/com/org/client"] |
若为 revision 是一个标签和 branch 被设定,标记的承诺必须属于该分支.
若为 revision 承诺必须属于 branch,或者如果 branch 未设置.
允许和拒绝政策
模式 allow_policies 财务报告和审定财务报表 deny_policies 与最近的路径相匹配 content_roots。 。 。 .
allow_policies 仅适用于它们被定义的依赖性,并描述您想要从依赖性中获取的原始文件.
何时 prune = false,只包含匹配的原生文件.
何时 prune = true,匹配的原生文件被用作倒转根: 原生文件跟随原生文件 import 跨模块依赖关系的语句,可能包括从同一模块导入的额外文件,也可能包括从依赖子树导入的文件.
deny_policies 适用于整个依赖子树.
何时 prune = false,不包括匹配的原生文件.
何时 prune = true,不包括匹配原生文件及其导入树.
依赖性循环
Pruning 特性使 protofetch 跟随 proto 文件
import 语句而不是只从模块级依赖关系复制文件。 有了螺旋,
protoft 从包含的文件开始 allow_policies,并按模块依赖性逐一跟踪其进口情况,
并获取每个导入的原始文件。 此 traversal 可能包含来自同一模块的额外文件, 即使
他们没有直接匹配 allow_policies,并可能包括从依赖子树导入的原生文件.
额外的过渡性依赖
启动 pruning 时, protofetch 在模块依赖树中查找导入的 proto 文件 .
这取决于每个依赖在a/ protofetch.toml 文档。 如果有受扶养人
不提供一条, 您仍可使用 pruning 特性, 通过声明额外的依赖性 transitive = true。 。 。 .
不直接取出来自过渡依赖的文件 。 它们是作为候选人提供的,只有在
import 由被压迫的依赖而来.
Protofetch 依赖toml 实例
name = "repository name"
description = "this is a repository"
[dep1]
url = "github.com/org/dep1"
revision = "1.3.0"
prune = true
allow_policies = ["/prefix/*", "*/subpath/*", "/path/to/file.proto"]
[dep2]
url = "github.com/org/dep2"
branch = "feature/v2"
[another-name]
url = "github.com/org/dep3"
revision = "a16f097eab6e64f2b711fd4b977e610791376223"
transitive = true
[scoped-down-dep4]
url = "github.com/org/dep4"
revision = "v1.1"
content_roots = ["/scope/path"]
allow_policies = ["prefix/subpath/scoped_path/*"]
Git 协议
Protofetch 支持使用 Git 仓库访问 ssh 或者说 https默认情况下, Protofetch 用途 ssh。您可以用 PROTOFETCH_GIT_PROTOCOL 环境变量.
也可以将协议设置在 protofetch.toml,但这只有在 Git 服务器不支持两个协议时才有必要。 否则,最好不要设置这个字段,让用户选择他们喜欢的任何协议.
SSH 支持
您需要运行一个 SSH 代理, 并加载您的 SSH 密钥 :
ssh-add ~/.ssh/your-private-key
HTTPS 支持
如果您想要使用 https, 您需要配置 git 来使用 证书助手。 。 。 .
支持 https 当 2FA 启用时,您必须生成个人访问符并设定为密码.
以下权限在创建符时已足够 .
范围降低多API repo
对于支持多个API的回波,但只需要特定的目录,即组合 content_roots 财务报告和审定财务报表 allow_policies 可以使用.
例如: dep4 repo包含以下内容:
dep4
├── scope
│ ├── path1
│ └── path2
└── scope2
└── unrelated
我们只需要原始文件 dep4/scope/path1时 path1 是软件包名称.
[scoped-down-dep4]
url = "github.com/org/dep4"
revision = "v1.1"
content_roots = ["/scope"]
allow_policies = ["path1/*"]