---
description: 跨服务 HTTP 须经 slot_sdk（slot/sdk）调用，禁止在业务服务内散落直连
alwaysApply: true
---

# 跨服务通信（slot_sdk）

**slot_sdk** 是跨服务 HTTP 客户端库（`composer` 包 `slot/sdk`，命名空间 `slotsdk\`），用于**调用方服务**访问**被调服务**的 `innerapi/*` 或 `api/*` 接口。它不是独立部署的微服务。

术语：说「**跨服务 HTTP 调用**」「**经 slot_sdk 调用**」，不说「服务间中转」或「通过 slot/sdk 中转」（库是客户端，被调服务仍直接处理请求）。

## 适用范围

- 一个 Webman 服务需要 HTTP 访问另一个服务的 `innerapi` / `api` 时，**调用方**必须通过 slot_sdk。
- **被调服务**实现 Controller / Logic / Model，**不**为「被别人调」而引入 `slot/sdk`。
- **调用方**若需访问第三个服务，禁止在业务代码里手写 Guzzle/curl 或拼接 `host + path`。

## 标准调用方式

```php
use slotsdk\Config as SDKConfig;
use slotsdk\service\wallet\WalletClient;

$config = new SDKConfig([
    'host' => ShareConfigService::get('walletApiHost'),
    'headers' => ['server-name' => config('app.server_name')],
]);
$result = (new WalletClient($config))->service()->getStatistics($uids, $currency);
```

- 调用链：`new {Domain}Client($config)->service()->{method}(...)`
- Host 来自 center 下发的 `*ApiHost`（如 `walletApiHost`、`userApiHost`）。
- 请求头 `server-name` 为**当前调用方**服务名。
- 响应 `code !== 0` 时抛出 `slotsdk\exception\ApiException`，在 Logic 或 Gateway 层处理。

## 新增 / 变更远程接口

1. 先在 `slot_sdk/src/service/{domain}/` 增加 `{Domain}Service` 方法、路径、必要时 `entity/*Entity`。
2. 再在调用方 Logic 或 `*GatewayService` 中调用；Controller 保持薄。
3. **禁止**在 `slot_admin`、`slot_agent` 等多仓库重复写同一路径字符串。

## 与单服务分层的关系

跨服务访问落在调用方的 **Service** 或 **`*GatewayService`**，Logic 编排用例；HTTP 细节不散落在 Controller。与 [backend-layering](backend-layering.mdc) 中「Service 可承载 sdk」一致；分层职责见该规则，此处只约束**跨服务边界**。

## 命名与混淆规避

| 类型 | 约定 |
| --- | --- |
| SDK 客户端 | `slotsdk\service\{domain}\{Domain}Client` |
| SDK 方法类 | `slotsdk\service\{domain}\{Domain}Service` |
| SDK DTO | `entity\{Name}Entity`、`{Name}RequestEntity` |
| 本地服务 | `app\service\*`（本地 WalletService ≠ slotsdk WalletService） |

同名时：`use slotsdk\Config as SDKConfig` 或完整 namespace。消费方对重复跨服务调用可封装为 `*GatewayService`（如 `UserReferralGatewayService`）。