# 服务客户端

iTi-Flask 提供轻量 HTTP JSON 服务客户端。

它用于调用 ERP 这类独立 Gateway 服务。
它不是 service mesh，也不是服务发现系统。

## 范围

第一版支持：

- HTTP JSON。
- 同步调用。
- base URL 配置。
- service token 鉴权。
- 超时。
- 保守重试。
- 可选熔断。
- trace id 透传。
- 结构化调用日志。
- 测试用 mock transport。

不支持：

- async client。
- 服务发现。
- 负载均衡。
- gRPC。
- streaming。
- OpenAPI client 生成。

## 配置

Flask 配置示例：

```python
SERVICES = {
    "erp": {
        "base_url": "http://iti-erp:8000",
        "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],
        },
        "circuit_breaker": {
            "enabled": False,
            "fail_max": 5,
            "reset_timeout": 30,
        },
    }
}
```

## 使用

```python
from iti.service_client import service_client

erp = service_client("erp")

payload = erp.get("/erp/users/{id}", path={"id": user_id})
```

POST 默认不重试。

```python
result = erp.post("/erp/sync/jobs", json={"kind": "users"})
```

## 错误语义

服务间 API 使用真实 HTTP 状态码。

客户端在以下情况抛出框架服务错误：

- 缺少服务配置。
- 超时。
- 传输错误。
- 熔断打开。
- 非 2xx HTTP 响应。
- 期望 JSON 但响应不是合法 JSON。

后台 API 的 envelope 规则不适用于服务间 API。