用途:该技能面向 RESTful API 设计,提供资源命名、HTTP 方法、状态码、错误处理等最佳实践,适用于设计新 API 或统一现有接口规范。
主要能力:
- 资源与 URL 设计:以名词表示资源,集合用复数(如 /users、/products),嵌套资源最多两层,避免过深嵌套。
- HTTP 方法语义:GET 读取、POST 创建、PUT 替换、PATCH 更新、DELETE 删除,并区分幂等与安全性。
- 无状态:每个请求自带全部信息,推荐在 Authorization 头中传 Bearer Token,而非依赖服务端会话。
- 查询参数:支持过滤、排序(如 sort=-price 表示降序)、分页(page/limit、offset/limit、cursor/limit)、字段选择与搜索。
- 版本控制:常见为 URL 路径版本(/api/v1/users),也支持请求头或查询参数方式。
- 状态码:2xx 成功(200、201、204)、4xx 客户端错误(400、401、403、404、409、422、429)、5xx 服务端错误(500、503)。
- 错误格式:统一结构含 error、message、details、requestId、documentation,并提及 RFC 7807 Problem Details。
- 分页:偏移分页与游标分页(推荐),支持 RFC 5988 Link 头。
- 响应约定:统一 data/meta 信封、ISO 8601 时间戳、字符串 ID、HATEOAS 链接。
- 限流与安全:X-RateLimit-* 与 Retry-After 头、CORS、helmet、Content-Type 校验。
- 幂等性:通过 Idempotency-Key 头避免重复提交。
使用方式:资料未提供具体安装命令或调用步骤,仅以规范与代码片段形式给出设计指导。
适用场景:设计新 API、审查现有接口、统一团队接口规范。
限制:资料未说明收费、价格、平台支持或实际运行效果,相关事实暂未提供。