vibe_coding/.cursor/skills/api-scaffold/SKILL.md

name, version, description

name	version	description
api-scaffold	3.0.0	生成 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 实现