114 lines
4.1 KiB
Markdown
114 lines
4.1 KiB
Markdown
# chongming-request
|
||
|
||
Zenoh Worker 直连客户端，用于从服务端或其他 Worker 直接调用 Zenoh RPC，无需经过 HTTP 路由。
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
uv pip install -e utils/request
|
||
```
|
||
|
||
---
|
||
|
||
## 功能
|
||
|
||
- **自动服务发现**：基于 Zenoh liveliness 自动发现存活的 Worker
|
||
- **随机负载均衡**：在可用 Worker 间随机选择；疑似故障副本进入 30s 冷静期被跳过
|
||
- **换副本重试**：超时 / 无回复 / 业务错误时换一个「未试过」的副本重试，
|
||
无未试副本立即失败（不重复打同一个坏副本）；业务错误不列入冷静期
|
||
- **同步/异步支持**：提供 `call`（异步）和 `call_sync`（同步）接口
|
||
|
||
---
|
||
|
||
## API
|
||
|
||
### `Client` 类
|
||
|
||
```python
|
||
from chongming_request import Client
|
||
|
||
async with Client(session=zenoh_session) as client:
|
||
result = await client.call(
|
||
worker_type="example",
|
||
subject="example.add",
|
||
payload={"a": 1, "b": 2},
|
||
method="GET"
|
||
)
|
||
```
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| ------------- | --------------- | -------------------------------- |
|
||
| `session` | `zenoh.Session` | Zenoh 会话对象 |
|
||
| `worker_type` | `str` | Worker 类型名（如 `"example"`） |
|
||
| `subject` | `str` | Zenoh 主题（如 `"example.add"`） |
|
||
| `payload` | `dict` | 业务参数（自动封装为信封） |
|
||
| `method` | `str` | HTTP 方法（`"GET"` / `"POST"`） |
|
||
| `timeout` | `float` | 单次调用超时（秒），换副本重试重新计时 |
|
||
| `retries` | `int` | 失败重试次数（每次重试换一个未试过的副本） |
|
||
|
||
> **信封协议**：`call()` 把 `payload` 封装为
|
||
> `{"meta": {"method": ...}, "data": payload}` 发送，**不修改调用方传入的 dict**；
|
||
> 若传入的 `payload` 已含 `meta`/`data` 键则视为完整信封**原样使用**（保留全部
|
||
> 字段、不改写 `0`/`[]` 等 falsy 值），仅缺 `meta.method` 时补入。`meta` 非 dict
|
||
> 会立即抛 `ValueError`，不会被发送。
|
||
|
||
### 与网关 `worker_manager.call_raw` 的语义对齐
|
||
|
||
- **载荷**：业务数据整体入 `data`；调用方自备信封时不改写（对齐 call_raw 的
|
||
"谁构造信封谁负责"）。
|
||
- **回复**：worker 回复解析为 dict 返回，空回复兜底 `{}`（对齐 call_raw 的 `b"{}"`）。
|
||
- **重试**：超时 / 无回复 / 业务错误换未试过的副本重试；超时与无回复的副本进入
|
||
30s 冷静期，后续调用跳过；失败终态抛 `RuntimeError` 并携带最后一个错误详情
|
||
（已尝试副本数、次数上限、具体原因）。
|
||
- **信任模型**：本包定位为**内部 worker 请求工具**（worker 间调用 / 服务端内部直连），
|
||
走 Zenoh 直连、无 HTTP 链路：`meta.user_info` **不会**被注入或校验，需要时由调用方
|
||
自填；`cacheable`、实例定向（`instance_id`）等能力请走网关 HTTP 或 `call_raw`。
|
||
|
||
### 同步调用
|
||
|
||
```python
|
||
result = client.call_sync(
|
||
worker_type="example",
|
||
subject="example.add",
|
||
payload={"a": 1, "b": 2},
|
||
timeout=5.0
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
1. **Worker 间互相调用**：一个 Worker 调用另一个 Worker 的 RPC 方法
|
||
2. **服务端内部调用**：在 FastAPI 路由处理器中直接调用 Worker
|
||
3. **内部接口调用**：调用 `internal = true` 的端点（不暴露 HTTP 路由）
|
||
4. **测试与调试**：直接测试 Worker 的 RPC 行为
|
||
|
||
---
|
||
|
||
## 与 HTTP 调用的对比
|
||
|
||
| 特性 | HTTP 调用 | `chongming-request` |
|
||
| -------------------- | ------------------ | -------------------- |
|
||
| 需要注册 HTTP 路由 | ✅ | ❌（直接 Zenoh RPC） |
|
||
| 支持 `internal` 端点 | ❌ | ✅ |
|
||
| 序列化开销 | JSON → HTTP → JSON | JSON → Zenoh → JSON |
|
||
| 适用场景 | 外部客户端 | 内部微服务通信 |
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
python tests/test_client.py
|
||
```
|
||
|
||
---
|
||
|
||
## 依赖
|
||
|
||
- `zenoh` — Zenoh Python 绑定（`eclipse-zenoh`）
|
||
- `orjson` — JSON 序列化
|