7.2 KiB
7.2 KiB
name, overview, todos, isProject
| name | overview | todos | isProject | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 跨服务 slot_sdk 约束 | 在用户级 Cursor 规则目录新增一条「跨服务通信」约束，用统一、可操作的术语规定：业务服务之间的 HTTP 互调必须经 `slot/sdk`（`slotsdk`）完成，并与现有 `backend-layering` 规则互补而不重复。 |
|
false |
跨服务通信 Cursor 用户级约束
背景与目标
当前用户级规则在 /Users/ray/.cursor/rules/ 已有：
backend-layering.mdc— 单服务内 Controller / Logic / Service 分层dev-environment.mdc— Docker 本地开发php-doc.mdc— PHPDoc 规范
backend-layering.mdc 仅在 Service 层职责里顺带提到「sdk」，没有规定跨服务 HTTP 的入口、命名与新增 API 的流程。本次新增独立规则（单一职责，符合 create-rule 实践），alwaysApply: true，与现有三条规则一致。
代码库事实（供规则用语对齐）：
- 包名：
slot/sdk，命名空间slotsdk\，仓库slot_sdk - 典型消费方：
slot_admin、slot_agent、slot_console、slot_pwa（composer 依赖slot/sdk） - 典型被调方：
slot_wallet、slot_user、slot_center等，对外暴露innerapi/*、api/* - 推荐调用链：
new {Domain}Client($config)->service()->{method}(...) - 项目内已有表述：
slot_agent/doc/feature_agent.md—「代理服不直连用户域表，统一通过slot_sdk调用户服 innerapi」
按你的选择：规则只约束新代码走 slot_sdk，不写 InnerCurlService / slot_lib 等 legacy 迁移条款。
术语优化（写入规则正文）
| 避免说法 | 推荐说法 | 说明 |
|---|---|---|
| 后端服务之间调用 / 中转 | 跨服务 HTTP 调用 | 明确是进程间 HTTP，不是本地 Logic/Service |
| 通过 slot/sdk 中转 | 经 slot_sdk 调用 | slot_sdk = 客户端库；被调服务仍直接处理请求，库不做业务中转 |
| SDK / 封装 | slot_sdk（slot/sdk） |
与 composer 包名、仓库目录一致 |
| 各服务自己拼 URL | 在 slot_sdk 增加 {Domain}Service 方法 |
路径与 DTO 单点维护 |
app\service\WalletService |
本地 WalletService vs slotsdk WalletService | 防止与 SDK 类名混淆 |
核心定义（规则开篇 1 段）：
slot_sdk 是跨服务 HTTP 客户端库（
composer包slot/sdk，命名空间slotsdk\），用于调用方服务访问被调服务的innerapi/*或api/*接口。它不是独立部署的微服务。
拟新增文件
路径： /Users/ray/.cursor/rules/cross-service-sdk.mdc
Frontmatter：
---
description: 跨服务 HTTP 须经 slot_sdk（slot/sdk）调用，禁止在业务服务内散落直连
alwaysApply: true
---
正文结构（约 35–45 行，中文为主）：
1. 适用范围
- 一个 Webman 服务需要 HTTP 访问另一个服务的
innerapi/api时适用。 - 被调服务自身实现 Controller/Logic/Model，不为「被别人调」而引入
slot/sdk。 - 调用方若需调第三个服务，必须通过
slot/sdk（不在业务代码里手写 Guzzle/curl/拼 host+path）。
2. 标准调用方式
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);
要点：
- Host 来自 center 下发的
*ApiHost（如walletApiHost、userApiHost）。 - 请求头带
server-name，值为当前调用方服务名。 - 非零
code由slotsdk\exception\ApiException抛出，调用方在 Logic/Gateway 层处理。
3. 新增 / 变更远程接口的流程
- 在
slot_sdk/src/service/{domain}/增加{Domain}Service方法、路径常量、必要时entity/*Entity。 - 在调用方 Logic 或
*GatewayService中调用；Controller 保持薄。 - 禁止在
slot_admin/slot_agent等多仓库重复写同一路径字符串。
4. 与 backend-layering 的衔接（1–2 句）
- 跨服务访问在调用方落在 Service 或
*GatewayService，Logic 编排用例；不把 HTTP 细节散落在 Controller。 - 与
backend-layering.mdc中「Service 可承载 sdk」一致；本规则专门约束跨服务边界，不重复写分层表。
5. 命名与混淆规避
- SDK：
slotsdk\service\{domain}\{Domain}Client、{Domain}Service、entity\{Name}Entity。 - 本地：
app\service\*；若同名，用SDKConfig、完整 namespace 或 import alias。 - 消费方封装重复调用：
UserReferralGatewayService这类*GatewayService模式。
与现有规则的关系
flowchart LR
subgraph userRules [用户级 .cursor/rules]
layering[backend-layering]
crossSdk[cross-service-sdk 新增]
docker[dev-environment]
phpdoc[php-doc]
end
layering -->|"单服务内分层"| Logic
crossSdk -->|"服务间 HTTP"| slot_sdk
slot_sdk --> innerapi[被调服务 innerapi/api]
- 不修改
backend-layering.mdc：避免一条规则过长；仅在cross-service-sdk末尾用交叉引用衔接。 - 不修改
dev-environment.mdc/php-doc.mdc。
实施步骤（确认计划后执行）
- 创建
cross-service-sdk.mdc，填入上述 frontmatter 与正文。 - 通读四条
alwaysApply规则，确认无矛盾表述（尤其 Service 层与 Gateway 分工）。 - （可选）在
slot_sdk/readme.md补 5–10 行架构说明并链到 Cursor 规则 — 仅当你希望仓库内也有文档镜像；非本次必需。
验收标准
- 新开 Cursor 会话、编辑任意 slot PHP 文件时，Agent 应自动带上「跨服务须经 slot_sdk、新 API 先改 slot_sdk」约束。
- 术语统一使用：跨服务 HTTP、调用方 / 被调方、slot_sdk，避免「中转」「服务间随便 HTTP」等模糊说法。
- 规则正文不含 legacy 迁移条款（按你的选择）。