iTi-Flask/docs/SERVICE_CLIENT.md

服务客户端

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 配置示例：

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,
        },
    }
}

使用

from iti.service_client import service_client

erp = service_client("erp")

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

POST 默认不重试。

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

错误语义

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

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

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

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