⚡

RESTAPI设计技能Skill rest-api-design

本技能提供RESTful API设计的专家级指导，涵盖资源命名、HTTP方法、状态码、版本控制、分页、HATEOAS和错误处理等核心原则与最佳实践。适用于API设计、后端开发、微服务架构等场景，帮助开发者构建规范、可维护、易用的Web服务接口。关键词：REST API设计，API版本控制，分页实现，HATEOAS，错误处理，OpenAPI文档，微服务架构。

后端开发 0 次安装 0 次浏览 更新于 2/26/2026

name: rest-api-design description: RESTful API设计原则、版本控制、分页、HATEOAS和文档。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep

REST API 设计技能

遵循最佳实践设计RESTful API的专家级协助。

能力

  • 设计面向资源的API
  • 实现正确的HTTP方法和状态码
  • 配置API版本控制策略
  • 实现分页模式
  • 设计错误响应
  • 应用HATEOAS原则

使用场景

在以下情况时调用此技能：

  • 设计新的REST API
  • 评审现有的API设计
  • 实现分页
  • 定义错误处理
  • 版本化API

设计原则

资源命名

# 良好 - 名词，复数形式
GET /api/users
GET /api/users/123
GET /api/users/123/posts

# 不佳 - 动词，URL中包含动作
GET /api/getUsers
GET /api/users/123/getPosts
POST /api/createUser

HTTP方法

方法 用途 响应
GET 读取资源 200 OK
POST 创建资源 201 Created
PUT 替换资源 200 OK
PATCH 部分更新 200 OK
DELETE 删除资源 204 No Content

分页响应

{
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "totalPages": 10
  },
  "links": {
    "self": "/api/users?page=1",
    "next": "/api/users?page=2",
    "prev": null
  }
}

错误响应

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "验证失败",
    "details": [
      { "field": "email", "message": "邮箱格式无效" }
    ]
  }
}

最佳实践

  • 使用正确的HTTP状态码
  • 实现一致的错误响应
  • 从一开始就对API进行版本控制
  • 使用OpenAPI进行文档化

目标流程

  • api-design
  • backend-development
  • microservices-architecture