生成的代码参考
生成的代码参考
gRPC Python 依赖于协议缓冲区编译器(protoc
)来生成代码。它使用插件来补充由普通 protoc
生成的代码,并添加 gRPC 特定的代码。对于包含 gRPC 服务的 .proto
服务描述,普通的 protoc
生成的代码会合成到一个 _pb2.py
文件中,而 gRPC 特定的代码则会存放在一个 _pb2_grpc.py
文件中。后一个 Python 模块会导入前一个模块。此页面的重点是生成的代码中 gRPC 特定的子集。
示例
考虑以下 FortuneTeller
proto 服务
service FortuneTeller {
// Returns the horoscope and zodiac sign for the given month and day.
rpc TellFortune(HoroscopeRequest) returns (HoroscopeResponse) {
// errors: invalid month or day, fortune unavailable
}
// Replaces the fortune for the given zodiac sign with the provided one.
rpc SuggestFortune(SuggestionRequest) returns (SuggestionResponse) {
// errors: invalid zodiac sign
}
}
当服务被编译时,gRPC protoc
插件会生成类似于以下 _pb2_grpc.py
文件的代码
import grpc
import fortune_pb2
class FortuneTellerStub(object):
def __init__(self, channel):
"""Constructor.
Args:
channel: A grpc.Channel.
"""
self.TellFortune = channel.unary_unary(
'/example.FortuneTeller/TellFortune',
request_serializer=fortune_pb2.HoroscopeRequest.SerializeToString,
response_deserializer=fortune_pb2.HoroscopeResponse.FromString,
)
self.SuggestFortune = channel.unary_unary(
'/example.FortuneTeller/SuggestFortune',
request_serializer=fortune_pb2.SuggestionRequest.SerializeToString,
response_deserializer=fortune_pb2.SuggestionResponse.FromString,
)
class FortuneTellerServicer(object):
def TellFortune(self, request, context):
"""Returns the horoscope and zodiac sign for the given month and day.
errors: invalid month or day, fortune unavailable
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def SuggestFortune(self, request, context):
"""Replaces the fortune for the given zodiac sign with the provided
one.
errors: invalid zodiac sign
"""
context.set_code(grpc.StatusCode.UNIMPLEMENTED)
context.set_details('Method not implemented!')
raise NotImplementedError('Method not implemented!')
def add_FortuneTellerServicer_to_server(servicer, server):
rpc_method_handlers = {
'TellFortune': grpc.unary_unary_rpc_method_handler(
servicer.TellFortune,
request_deserializer=fortune_pb2.HoroscopeRequest.FromString,
response_serializer=fortune_pb2.HoroscopeResponse.SerializeToString,
),
'SuggestFortune': grpc.unary_unary_rpc_method_handler(
servicer.SuggestFortune,
request_deserializer=fortune_pb2.SuggestionRequest.FromString,
response_serializer=fortune_pb2.SuggestionResponse.SerializeToString,
),
}
generic_handler = grpc.method_handlers_generic_handler(
'example.FortuneTeller', rpc_method_handlers)
server.add_generic_rpc_handlers((generic_handler,))
代码元素
gRPC 生成的代码首先导入 grpc
包和由 protoc
合成的普通 _pb2
模块,后者定义了非 gRPC 特定的代码元素,例如对应于协议缓冲区消息的类以及反射使用的描述符。
对于 .proto
文件中的每个服务 Foo
,都会生成三个主要元素
- Stub:客户端用于连接到 gRPC 服务的
FooStub
。 - Servicer:服务器用于实现 gRPC 服务的
FooServicer
。 - 注册函数:用于将 servicer 注册到
grpc.Server
对象的add_FooServicer_to_server
函数。
Stub
生成的 Stub
类由 gRPC 客户端使用。它有一个构造函数,该构造函数接受一个 grpc.Channel
对象并初始化 stub。对于服务中的每个方法,初始化器都会使用相同名称向 stub 对象添加一个对应的属性。根据 RPC 类型(一元或流式),该属性的值将是类型为 UnaryUnaryMultiCallable、UnaryStreamMultiCallable、StreamUnaryMultiCallable 或 StreamStreamMultiCallable 的可调用对象。
Servicer
对于每个服务,都会生成一个 Servicer
类,该类充当服务实现的超类。对于服务中的每个方法,都会在 Servicer
类中生成一个对应的函数。使用服务实现覆盖此函数。与 .proto
文件中的代码元素关联的注释会作为文档字符串出现在生成的 Python 代码中。
注册函数
对于每个服务,都会生成一个函数,该函数在 grpc.Server
对象上注册一个实现该服务的 Servicer
对象,以便服务器可以将查询路由到相应的 servicer。此函数接受一个实现 Servicer
的对象,通常是生成的 Servicer
代码元素的子类的实例,以及一个 grpc.Server 对象。