# dubbo-python

**Repository Path**: zengrui_dl/dubbo-python

## Basic Information

- **Project Name**: dubbo-python
- **Description**: 基于 Apache Dubbo Python SDK 的装饰器风格封装，简化 Dubbo 服务定义和消费, 添加 Nacos 支持
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dubbo_ext

基于 Apache Dubbo Python SDK 的装饰器风格封装，简化 Dubbo 服务定义和消费。支持 Nacos 注册中心和 Protocol Buffers 序列化。

## 特性

- **类装饰器风格**：`@dubbo_service` 定义 RPC 服务，`@dubbo_reference` 定义远程服务引用
- **单例容器**：`dubbo_application` 管理多个服务，共享一个端口
- **Protocol Buffers 支持**：使用 dataclass 定义消息结构，自动生成 .proto 文件
- **Nacos 集成**：支持通过 URL 连接 Nacos 注册中心
- **多服务支持**：一个应用可暴露多个 Dubbo 服务
- **共享端口**：多个服务在同一个端口上通过 Triple 协议区分

## 快速开始

### 1. 定义消息结构（使用 dataclass）

```python
from dataclasses import dataclass

@dataclass
class GetUserRequest:
    user_id: str

@dataclass
class GetUserResponse:
    user_id: str
    name: str
    email: str
```

### 2. 定义 Dubbo 服务

```python
from dubbo_ext import dubbo_service

@dubbo_service("org.example.UserService")
class UserService:
    def get_user(self, req: GetUserRequest) -> GetUserResponse:
        return GetUserResponse(
            user_id=req.user_id,
            name="张三",
            email="zhangsan@example.com"
        )

@dubbo_service("org.example.OrderService")
class OrderService:
    def get_orders(self, req: GetOrdersRequest) -> GetOrdersResponse:
        return GetOrdersResponse(
            user_id=req.user_id,
            orders=[
                Order(order_id="1001", amount=100.0),
                Order(order_id="1002", amount=200.0)
            ]
        )
```

### 3. 定义远程服务引用

```python
from dubbo_ext import dubbo_reference

@dubbo_reference(service_name="org.example.OrderService")
class OrderRef:
    def get_orders(self, req: GetOrdersRequest) -> GetOrdersResponse: ...
```

### 4. 启动服务

```python
from fastapi import FastAPI
import uvicorn
from dubbo_ext import dubbo_application

app = FastAPI(title="User Service")

@app.get("/api/user/{user_id}")
def get_user_http(user_id: str):
    req = GetUserRequest(user_id=user_id)
    result = UserService.get_user(req)
    return {
        "user_id": result.user_id,
        "name": result.name,
        "email": result.email
    }

async def main():
    dubbo_application.set_registry("nacos://nacos:nacos@127.0.0.1:8848")
    dubbo_application.serve(port=50051)
    order_ref = dubbo_application.connect(OrderRef)
    config = uvicorn.Config(app, host="0.0.0.0", port=18000)
    await uvicorn.Server(config).serve()

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())
```

## Protocol Buffers 支持

### 自动生成 .proto 文件

当使用 `dubbo_application.serve()` 启动服务时，会自动为所有服务生成对应的 .proto 文件到 `proto/` 目录。

### 支持的类型

| Python 类型 | Protobuf 类型 | 示例 |
|------------|--------------|------|
| `str` | `string` | `name: str` |
| `int` | `int64` | `age: int` |
| `float` | `double` | `price: float` |
| `bool` | `bool` | `active: bool` |
| `List[T]` | `repeated T` | `items: List[Item]` |
| `Optional[T]` | `optional T` | `nickname: Optional[str]` |
| dataclass | message | `user: User` |

### 嵌套 dataclass

```python
@dataclass
class Order:
    order_id: str
    amount: float

@dataclass
class GetOrdersResponse:
    user_id: str
    orders: List[Order]
```

生成的 .proto 文件：

```protobuf
message Order {
  string order_id = 1;
  double amount = 2;
}

message GetOrdersResponse {
  string user_id = 1;
  repeated Order orders = 2;
}
```

## 装饰器详解

### @dubbo_service(service_name)

类装饰器，将类中的方法注册为 Dubbo RPC 方法：

```python
@dubbo_service("org.example.UserService")
class UserService:
    def get_user(self, req: GetUserRequest) -> GetUserResponse:
        return GetUserResponse(user_id=req.user_id, name="张三")
```

### @dubbo_reference(service_name)

定义一个远程服务接口，自动连接并调用：

```python
@dubbo_reference(service_name="org.example.OrderService")
class OrderRef:
    def get_orders(self, req: GetOrdersRequest) -> GetOrdersResponse: ...
```

使用：
```python
dubbo_application.set_registry("nacos://nacos:nacos@127.0.0.1:8848")
order_ref = dubbo_application.connect(OrderRef)
req = GetOrdersRequest(user_id="123")
result = order_ref.get_orders(req)
```

## API

### dubbo_service

```python
@dubbo_service(service_name: str)
class ServiceClass:
    ...
```

类装饰器，自动将类中的方法注册为 Dubbo RPC 方法。

### DubboApplication

```python
dubbo_application  # 单例
```

应用容器，管理多个 DubboService。

**方法**：
- `set_registry(registry: str | Registry)` - 设置注册中心（全局生效）
- `serve(port: int = 50051, registry: str | Registry = None, host: Optional[str] = None, generate_proto: bool = True)` - 启动所有服务并注册到注册中心
- `connect(ref_cls, registry: str | Registry = None, max_retries=10, retry_interval=1.0)` - 连接远程服务

### dubbo_reference

```python
@dubbo_reference(service_name: str)
class InterfaceClass:
    ...
```

定义远程服务接口。

### NacosRegistryFactory

```python
NacosRegistryFactory().get_registry(url: str | URL) -> NacosRegistry
```

## 目录结构

```
dubbo-python/
├── dubbo_ext/                     # 核心库
│   ├── __init__.py
│   ├── protobuf/                  # Protobuf 支持
│   │   ├── __init__.py
│   │   ├── generator.py           # .proto 文件生成器
│   │   ├── converter.py           # dataclass ↔ protobuf 转换
│   │   └── registry.py            # 消息类型注册表
│   ├── dubbo_service.py           # @dubbo_service
│   ├── dubbo_application.py       # DubboApplication
│   ├── dubbo_reference.py         # @dubbo_reference
│   └── nacos_registry.py          # Nacos 集成
├── proto/                         # 自动生成的 .proto 文件
├── sample/                        # 示例服务
│   ├── user_service/
│   │   ├── main.py
│   │   └── service/
│   │       ├── user_svc.py
│   │       └── order_ref.py
│   └── order_service/
│       ├── main.py
│       └── service/
│           ├── order_svc.py
│           └── user_ref.py
├── tests/                         # 测试
│   ├── test_dubbo_service.py
│   └── test_protobuf.py
└── README.md
```

## 依赖

- `apache-dubbo>=3.0.0b1` - Apache Dubbo Python SDK
- `fastapi>=0.104.0` - Web 框架
- `uvicorn[standard]>=0.24.0` - ASGI 服务器
- `nacos-sdk-python>=0.2.0` - Nacos 客户端
- `protobuf>=4.25.0` - Protocol Buffers

## License

Apache License 2.0