Pressidian

Appearance

RestfulAPI ​

RESTful API（Representational State Transfer，表述性状态转移）是一种基于HTTP协议设计接口的规范，旨在通过统一的规则实现客户端与服务器之间的高效通信。它并非严格的标准，而是一组设计原则，强调简洁、可扩展、无状态，广泛应用于前后端分离、移动应用与服务器交互等场景。

1 RESTful API的核心原则 ​

  1. 资源（Resource）为中心

    • 一切数据、服务或实体都被视为“资源”，并通过URI（统一资源标识符） 唯一标识。
    • 示例：
      • 用户资源：/users（所有用户）、/users/123（ID为123的用户）
      • 文章资源：/articles（所有文章）、/articles/456/comments（文章456的评论）

  2. 使用HTTP方法表达操作语义

    • 利用HTTP的标准方法（动词）描述对资源的操作，而非通过URI中的动词（如/getUser）。常见方法及含义：
      • GET：获取资源（只读，无副作用）
        • 示例：GET /users（获取所有用户）、GET /users/123（获取用户123）
      • POST：创建新资源
        • 示例：POST /users（提交用户数据，创建新用户）
      • PUT：全量更新资源（需提供资源完整信息）
        • 示例：PUT /users/123（更新用户123的所有信息）
      • PATCH：部分更新资源（仅提供需修改的字段）
        • 示例：PATCH /users/123（仅更新用户123的邮箱）
      • DELETE：删除资源
        • 示例：DELETE /users/123（删除用户123）

  3. 无状态（Stateless）

    • 服务器不存储客户端的状态信息，每次请求必须包含所有必要数据（如身份验证令牌），便于服务器水平扩展。

  4. 资源的表述（Representation）

    • 资源的“表述”是传输的数据格式（如JSON、XML），客户端与服务器通过Accept（请求期望格式）和Content-Type（响应实际格式）头协商。
    • 示例：客户端请求Accept: application/json，服务器返回JSON格式数据。

  5. 返回合适的HTTP状态码

    • 用标准状态码表示请求结果，避免自定义错误码：
      • 2xx（成功）：200（OK，请求成功）、201（Created，资源创建成功）
      • 4xx（客户端错误）：400（Bad Request，请求参数错误）、404（Not Found，资源不存在）、401（Unauthorized，未认证）、403（Forbidden，权限不足）
      • 5xx（服务器错误）：500（Internal Server Error，服务器内部错误）

2 RESTful API的设计最佳实践 ​

  1. URI命名规范

    • 用名词复数表示资源集合（如/users而非/user），避免动词（如/deleteUser）。
    • 层级结构体现资源关系（如/articles/456/comments表示“文章456的评论”）。
    • 用小写字母，单词间用连字符-分隔（如/user-profiles），避免下划线或骆驼峰。

  2. 过滤、排序、分页与搜索

    • 通过查询参数（Query Parameters） 处理资源的筛选，而非修改URI路径：
      • 分页：/users?page=2&size=10（第2页，每页10条）
      • 排序：/articles?sort=createdAt&order=desc（按创建时间倒序）
      • 过滤：/users?role=admin（只返回管理员用户）
      • 搜索：/articles?search=restful（搜索含“restful”的文章）

  3. 版本控制

    • 为避免API变更影响客户端，需明确版本：
      • 方式1：URI路径包含版本：/v1/users、/v2/articles
      • 方式2：通过请求头：Accept: application/vnd.company.v1+json

  4. 错误处理

    • 除状态码外，响应体应包含错误详情（如错误码、描述）：
      json
      {
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户ID 123不存在"
  }
}

  5. HATEOAS（超媒体作为应用状态引擎）

    • 响应中包含相关资源的链接，引导客户端自动发现可执行的操作（进阶原则，非必需）：
      json
      {
  "id": 123,
  "name": "张三",
  "links": {
    "self": "/users/123",
    "articles": "/users/123/articles"  // 该用户的文章链接
  }
}

3 RESTful API的优势与局限性 ​

  • 优势：

    • 基于HTTP标准，无需额外学习新协议，兼容性强。
    • 无状态设计便于服务器集群扩展，适合分布式系统。
    • 简洁的URI和语义化方法使接口直观易懂，降低维护成本。

  • 局限性：

    • 不适合实时通信（如聊天、股票行情），需结合WebSocket等技术。
    • 复杂操作（如多资源联动）难以用单一HTTP方法表达，可能需妥协设计。