mcpField

api-design

github.com/eddiebe147开发40 次安装
代码仓库

关于 api-design

面向开发者的 REST API 设计参考，涵盖端点、请求与响应格式、状态码、版本管理和安全实践。

主要功能

  1. 01HTTP 方法与 URL 规范
  2. 02状态码使用指南
  3. 03集合与错误响应格式
  4. 04筛选、排序与分页
  5. 05幂等性与版本管理
  6. 06输入验证与安全建议

适用场景

  1. 01设计 CRUD 端点
  2. 02统一 API 错误响应
  3. 03添加分页与筛选
  4. 04规划 API 破坏性变更

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/eddiebe147/claude-settings --skill api-design

安装后在 Claude Code 中输入/api-design确认已加载。

详细介绍

REST API 设计原则

URL 结构

GET    /api/v1/resources           # List all
GET    /api/v1/resources/{id}      # Get one
POST   /api/v1/resources           # Create
PUT    /api/v1/resources/{id}      # Replace
PATCH  /api/v1/resources/{id}      # Partial update
DELETE /api/v1/resources/{id}      # Delete

# Nested resources
GET    /api/v1/parents/{id}/children
POST   /api/v1/parents/{id}/children

HTTP 状态码

代码含义使用场景
200正常GET、PUT、PATCH 请求成功
201已创建POST 请求成功（新资源）
204无内容DELETE 请求成功
400错误请求验证错误、请求格式错误
401未授权缺少或无效的身份验证
403禁止访问身份验证有效，但没有权限
404未找到资源不存在
409冲突重复项、状态冲突
422无法处理语义错误
500服务器错误意外错误

请求/响应设计

集合响应
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 150,
    "totalPages": 8
  }
}
单个资源响应
{
  "id": "uuid",
  "name": "Resource Name",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}
错误响应
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": [
      {"field": "name", "message": "must not be blank"}
    ]
  }
}

查询参数

# Filtering
GET /api/v1/resources?status=active&type=premium

# Sorting
GET /api/v1/resources?sort=createdAt,desc

# Pagination
GET /api/v1/resources?page=1&pageSize=20

# Field selection
GET /api/v1/resources?fields=id,name,status

# Search
GET /api/v1/resources?search=query

幂等性

  • 使用唯一标识符的 POST 请求遇到重复项时，应返回现有资源（200）
  • PUT/DELETE 应具备幂等性
  • 使用 Pair<Result, Boolean> 模式指示资源是新建还是已存在

版本控制

  • 使用 URL 路径进行版本控制：/api/v1/、/api/v2/
  • 进行不兼容变更时更新版本
  • 在迁移期间支持旧版本

安全注意事项

  • 始终在 API 边界验证输入
  • 使用参数化查询（JOOQ 会处理此事）
  • 在服务层检查授权
  • 切勿暴露内部 ID 或敏感数据
  • 对公开端点实施速率限制

评论

支持 Markdown