在golang语言中简单使用protobuf时遭遇go_package困难重重

发表于 | 更新于 | 分类于 |
热度 ℃   |   字数统计: 2,141(字)   |   阅读时长: 9(分) |

前言

Protobuf，全称Protocol Buffers，是一种由Google开发的用于序列化结构化数据的开源数据交换格式，Golang作为一种后端语言，免不了使用protobuf这种数据交换格式，本来打算写个小例子展示一下怎样在go语言中使用protobuf，结果遇到的问题到不少，特别是这个go_package的要求，也是之前在项目开发过程中遇到的，这次就查找一下具体原因以及怎么使用吧。

编写示例

为了能对这个示例有一个整体的轮廓，我先把编写好的目录结构展示一下，后面再逐步实现

1
2
3
4
5
6
7
8
9
$ tree lib_protobuf
lib_protobuf
├── go.mod
├── go.sum
├── lib_protobuf.go
├── msgproto
│   └── examplemsg.pb.go
└── srcproto
    └── examplemsg.proto

简单解释下，examplemsg.proto proto源文件，examplemsg.pb.go 是proto导出文件，lib_protobuf.go 是proto协议使用和测试文件

示例初始化

执行下面的命令，创建示例基础目录文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
$ mkdir lib_protobuf
$ cd lib_protobuf
$ mkdir srcproto
$ touch srcproto/examplremsg.proto
$ touch lib_protobuf.go
$ go mod init lib_protobuf
go: creating new go.mod: module lib_protobuf
go: to add module requirements and sums:
        go mod tidy

$ go mod tidy
$ ls
go.mod  lib_protobuf.go  srcproto

编写协议文件内容

先编写proto文件，文件内容如下：

1
2
3
4
5
6
7
syntax = "proto3";

message Person {
    string name = 1;
    int32 age = 2;
    repeated string hobbies = 3;
}

这个协议文件只定义了一个名为 Person 的结构，其中包括 name 、age、hobbies 三个字段

导出协议文件

这是本文的重点，至于怎么用proto文件定义结构，各个语言都是相通的，但是在导出时遇到 go_package 文件却是 golang 语言特有的，所以本文重点在这部分多花些篇幅，解释一下遇到的各种问题

protoc 和 protoc-gen-go

导出时需要是使用工具 protoc，而平时你可能听说过或者在.pb.go文件中看到过 protoc-gen-go 这个工具的名字，其实 protoc-gen-go 是一个用于生成 Go 代码的插件，它是 Protocol Buffers 编译器 protoc 的一部分。当您使用 protoc 编译 .proto 文件时，可以通过指定 --go_out 标志来指定要使用的 protoc-gen-go 插件，从而生成对应的 Go 代码文件。这个插件会根据 .proto 文件中定义的消息和服务等内容，生成与之对应的 Go 结构体、接口和方法等代码。因此，protoc-gen-go 和 protoc 是紧密相关的，它们共同用于将 Protocol Buffers 文件编译为 Go 语言中的数据结构和服务定义。

执行导出命令

使用protoc将proto文件导出golang可用的文件最重要的两个参数如下：

--proto_path：proto源文件所在文件夹
--go_out：proto文件导出的目标文件夹

执行命令如下：

1
2
3
4
5
6
7
8
9
10
11
$ cd lib_protobuf
$ protoc --proto_path=srcproto --go_out=. examplemsg.proto
protoc-gen-go: unable to determine Go import path for "examplemsg.proto"

Please specify either:
        • a "go_package" option in the .proto source file, or
        • a "M" argument on the command line.

See https://developers.google.com/protocol-buffers/docs/reference/go-generated#package for more information.

--go_out: protoc-gen-go: Plugin failed with status code 1.

不出意外的果然出意外了，告诉我不能确定 examplemsg.proto 文件的导入路径，换句话说就是现在这样不能导出一个可以被正常导入的包，有两种解决办法，第一种就是在.proto文件中添加 go_package 选项，第二种是在执行导出的命令行中添加M参数，详细的解释参考链接 https://developers.google.com/protocol-buffers/docs/reference/go-generated#package

官方推荐是用第一种方式，也就是直接在.proto文件中添加 go_package 选项，假如我们这样写：

1
option go_package = "msgproto";

然后直接导出会遇到新的错误，提示”msgproto”并不是文件”examplemsg.proto”的一个有效的导入路径

1
2
3
4
5
6
7
8
$ protoc --proto_path=srcproto --go_out=. examplemsg.proto
protoc-gen-go: invalid Go import path "msgproto" for "examplemsg.proto"

The import path must contain at least one period ('.') or forward slash ('/') character.

See https://developers.google.com/protocol-buffers/docs/reference/go-generated#package for more information.

--go_out: protoc-gen-go: Plugin failed with status code 1.

要求必须至少包含一个 . 或者 /，那么把选项改成下面这样就可以了

1
option go_package = "./msgproto";

有时为了在当前目录下生成，又要指定包名，可以写成这样：

1
option go_package = "./;msgproto";

使用分号将包路径和包名分开，但这种方法官方并不推荐，因为按照golang的包管理习惯，文件夹下的所有文件包名应该与文件名相同，通过包的路径能够推测是包名才对，否则写成 option go_package = "./msgprotoA;msgprotoB"; 就很奇怪了

关于go_package至少包含一个 . 或者 /的要求，据说v1.4.0以上的版本就要求必须加/了，最近查了一些资料，解释如下：

在 Protocol Buffers（Protobuf）中，go_package 选项用于指定生成的 Go 代码的包名和导入路径。要求导入路径（import path）必须包含至少一个点（.）或正斜杠（/）的原因与 Go 语言的模块系统和包导入机制有关

这个要求是因为在导出时，protoc 需要能够将生成的代码文件放置在文件系统的适当位置，并且需要能够以合适的包路径来导入这些生成的代码。在大多数情况下，包路径应该具有与文件系统路径相对应的结构，因此至少需要包含一个句点（.）或正斜杠（/）字符来指示层次结构。

如果导入路径不包含这些字符，那么生成的代码文件将无法以合适的方式组织和导入，可能会导致编译器无法正确识别代码的位置和包结构。因此，为了确保生成的代码能够被正确导入和使用，protoc 对导入路径设置了这个最低要求。

但是我觉得这个解释不能让人信服，我把go_package的值写成 .msgproto、msgproto. 或者 ..msgproto 都是能正常导出的，并没有看到这种限制的好处，其中深层次的原因还得在今后的使用过程中慢慢体会了

编写协议使用文件

在文件 lib_protobuf.go 中编写如下内容，执行 go mod tidy 和 go run . 查看输出结果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
package main

import (
   "fmt"
   "log"

   msg "lib_protobuf/msgproto"

   "google.golang.org/protobuf/proto"
)

func main() {
   p := &msg.Person{
      Name:    "Alice",
      Age:     30,
      Hobbies: []string{"reading", "running"},
   }

   // 序列化
   data, err := proto.Marshal(p)
   if err != nil {
      log.Fatalf("Failed to encode person: %v", err)
   }

   // 反序列化
   newP := &msg.Person{}
   err = proto.Unmarshal(data, newP)
   if err != nil {
      log.Fatalf("Failed to decode person: %v", err)
   }

   fmt.Println("Original Person:", p)
   fmt.Println("Decoded Person:", newP)
}
1
2
3
$ go run .
Original Person: name:"Alice"  age:30  hobbies:"reading"  hobbies:"running"
Decoded Person: name:"Alice"  age:30  hobbies:"reading"  hobbies:"running"

体会

有关 go_package 值官方给出的示例是这种 example.com/project/protos/fizz，这就跟go.mod文件中的module定义一样，比如 module github.com/tealeg/xlsx 或 module github.com/peterbourgon/diskv/v3，提供的是一种导出之后的引用写法

但是 go_package 和 module 还确实有一些不同，因为它在导出时真的会根据 go_package 生成相应的路径，所以针对这些去情况我觉得一种比较好的写法是从项目根目录开始写，导出的目录也是根目录，这样在引用时直接写 go_package 就可以了，但是具体情况还需灵活应对

1
option go_package = "lib_protobuf/msgproto";
1
2
$ lib_protobuf
$ protoc --proto_path=srcproto --go_out=.. examplemsg.proto
1
2
3
4
5
6
7
8
import (
   "fmt"
   "log"

   msg "lib_protobuf/msgproto"

   "google.golang.org/protobuf/proto"
)

总结

  • Protobuf是一种由Google开发的用于序列化结构化数据的开源数据交换格式
  • 使用protoc 工具可以将 .proto 文件导出成golang可用的数据交换文件
  • protoc-gen-go 是一个用于生成 Go 代码的插件，它是 Protocol Buffers 编译器 protoc 的一部分
  • .proto文件中的go_package选项的值至少需要包含一个 . 或者 /
  • go_package 的值官方给出的示例是这种类似module名的写法 example.com/project/protos/fizz
==>> 反爬链接，请勿点击，原地爆炸，概不负责！<<==

仰天大笑出门去，我辈岂是蓬蒿人。不好意思，我们绝大多数都是蓬蒿人，都是陪跑的NPC，只是在穷尽一生的努力想做一颗稍微不那么矮的蓬蒿而已~

2024-2-18 16:44:18

Albert Shi wechat
欢迎您扫一扫上面的微信公众号，订阅我的博客