You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
99 lines
1.9 KiB
Markdown
99 lines
1.9 KiB
Markdown
# 服务客户端
|
|
|
|
iTi-Flask 提供同步 HTTP JSON 服务客户端。
|
|
它用于业务项目调用独立服务。
|
|
|
|
## 能力
|
|
|
|
支持：
|
|
|
|
- base URL 配置。
|
|
- service token 鉴权。
|
|
- 超时。
|
|
- 按方法和状态码重试。
|
|
- 可选熔断。
|
|
- `X-Trace-Id` 透传。
|
|
- 结构化调用日志。
|
|
- 测试用 mock transport。
|
|
|
|
不支持：
|
|
|
|
- 服务发现。
|
|
- 负载均衡。
|
|
- gRPC。
|
|
- streaming。
|
|
- async client。
|
|
- OpenAPI client 生成。
|
|
|
|
## 配置
|
|
|
|
```python
|
|
SERVICES = {
|
|
"inventory": {
|
|
"base_url": "http://inventory.local",
|
|
"token": "change-me",
|
|
"timeout": {
|
|
"connect": 1.0,
|
|
"read": 5.0,
|
|
"write": 5.0,
|
|
"pool": 1.0,
|
|
},
|
|
"retry": {
|
|
"attempts": 2,
|
|
"backoff": 0.2,
|
|
"statuses": [502, 503, 504],
|
|
"methods": ["GET", "HEAD", "OPTIONS"],
|
|
},
|
|
"circuit_breaker": {
|
|
"enabled": False,
|
|
"fail_max": 5,
|
|
"reset_timeout": 30,
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
`base_url` 必填。
|
|
`token` 非空时，客户端会发送：
|
|
|
|
```http
|
|
Authorization: Bearer change-me
|
|
```
|
|
|
|
## 使用
|
|
|
|
```python
|
|
from iti.service_client import service_client
|
|
|
|
inventory = service_client("inventory")
|
|
|
|
item = inventory.get("/items/{id}", path={"id": "A001"})
|
|
created = inventory.post("/items", json={"name": "demo"})
|
|
```
|
|
|
|
`GET`、`HEAD`、`OPTIONS` 默认可按配置重试。
|
|
`POST` 默认不重试。
|
|
|
|
需要强制重试：
|
|
|
|
```python
|
|
inventory.post("/jobs", json={"kind": "sync"}, retry=True)
|
|
```
|
|
|
|
## Trace ID
|
|
|
|
客户端优先复用当前请求头里的 `X-Trace-Id`。
|
|
没有请求上下文时自动生成。
|
|
|
|
## 错误
|
|
|
|
客户端会抛出这些异常：
|
|
|
|
- `ServiceConfigError`
|
|
- `ServiceUnavailableError`
|
|
- `ServiceHTTPError`
|
|
|
|
非 2xx 响应会抛出 `ServiceHTTPError`。
|
|
响应体为空时返回 `None`。
|
|
`expect_json=False` 时返回原始 `httpx.Response`。
|