64 lines
2.6 KiB
Plaintext
64 lines
2.6 KiB
Plaintext
---
|
||
description: >
|
||
Hyperf 后端模块脚手架技能。新建 API 端点、Controller、Service、
|
||
Repository 或完整后端业务模块时激活。含分层约定、异常体系和事务管理。
|
||
globs:
|
||
- "**/Controller/**/*.php"
|
||
- "**/Service/**/*.php"
|
||
- "**/Repository/**/*.php"
|
||
alwaysApply: false
|
||
---
|
||
|
||
# Backend Scaffold (API + Service)
|
||
|
||
> 本文件是精简执行摘要。完整流程、模板和深度参考见：
|
||
> Read `.cursor/skills/api-scaffold/SKILL.md`（API 端点）
|
||
> Read `.cursor/skills/hyperf-service/SKILL.md`（Service 模块）
|
||
|
||
> **适用性**（双模式）：
|
||
> - **新建**后端模块/API 端点：走完整执行流程（Step 1-8）
|
||
> - **修改**已有接口或 Service：跳过脚手架步骤，完成后走「验证」清单
|
||
|
||
## 执行流程
|
||
|
||
1. 加载规范：Read `013-backend.mdc`、`016-swoole.mdc`
|
||
2. 确认模块规格（资源名称、HTTP 方法、路由路径、是否需要 Repository/事件/数据权限）
|
||
3. 扫描项目约定：`app/Controller/`、`app/Service/` 现有模式
|
||
4. **配置依赖检查**（使用事件/队列/缓存时必须检查）：
|
||
- 使用异步队列：检查 `config/autoload/async_queue.php` 是否存在
|
||
- 使用 Redis 缓存：检查 `config/autoload/redis.php` 连接池配置
|
||
- 使用 JWT：检查 `config/autoload/jwt.php` 和环境变量 `JWT_SECRET`
|
||
5. 生成文件：Controller → Service → Repository（如需）→ Model → FormRequest → Event（可选）→ 路由注册
|
||
6. Service 使用 `Db::transaction` 包裹写操作
|
||
7. Repository 实现 `applyFilters`、`applyDataScope`、分页上限
|
||
8. 集成 HasLogger Trait，关键操作有结构化日志
|
||
9. 外部 API 调用使用 RetryHelper 指数退避重试
|
||
|
||
## 分层约定
|
||
|
||
Controller（接收请求）→ Service（业务逻辑）→ Repository（数据访问）→ Model
|
||
|
||
## 异常体系
|
||
|
||
- `BusinessException` — 可预期业务错误（404/403/422）
|
||
- `ValidationException` — FormRequest 校验失败
|
||
- `SystemException` — 500 系统故障，记录堆栈
|
||
|
||
## 验证
|
||
|
||
- [ ] `php -l` 编译无错误
|
||
- [ ] FormRequest rules 覆盖所有请求字段
|
||
- [ ] 错误处理覆盖 400/401/403/404/422/500
|
||
- [ ] Service 使用事务包裹写操作
|
||
- [ ] 路由遵循 RESTful 命名（复数名词、kebab-case）
|
||
- [ ] 中间件正确挂载（认证 + 权限）
|
||
- [ ] 分页有 page_size 上限
|
||
- [ ] 关键操作有结构化日志
|
||
- [ ] 外部 API 用 RetryHelper
|
||
|
||
## 深度参考
|
||
|
||
- `.cursor/skills/api-scaffold/references/code-templates.md`
|
||
- `.cursor/skills/api-scaffold/references/exception-handling.md`
|
||
- `.cursor/skills/hyperf-service/references/service-templates.md`
|