72 lines
2.5 KiB
Markdown
72 lines
2.5 KiB
Markdown
---
|
||
name: api-scaffold
|
||
version: 3.0.0
|
||
description: "生成 Hyperf API 端点脚手架（Controller/Service/FormRequest/路由）。当需要新建 API 接口或 CRUD 资源时使用。含分级异常体系。"
|
||
---
|
||
|
||
> ⚠️ 核心执行流程已在 `.cursor/rules/skill-backend-scaffold.mdc` 中由 Cursor 自动注入。
|
||
> 本文件提供完整模板、代码示例和边缘场景处理，供 Agent 按需深入 Read。
|
||
|
||
# Hyperf API Endpoint Scaffold
|
||
|
||
## 触发条件
|
||
|
||
用户要求创建新 API 端点、路由、接口、REST 资源或 CRUD 操作。
|
||
|
||
## 执行流程
|
||
|
||
### 0. 加载规范（⚠️ 必须最先执行）
|
||
|
||
依次使用 `Read` 工具读取：
|
||
- `.cursor/rules/013-backend.mdc` — ApiResponse 格式、FormRequest、路由、认证
|
||
- `.cursor/rules/019-modular.mdc` — Controller→Service→Repository→Model 依赖方向、各层职责
|
||
|
||
### 1. 确认端点规格
|
||
|
||
| 字段 | 必填 | 默认值 |
|
||
|------|------|--------|
|
||
| 资源名称 | ✅ | — |
|
||
| HTTP 方法 | ✅ | — |
|
||
| 路由路径 | ✅ | — |
|
||
| 请求体结构 | GET 除外 | — |
|
||
| 响应结构 | ✅ | — |
|
||
| 需要认证？ | ❌ | true |
|
||
| 需要权限？ | ❌ | true |
|
||
| 分页？ | ❌ | GET 列表自动加 |
|
||
|
||
### 2. 生成文件
|
||
|
||
生成 Controller、Service、FormRequest、Model（如不存在）、路由。分层约定与完整模板见 **Tier 3**。
|
||
|
||
### 3. 遵循项目约定
|
||
|
||
生成前扫描：`app/Controller/` 现有模式、`AbstractController` 基类、`AppExceptionHandler`、中间件注册方式。
|
||
|
||
### 4. 异常体系
|
||
|
||
- `BusinessException` — 404/403/409/422 等可预期业务错误
|
||
- `ValidationException` — FormRequest 校验失败
|
||
- `SystemException` — 500 系统故障，记录堆栈并通知运维
|
||
|
||
异常选择决策与 `AppExceptionHandler` 实现见 **Tier 3**。
|
||
|
||
## 验证
|
||
|
||
1. [ ] `php -l` 编译无错误
|
||
2. [ ] FormRequest rules 覆盖所有请求字段
|
||
3. [ ] 错误处理覆盖 400/401/403/404/422/500
|
||
4. [ ] Service 使用事务包裹写操作
|
||
5. [ ] 路由遵循 RESTful 命名（复数名词、kebab-case）
|
||
6. [ ] 中间件正确挂载（认证 + 权限）
|
||
7. [ ] 可预期错误使用 `BusinessException`
|
||
8. [ ] 不可预期错误使用 `SystemException`
|
||
9. [ ] `SystemException` 不向客户端暴露内部细节
|
||
10. [ ] `AppExceptionHandler` 已注册在 `config/autoload/exceptions.php`
|
||
|
||
## Tier 3 深度参考
|
||
|
||
| 文件 | 内容 |
|
||
|------|------|
|
||
| `references/code-templates.md` | Controller/Service/FormRequest/路由完整模板 |
|
||
| `references/exception-handling.md` | 分级异常体系与 AppExceptionHandler 实现 |
|