---
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 实现 |