56 lines
2.7 KiB
Plaintext
56 lines
2.7 KiB
Plaintext
---
|
||
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`）。
|