70 lines
2.2 KiB
Markdown
70 lines
2.2 KiB
Markdown
---
|
||
name: hyperf-service
|
||
version: 2.0.0
|
||
description: "生成 Hyperf 后端服务模块脚手架（Controller/Service/Repository/Model）。当需要新建后端业务模块时使用。支持 DI 注入和事务管理。"
|
||
---
|
||
|
||
> ⚠️ 核心执行流程已在 `.cursor/rules/skill-backend-scaffold.mdc` 中由 Cursor 自动注入。
|
||
> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
|
||
|
||
# Hyperf Service Module Scaffold
|
||
|
||
## 触发条件
|
||
|
||
用户要求创建后端服务模块、业务 Service 类、或完整的后端业务层。
|
||
|
||
## 执行流程
|
||
|
||
### 0. 加载规范（⚠️ 必须最先执行）
|
||
|
||
依次读取 `.cursor/rules/013-backend.mdc`、`016-swoole.mdc`、`019-modular.mdc`，提取 DI、事务、协程安全、依赖方向、事件解耦。
|
||
|
||
### 1. 确认模块规格
|
||
|
||
| 字段 | 必填 | 默认值 |
|
||
|------|------|--------|
|
||
| 模块名称 | ✅ | — |
|
||
| 所属业务域 | ❌ | 推断 |
|
||
| 需要 Repository？ | ❌ | 复杂查询时 true |
|
||
| 需要事件？ | ❌ | false |
|
||
| 需要数据权限？ | ❌ | true |
|
||
| 需要缓存？ | ❌ | false |
|
||
|
||
### 2. 生成文件结构
|
||
|
||
Controller/Admin、Service、Repository、Model、Request、Event、Listener（可选）。
|
||
|
||
### 3. Service / Repository
|
||
|
||
Service 使用 `Db::transaction` 包裹写操作，Repository 实现 `applyFilters`、`applyDataScope`、分页上限。完整模板见 **Tier 3**。
|
||
|
||
### 4. 结构化日志
|
||
|
||
Service 集成 HasLogger Trait，create/update/delete 至少 info 级别。RequestId 中间件全局注入 request_id。
|
||
|
||
### 5. 重试机制
|
||
|
||
外部 API 调用使用 RetryHelper 指数退避重试，retryOn 指定可重试异常类型。
|
||
|
||
### 6. 遵循项目约定
|
||
|
||
扫描 `app/Service/`、AbstractService、BusinessException、数据权限、事件注册、HasLogger、RetryHelper。
|
||
|
||
## 验证
|
||
|
||
1. [ ] `php -l` 无错误
|
||
2. [ ] 依赖注入正确
|
||
3. [ ] 写操作使用 `Db::transaction()`
|
||
4. [ ] 分页有 page_size 上限
|
||
5. [ ] 异常使用 BusinessException
|
||
6. [ ] applyDataScope 已实现（如需）
|
||
7. [ ] 关键操作有结构化日志
|
||
8. [ ] 外部 API 用 RetryHelper
|
||
9. [ ] Logger channel 使用类名
|
||
|
||
## Tier 3 深度参考
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `references/service-templates.md` | Service/Repository/Event/Logger/Retry 完整代码 |
|