iTi-Flask/docs/SERVICE_CLIENT.md

服务客户端

iTi-Flask 提供同步 HTTP JSON 服务客户端。 它用于业务项目调用独立服务。

能力

支持：

• base URL 配置。
• service token 鉴权。
• 超时。
• 按方法和状态码重试。
• 可选熔断。
• X-Trace-Id 透传。
• 结构化调用日志。
• envelope 自动识别。
• HTTP status 自动识别。
• 测试用 mock transport。

不支持：

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

配置

class DevConfig(BaseDevConfig):
    def __init__(self) -> None:
        super().__init__()
        self.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 非空时，客户端会发送：

Authorization: Bearer change-me

使用

from iti.service_client import service_client

inventory = service_client(app, "inventory")

item = inventory.get("/items/{id}", path={"id": "A001"})
created = inventory.post("/items", json={"name": "demo"})

GET、HEAD、OPTIONS 默认可按配置重试。 POST 默认不重试。

需要强制重试：

inventory.post("/jobs", json={"kind": "sync"}, retry=True)

Trace ID

客户端会为每次调用生成 X-Trace-Id。

错误

客户端会抛出这些异常：

• ServiceConfigError
• ServiceUnavailableError
• ServiceHTTPError
• ServiceBusinessError

响应体如果是 envelope：

• code == 200 返回 data。
• code != 200 抛出 ServiceBusinessError。

这条规则不依赖 HTTP status。 也就是说，HTTP 401 + envelope code=401 会抛 ServiceBusinessError，调用方可统一处理业务 code。

非 envelope 的非 2xx 响应会抛出 ServiceHTTPError。 envelope 只认同时包含 data、code、message 的 JSON object。 响应体为空时返回 None。 expect_json=False 时返回原始 httpx.Response。