生成代码参考

生成代码参考

本页介绍了使用 protoc 编译 .proto 文件时生成的代码,使用了 protoc-gen-go-grpc grpc 插件。这个最新版本的生成代码默认使用泛型。如果您正在使用不使用泛型的旧版本生成代码,您可以在此处找到相关文档。虽然我们鼓励使用这个最新的泛型版本,您可以通过将 useGenericStreams 标志设置为 false 来暂时恢复旧的行为。

您可以在服务定义中找到如何在 .proto 文件中定义 gRPC 服务的方法。

线程安全:请注意,客户端 RPC 调用和服务器端 RPC 处理程序是线程安全的,并且旨在在并发 goroutine 上运行。还要注意,对于单独的流,传入和传出的数据是双向的但串行的;因此,例如,单独的流不支持并发读取并发写入(但读取与写入是安全并发的)。

生成服务器接口的方法

在服务器端,.proto 文件中的每个 service Bar 都会产生函数

func RegisterBarServer(s *grpc.Server, srv BarServer)

应用程序可以定义 BarServer 接口的具体实现,并使用此函数将其注册到 grpc.Server 实例(在启动服务器实例之前)。

一元方法

这些方法在生成的服务接口上具有以下签名

Foo(context.Context, *RequestMsg) (*ResponseMsg, error)

在此上下文中,RequestMsg 是从客户端发送的 protobuf 消息,而 ResponseMsg 是从服务器发回的 protobuf 消息。

服务器流方法

这些方法在生成的服务接口上具有以下签名:Foo(*RequestMsg, grpc.ServerStreamingServer[*ResponseMsg]) error

在此上下文中, RequestMsg 是来自客户端的单个请求,grpc.ServerStreamingServer 表示服务器到客户端响应类型 ResponseMsg 流的服务器端。

有关详细用法信息,请参阅 grpc.ServerStreamingServer 文档。

客户端流方法

这些方法在生成的服务接口上具有以下签名

Foo(grpc.ClientStreamingServer[*RequestMsg, *ResponseMsg]) error

其中 RequestMsg 是从客户端发送到服务器的流的消息类型,而 ResponseMsg 是从服务器到客户端的响应类型。

在此上下文中,grpc.ClientStreamingServer 既可以用来读取客户端到服务器的消息流,也可以用来发送单个服务器响应消息。

有关详细用法信息,请参阅 grpc.ClientStreamingServer 文档。

双向流方法

这些方法在生成的服务接口上具有以下签名

Foo(grpc.BidiStreamingServer[*RequestMsg, *ResponseMsg]) error

其中 RequestMsg 是从客户端发送到服务器的流的消息类型,而 ResponseMsg 是从服务器到客户端的流类型。

在此上下文中,grpc.BidiStreamingServer 可以用来访问客户端到服务器的消息流和服务器到客户端的消息流。

有关详细用法信息,请参阅 grpc.BidiStreamingServer 文档。

生成客户端接口的方法

对于客户端使用,.proto 文件中的每个 service Bar 也会产生函数: func BarClient(cc *grpc.ClientConn) BarClient,它返回 BarClient 接口的具体实现(此具体实现也位于生成的 .pb.go 文件中)。

一元方法

这些方法在生成的客户端 stub 上具有以下签名

(ctx context.Context, in *RequestMsg, opts ...grpc.CallOption) (*ResponseMsg, error)

在此上下文中,RequestMsg 是从客户端发送到服务器的单个请求,而 ResponseMsg 包含服务器发回的响应。

服务器流方法

这些方法在生成的客户端 stub 上具有以下签名

Foo(ctx context.Context, in *RequestMsg, opts ...grpc.CallOption) (grpc.ServerStreamingClient[*ResponseMsg], error)

在此上下文中,grpc.ServerStreamingClient 表示服务器到客户端 ResponseMsg 消息流的客户端。

有关详细用法信息,请参阅 grpc.ServerStreamingClient 文档。

客户端流方法

这些方法在生成的客户端 stub 上具有以下签名

Foo(ctx context.Context, opts ...grpc.CallOption) (grpc.ClientStreamingClient[*RequestMsg, *ResponseMsg], error)

在此上下文中,grpc.ClientStreamingClient 表示客户端到服务器 RequestMsg 消息流的客户端。它既可以用来发送客户端到服务器的消息流,也可以用来接收单个服务器响应消息。

有关详细用法信息,请参阅 grpc.ClientStreamingClient 文档。

双向流方法

这些方法在生成的客户端 stub 上具有以下签名

Foo(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[*RequestMsg, *ResponseMsg], error)

在此上下文中,grpc.BidiStreamingClient 代表客户端到服务器和服务器到客户端的消息流。

有关详细用法信息,请参阅 grpc.BidiStreamingClient 文档。

包和命名空间

当使用 --go_out=plugins=grpc: 调用 protoc 编译器时,proto package 到 Go package 的转换方式与使用不带 grpc 插件的 protoc-gen-go 插件时相同。

因此,例如,如果 foo.proto 声明自身位于 package foo 中,那么生成的 foo.pb.go 文件也将位于 Go package foo 中。

上次修改时间为 2024 年 11 月 12 日:generated-code: 更新以包含流泛型 (#1365) (3df8b27)