AGENT SKILL
restful-api-standard
企业级 RESTful API 设计准则
- License 许可
- MIT
- 最近更新
- 2026-08-25
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- restful-api-standard
- version
- 1.0.0
- namespace
- web
- skillType
- rule
- description
- 企业级 RESTful API 设计准则
02 资源文件 1
- 参考文档skill.json1.6 KB
03 SKILL.md 正文
企业级 RESTful API 设计准则
在生成任何 API 接口、路由定义与控制器时,AI 必须严格执行以下设计标准。
一、 URL 命名与路由层级
- 全名词复数:使用资源复数名词,严禁在 URL 中出现动词(动词由 HTTP Method 表达)。
- ❌
/api/getUserInfo//api/deleteOrder - ✅
GET /api/v1/users/{id}/DELETE /api/v1/orders/{id}
- ❌
- 层级从属表达:子资源嵌套在父资源之后。
- ✅
GET /api/v1/users/{userId}/orders
- ✅
- Kebab-Case:URL 路径全小写并用连字符连接(如
/api/v1/payment-methods)。
二、 HTTP 谓词与状态码契约
GET:安全且幂等,查询资源。200 OKPOST:创建资源。成功返回201 Created+Location头。PUT:全量替换(幂等)。200 OK或204 No ContentPATCH:局部更新。200 OKDELETE:删除资源(幂等)。成功返回204 No Content或200 OK- 错误状态码:
400 Bad Request(参数格式错误)401 Unauthorized(未认证/Token 失效)403 Forbidden(已认证但无权限)404 Not Found(资源不存在)409 Conflict(唯一约束/状态机冲突)422 Unprocessable Entity(业务逻辑校验失败)
三、 统一响应体信封 (Envelope)
{
"code": 0,
"message": "success",
"data": { ... },
"meta": {
"page": 1,
"pageSize": 20,
"total": 100
},
"traceId": "c98a1f87-6e42-4b2a"
}
04 同仓库更多 Skills
web-page-extractor
网页正文智能提纯与清洗工具。抓取网页并剔除 HTML 标签、脚本与样式,输出高信息密度的 Markdown。
★ 1
fetch-page
抓取网页并提取标题与正文长度,需要网络权限(默认策略为拒绝,须授权)。
★ 1
api-tester-toolkit
API 接口网络测试与耗时诊断工具包。发起 HTTP GET/POST 请求、统计响应耗时与状态码、检查响应数据。
★ 1
semver-bump
语义化版本号升级:major / minor / patch。
★ 1
translate
中英互译演示实现,内置小词典,用于演示翻译类 skill 的检索与调用。
★ 1
summarize
把长文本压缩成简短摘要,适合会议记录、文章、文档的快速概览。
★ 1