3. ResfulApi 接口开发规范？

userLee
172 阅读4分钟

RESTful API 是一种基于 REST（Representational State Transfer）架构风格的 Web 服务设计规范。它并不是一个标准，而是一个设计理念，旨在通过简洁、易于理解的方式设计 Web 服务接口。

RESTful API 设计遵循以下几个核心原则：

  1. 无状态性 (Stateless) ：

    • 每个请求都必须包含足够的信息，以便服务端理解和处理该请求。每个请求都独立，服务器不会存储客户端的状态。
    • 例如，服务器不存储上次客户端请求的信息，客户端必须在每个请求中提供所需的所有信息（如认证凭证）。

  2. 客户端-服务器 (Client-Server) ：

    • 客户端和服务器应该解耦，客户端只关心如何展示数据，服务器则负责存储数据和业务逻辑处理。
    • 客户端不需要知道服务器内部的实现细节，服务器也不需要知道客户端的具体展示方式。

  3. 统一接口 (Uniform Interface) ：

    • RESTful API 定义了统一的接口，通过 HTTP 协议的标准方法（如 GET、POST、PUT、DELETE 等）来进行操作。

    • URI（Uniform Resource Identifier）是 RESTful API 中的核心，通过 URL 进行资源的标识和访问。

    • 常见的 RESTful 方法：

      • GET：读取数据（例如获取某个资源或数据列表）
      • POST：创建数据（例如提交表单或新增资源）
      • PUT：更新数据（例如更新资源）
      • DELETE：删除数据（例如删除资源）

      所有的操作都通过操作资源的 HTTP 方法来进行。每个方法对应了对资源的不同操作 例如：

      • GET /books：请求所有书籍的列表（检索资源）。
      • GET /books/123：请求书籍 ID 为 123 的资源（检索单一资源）。
      • POST /books：提交新的书籍信息来创建书籍（创建资源）。
      • PUT /books/123：更新 ID 为 123 的书籍信息（更新资源）。
      • DELETE /books/123：删除 ID 为 123 的书籍（删除资源）

  4. 资源导向 (Resources) ：

    • 在 REST 中，所有的对象（或数据）被视为“资源”，通过唯一的 URL 来标识。
    • 每个资源通过 HTTP 方法进行操作。通常，资源是指数据模型或实体（如用户、商品、订单等），它们可以通过 URL 进行访问。
    • 例如，https://api.example.com/users 可能表示用户列表，https://api.example.com/users/1 可能表示用户 ID 为 1 的资源。

  5. 表现层（Representation） ：

    • 客户端与服务器之间传递的是资源的表现（即资源的不同视图），而不是资源本身。
    • 资源可以有多种表现形式，如 JSON、XML、HTML 等，最常见的是 JSON 格式。

  6. 可缓存性 (Cacheable) ：

    • 由于 REST 是基于 HTTP 协议的，HTTP 本身提供了缓存机制（如缓存头信息）。通过合理利用缓存，可以提高 API 性能和响应速度。
    • 对于可以缓存的响应，客户端可以缓存结果，减少与服务器的交互。

  7. 分层系统 (Layered System) ：

    • RESTful 系统可以通过多个层次来实现，比如客户端与服务器之间可以通过中间层（如负载均衡、代理服务器）进行交互，透明地提供扩展性。
    • 客户端不必直接与数据库或数据存储交互，而是通过中间层来完成操作。

RESTful API 的设计规范

  1. 资源 URI 设计

    • URI 应该直观地反映资源的结构，遵循名词复数形式，通常使用 / 分隔资源。

    • 例如：

      • /users：表示用户列表。
      • /users/{id}：表示单个用户资源，其中 {id} 是用户的唯一标识符。
      • /posts/{postId}/comments：表示某个帖子下的评论资源。

  2. HTTP 方法的使用

    • 使用标准的 HTTP 方法来执行对资源的操作：

      • GET /users：获取所有用户信息。
      • POST /users：创建新的用户。
      • GET /users/{id} ：获取某个特定用户的信息。
      • PUT /users/{id} ：更新某个特定用户的信息。
      • DELETE /users/{id} ：删除某个特定用户。

  3. 响应状态码

    • 返回标准的 HTTP 状态码，以指示请求的成功或失败：

      • 200 OK：请求成功（常见于 GET、PUT、DELETE）。
      • 201 Created：资源成功创建（常见于 POST 请求）。
      • 400 Bad Request：请求无效或格式错误。
      • 404 Not Found：请求的资源不存在。
      • 500 Internal Server Error：服务器内部错误。

  4. 请求和响应格式

    • 请求和响应通常使用 JSON 格式，除非另有要求（如 application/xml）。应确保请求体和响应体有清晰的结构，通常是对象或数组。

    • 请求示例（POST 请求创建用户） ：

      json
{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}

    • 响应示例（GET 请求获取用户信息） ：

      json
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30
}
avatar
文章
阅读
粉丝