Python SDK 手册 on Apache Dubbo

快速开始

Mon, 01 Jan 0001 00:00:00 +0000

本指南将通过一个简单的工作示例帮助您开始使用 Python 中的 Dubbo，在此查看完整示例。

1 前置条件

Python 3.11 或更高版本
合适的pip 版本

2 安装Dubbo-python

直接安装
```
pip install apache-dubbo
```

从源码安装

git clone https://github.com/apache/dubbo-python.git
cd dubbo-python && pip install .

3 构建Dubbo服务

构建Dubbo Server

import dubbo
from dubbo.configs import ServiceConfig
from dubbo.proxy.handlers import RpcMethodHandler, RpcServiceHandler

class UnaryServiceServicer:
 def say_hello(self, message: bytes) -> bytes:
 print(f"Received message from client: {message}")
 return b"Hello from server"

def build_service_handler():
 # build a method handler
 method_handler = RpcMethodHandler.unary(
 method=UnaryServiceServicer().say_hello, method_name="unary"
 )
 # build a service handler
 service_handler = RpcServiceHandler(
 service_name="org.apache.dubbo.samples.HelloWorld",
 method_handlers=[method_handler],
 )
 return service_handler

if __name__ == "__main__":
 # build service config
 service_handler = build_service_handler()
 service_config = ServiceConfig(
 service_handler=service_handler, host="127.0.0.1", port=50051
 )
 # start the server
 server = dubbo.Server(service_config).start()

 input("Press Enter to stop the server...\n")

构建Dubbo Client

自定义序列化

Mon, 01 Jan 0001 00:00:00 +0000

在此查看完整示例。

Python 是一种动态语言，其灵活性使得在其他语言中设计通用的序列化层具有挑战性。因此，我们移除了框架级别的序列化层，而是提供接口，允许用户根据需求自行实现（因为用户更了解他们要传输的数据格式）。

序列化通常分为两个部分：序列化和反序列化。我们为这些函数定义了类型，自定义的序列化/反序列化函数必须遵循这些 “格式”。

对于序列化函数，我们规定：

# A function that takes any number of arguments and returns data of type bytes
SerializingFunction = Callable[..., bytes]

对于反序列化函数，我们规定：

# A function that takes an argument of type bytes and returns data of any type
DeserializingFunction = Callable[[bytes], Any]

下面，我将演示如何使用 protobuf 和 json 进行序列化。

protobuf

有关定义和编译 protobuf 文件的详细说明，请参阅 protobuf tutorial。

在Client的unary、client_stream、server_stream 和 bi_stream 方法中通过设置request_serializer 和 response_deserializer 设置对应的序列化和反序列化函数。

class GreeterServiceStub:
 def __init__(self, client: dubbo.Client):
 self.unary = client.unary(
 method_name="sayHello",
 request_serializer=greeter_pb2.GreeterRequest.SerializeToString,
 response_deserializer=greeter_pb2.GreeterReply.FromString,
 )

 def say_hello(self, request):
 return self.unary(request)

if __name__ == "__main__":
 reference_config = ReferenceConfig.from_url(
 "tri://127.0.0.1:50051/org.apache.dubbo.samples.data.Greeter"
 )
 dubbo_client = dubbo.Client(reference_config)

 stub = GreeterServiceStub(dubbo_client)
 result = stub.say_hello(greeter_pb2.GreeterRequest(name="Dubbo-python"))
 print(f"Received reply: {result.message}")

同理在Server中设置对应的序列化和反序列化函数。

Streaming 通信模型

Mon, 01 Jan 0001 00:00:00 +0000

在此查看完整示例。

Dubbo-Python 支持流式调用，包括 ClientStream、ServerStream 和 BidirectionalStream 三种模式。

在流式调用中，操作可以分为写入流和读取流两部分。对于 ClientStream，是多次写入、单次读取；对于 ServerStream，是单次写入、多次读取；而 BidirectionalStream 支持多次写入和多次读取。

写入流

流式调用的写入操作分为单次写入（ServerStream）和多次写入（ClientStream 和 BidirectionalStream）。

单次写入

单次写入流的调用方式与 unary 模式类似。例如：

stub.server_stream(greeter_pb2.GreeterRequest(name="hello world from dubbo-python"))

多次写入

对于多次写入流，用户可以通过迭代器或 writeStream 方式写入数据（两者只能选其一）。

迭代器写入：写入方式类似于 unary 模式，唯一的区别是传入的是迭代器。例如：

# Use an iterator to send multiple requests
def request_generator():
 for i in ["hello", "world", "from", "dubbo-python"]:
 yield greeter_pb2.GreeterRequest(name=str(i))

# Call the remote method and return a read_stream
stream = stub.client_stream(request_generator())

使用 writeStream 写入：此方法不传入参数，使用空参调用，然后通过 write 方法逐条写入数据，写入完成后调用 done_writing 方法结束流。例如：

stream = stub.bi_stream()
# Use the write method to send messages
stream.write(greeter_pb2.GreeterRequest(name="jock"))
stream.write(greeter_pb2.GreeterRequest(name="jane"))
stream.write(greeter_pb2.GreeterRequest(name="alice"))
stream.write(greeter_pb2.GreeterRequest(name="dave"))
# Call done_writing to notify the server that the client has finished writing
stream.done_writing()

读取流

流式调用的读取操作分为单次读取（ClientStream）和多次读取（ServerStream 和 BidirectionalStream）。在流式调用中，无论是哪种模式，返回的都是一个 ReadStream。我们可以使用 read 方法或迭代器读取数据，针对 read 方法，需要注意以下几点：

服务发现

Mon, 01 Jan 0001 00:00:00 +0000

在此查看完整示例。

使用服务注册和发现非常简单。事实上，与点对点调用相比，它只需要增加两行代码。在使用该功能之前，我们需要安装相关的注册客户端。目前，Dubbo-python 只支持 Zookeeper，因此下面的演示将使用 Zookeeper。与之前类似，我们需要克隆 Dubbo-python 源代码并安装它。不过，在这种情况下，我们还需要安装 Zookeeper 客户端。命令如下：

git clone https://github.com/apache/dubbo-python.git
cd dubbo-python && pip install .[zookeeper]

而后，只需启动 Zookeeper 并在现有示例中插入以下代码即可：

# Configure the Zookeeper registry
registry_config = RegistryConfig.from_url("zookeeper://127.0.0.1:2181")
bootstrap = Dubbo(registry_config=registry_config)

# Create the client
client = bootstrap.create_client(reference_config)

# Create and start the server
bootstrap.create_server(service_config).start()