导入GitHub存储库中的protobuf文件

如何导入 GitHub 存储库中的 protobuf 文件？Protobuf 没有远程导入路径的本机概念，因此导入路径必须相对于指示的本地文件系统基本路径。通常，最简单的方法是为您的组织创建一个包含 protobuf 定义的存储库，并将导入路径设置为相对于该存储库的 protos/ 目录。另一种选择是使用 buf，它可以通过 go 模块导入生成的 pb 代码，或者将所有代码生成到单独的存储库中。

我目前有两个 protobuf 存储库：api 和 timestamp：

时间戳存储库：

- readme.md
- timestamp.proto
- timestamp.pb.go
- go.mod
- go.sum

api 存储库：

- readme.md
- protos/
  - dto1.proto
  - dto2.proto

目前，timestamp 包含对我想在 api 中使用的时间戳对象的引用，但我不确定导入应该如何工作，或者应该如何修改编译过程来处理这个问题。让这个过程变得复杂的是，api 存储库被编译为 go 的一个单独的下游存储库，名为 api-go。

例如，考虑 dto1.proto：

syntax = "proto3";
package api.data;

import "<what goes here?>";

option go_package = "github.com/my-user/api/data"; // golang

message dto1 {
    string id = 1;
    timestamp timestamp = 2;
}

我的编译命令是这样的：

find $GEN_PROTO_DIR -type f -name "*.proto" -exec protoc \
    --go_out=$GEN_OUT_DIR --go_opt=module=github.com/my-user/api-go \
    --go-grpc_out=$GEN_OUT_DIR --go-grpc_opt=module=github.com/my-user/api-go \
    --grpc-gateway_out=$GEN_OUT_DIR --grpc-gateway_opt logtostderr=true \
    --grpc-gateway_opt paths=source_relative --grpc-gateway_opt 
    generate_unbound_methods=true \{} \;

假设我在 timestamp 中为我想要将 api 编译成的每种编程语言都有一个定义，我如何将其导入到 .proto 文件中以及我应该做什么来确保导入不会破坏我的下游回购？

正确答案

protobuf 没有远程导入路径的本机概念。因此导入路径必须相对于某些指示的本地文件系统基本路径（通过 -i / --proto_path 指定）。

选项 1

通常，最简单的方法是为您的组织创建一个包含 protobuf 定义的存储库 - 例如名为 acme-contract 的存储库

.
└── protos
    └── acme
        ├── api
        │   └── data
        │       ├── dto1.proto
        │       └── dto2.proto
        └── timestamp
            └── timestamp.proto

你的 dto1.proto 看起来像：

syntax = "proto3";

package acme.api.data;

import "acme/timestamp/timestamp.proto";

message dto1 {
  string id = 1;
  acme.timestamp.timestamp timestamp = 2;
}

只要生成与此存储库的 protos/ 目录相关的代码，就不应该有问题。

选项 2

有多种替代方案，您可以继续将定义拆分到不同的存储库中，但您无法真正逃避导入与文件系统相关的事实。

从历史上看，这可以通过手动克隆各种存储库并安排目录以使路径是相对的，或者使用 -i 指向可能有意或无意包含原始文件的各种位置（例如在 $gopath 中）来处理。这些策略最终往往会变得相当混乱且难以维护。

buf 现在让事情变得更容易了。如果您想要拥有 timestamp 存储库：

.
├── buf.gen.yaml
├── buf.work.yaml
├── gen
│   └── acme
│       └── timestamp
│           └── timestamp.pb.go
├── go.mod
├── go.sum
└── protos
    ├── acme
    │   └── timestamp
    │       └── timestamp.proto
    ├── buf.lock
    └── buf.yaml

timestamp.proto 看起来像：

syntax = "proto3";

package acme.timestamp;

option go_package = "github.com/my-user/timestamp/gen/acme/timestamp";

message timestamp {
  int64 unix = 1;
}

buf.gen.yaml 看起来像：

version: v1
plugins:
  - name: go
    out: gen
    opt: paths=source_relative
  - name: go-grpc
    out: gen
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false
  - name: grpc-gateway
    out: gen
    opt:
      - paths=source_relative
      - generate_unbound_methods=true

... gen/ 下的所有内容都是通过 bufgenerate 生成的。

然后在您的 api 存储库中：

.
├── buf.gen.yaml
├── buf.work.yaml
├── gen
│   └── acme
│       └── api
│           └── data
│               ├── dto1.pb.go
│               └── dto2.pb.go
└── protos
    ├── acme
    │   └── api
    │       └── data
    │           ├── dto1.proto
    │           └── dto2.proto
    ├── buf.lock
    └── buf.yaml

buf.yaml 看起来像：

version: v1
name: buf.build/your-user/api
deps:
  - buf.build/your-user/timestamp
breaking:
  use:
    - file
lint:
  use:
    - default

dto1.proto 看起来像：

syntax = "proto3";

package acme.api.data;

import "acme/timestamp/timestamp.proto";

option go_package = "github.com/your-user/api/gen/acme/api/data";

message dto1 {
  string id = 1;
  acme.timestamp.timestamp timestamp = 2;
}

和 buf.gen.yaml 与 timestamp 存储库中的相同。

通过 bufgenerate 生成的代码将依赖于通过 go 模块的 timestamp 存储库：

// code generated by protoc-gen-go. do not edit.
// versions:
//  protoc-gen-go v1.28.1
//  protoc        (unknown)
// source: acme/api/data/dto1.proto

package data

import (
    timestamp "github.com/your-user/timestamp/gen/acme/timestamp"
    protoreflect "google.golang.org/protobuf/reflect/protoreflect"
    protoimpl "google.golang.org/protobuf/runtime/protoimpl"
    reflect "reflect"
    sync "sync"
)

// <snip>

请注意，如果对依赖项进行更改，您需要确保 buf 和 go 模块保持相对同步。

选项 3

如果您不想利用 go 模块来导入生成的 pb 代码，您也可以寻找与 option 2 类似的设置，而是将所有代码生成到单独的存储库中（类似于从声音来看，你现在正在做的事情）。通过使用 buf 托管模式最容易实现这一点，这基本上使其不需要+忽略任何 go_modules 指令。

在 api-go 中：

.
├── buf.gen.yaml
├── go.mod
└── go.sum

buf.gen.yaml 包含：

version: v1
managed:
  enabled: true
  go_package_prefix:
    default: github.com/your-user/api-go/gen
plugins:
  - name: go
    out: gen
    opt: paths=source_relative
  - name: go-grpc
    out: gen
    opt:
      - paths=source_relative
      - require_unimplemented_servers=false
  - name: grpc-gateway
    out: gen
    opt:
      - paths=source_relative
      - generate_unbound_methods=true

然后，您需要为每个相应的存储库生成代码（布什到 bsr）：

$ buf generate buf.build/your-user/api
$ buf generate buf.build/your-user/timestamp

之后您应该为两者生成一些代码：

.
├── buf.gen.yaml
├── gen
│   └── acme
│       ├── api
│       │   └── data
│       │       ├── dto1.pb.go
│       │       └── dto2.pb.go
│       └── timestamp
│           └── timestamp.pb.go
├── go.mod
└── go.sum

导入将相对于当前模块：

// Code generated by protoc-gen-go. DO NOT EDIT.
// versions:
//  protoc-gen-go v1.28.1
//  protoc        (unknown)
// source: acme/api/data/dto1.proto

package data

import (
    timestamp "github.com/your-user/api-go/gen/acme/timestamp"
    protoreflect "google.golang.org/protobuf/reflect/protoreflect"
    protoimpl "google.golang.org/protobuf/runtime/protoimpl"
    reflect "reflect"
    sync "sync"
)

// <snip>

总而言之，我建议选择 1 - 将您的 protobuf 定义合并到单个存储库中（包括供应商第 3 方定义） - 除非有特别充分的理由不这样做。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《导入GitHub存储库中的protobuf文件》文章吧，也可关注golang学习网公众号了解相关技术文章。