Hello API
Developmenthello-apiHello API is an Agent Skill for development published in the hellowind777/helloagents repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
构建、修改或审查 REST API、GraphQL 端点、webhook、中间件、请求/响应处理、API 版本管理、限流或分页时使用。
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/hellowind777/helloagents/blob/HEAD/skills/hello-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/hello-api, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
API 相关代码必须遵循以下规范。
编码前
先确定资源模型和端点契约,再写代码。
RESTful 设计
- 资源命名:复数名词
/users,嵌套/users/:id/posts - HTTP 方法语义:GET 读、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除
- 状态码准确:200 成功、201 创建、204 无内容、400 参数错误、401 未认证、403 无权限、404 不存在、409 冲突、422 验证失败、500 服务端错误
请求验证
- 入参验证在 controller 层,使用 schema 验证库(zod、joi、ajv)
- 验证类型、范围、格式、必填
- 文件上传限制大小和类型
- 请求体大小限制
响应格式
- 统一成功响应:
{ data, meta? } - 统一错误响应:
{ error: { code, message, details? } } - 列表接口必须分页:
?page=1&limit=20或 cursor-based - 支持排序:
?sort=created_at&order=desc - 过滤参数白名单
版本与保护
- API 版本化:URL 前缀
/v1/或 header - 限流保护:按 IP/用户/API key
- 超时设置:所有外部调用设超时
- CORS:明确允许的 origin,不用
*
交付检查
- 状态码准确反映操作结果
- 所有入参已验证
- 列表接口有分页
- 错误响应格式统一
- 有限流保护