详解：REST API 中常见的 HTTP 请求参数

HTTP 请求中的请求参数解释

当客户端发起 HTTP 请求 时，它们可以在 URL 末尾添加请求参数（也叫查询参数或 URL 参数）来传递数据。这些参数以键值对的形式出现在 URL 中，方便浏览和操作。

请求参数示例

以下是一些带有请求参数的 URL 示例：

    /users?id=1234
    /posts?category=tech&sort=asc
    /search?q=hello+world

这些参数出现在 ? 之后，并使用 & 分隔，每个参数都能够被服务器读取以便处理请求。

为什么需要请求参数？

请求参数作为 REST API 的一部分，具备多项优势：

• 简单易用：通过 URL 附加键值对，是传递数据的一种简便手段，减少了复杂请求体的需求。
• 灵活性高：你可以根据需要组合不同的参数，轻松引入新参数而不会影响现有的客户端。
• 缓存优势：不同参数对应的 URL 可以分别被浏览器和内容分发网络（CDNs）缓存。
• 书签化：包含参数的 URL 可以轻松创建书签保存。
• 日志记录：参数值在服务器日志中直接可见，便于跟踪和分析。

• 编码支持：URL 支持对参数值进行编码，例如将空格编码为 %20。
  综合来看，请求参数为 REST API 提供了一种高效传递数据的方式。

  四种主要的 API 参数类型

  请求参数主要有四种类型：

  查询参数 (Query Parameters)

  这是最常见的参数类型，附加在 URL 路径的 ? 之后：

  /users?page=1&per_page=20

  查询参数适用于过滤、排序、分页和简单查询。

  路径参数 (Path Parameters)

  这些参数通常嵌入在 URL 路径中：

  /users/{userId}

  这种方式能够让标识符和固定属性直接出现在资源路径上，增加 API 的自描述性。

  HTTP 请求头参数 (Header Parameters)

  头部参数提供了关于请求的元数据，比如内容类型、认证信息等。这些参数位于 HTTP 请求头中，与请求体分离。
  示例：

  Content-Type: application/json
  Authorization: Bearer <token>

  请求体参数 (Body Parameters)

  这些参数包含请求体中的数据，通常用于 POST、PUT 和 PATCH 请求来传输如 JSON 对象或表单数据的实际内容。
  示例：

  {
    "username": "example",
    "password": "password123"
  }

  使用 HTTP 方法的请求参数

  GET 请求的参数

  GET 请求通常使用查询参数，适用于过滤结果、分页和排序。查询参数的例子：

  GET /users?status=active&sort=-createdAt

  POST 请求的参数

  虽然 POST 请求可以包含查询参数，但一般避免这么做。应该使用路径参数来识别资源，并将其他数据放入请求体中：

  POST /users/{userId}/comments
  {
    "text": "Hello World!"
  }

  PUT 请求的参数

  与 POST 类似，PUT 请求应使用路径参数来识别资源，并将需要更新的数据放在请求体中：

  PUT /users/{userId}
  {
    "firstName": "Jane"
  }

  PATCH 请求的参数

  PATCH 请求用于部分更新已有资源，仅发送需要修改的数据，优化网络流量。
  示例：

  PATCH /api/users/123
  {
    "age": 40,
    "city": "New York"
  }

  API 工具中使用请求参数

  Apifox  是一个 API 文档工具，能根据请求参数等信息生成详尽的 API 文档。

  请求参数文档

  在 Apifox 中，可以记录请求参数的名称、类型、描述及验证规则，确保使用 API 的开发人员清楚每个请求的预期数据。

代码中访问参数

在服务器端，可以从请求中提取和验证参数再使用。在 Express 中，参数储存在 req.params 和 req.query 对象中。
示例：

    app.get('/users', (req, res) => {
      const sort = req.query.sort;
      const limit = req.query.limit;
      
      // ...
    });

客户端可以使用类似 qs 的库来生成和解析参数字符串。

参数验证

验证请求参数是避免安全问题和数据错误的重要步骤：

• 类型检查：确保参数类型正确（如数字、字符串）。
• 值检查：验证值的合法性（如范围、模式）。
• 必要性：确保关键参数存在。

• 清理：防止 XSS 和其他注入攻击。
  如 Express Validator 等库能使参数验证更为简便。

  总结

  请求参数使得数据传输更加简便、灵活，并且符合 REST 原则。
  在使用请求参数时，最佳实践包括：

• 对于 GET 请求使用查询参数，对于其他方法使用路径参数。
• 避免在请求体中使用查询参数，应该将数据放在请求体内。
• 同时验证、清理和记录参数。
• 在 API 之间保持参数的一致性。

通过这些策略，可以构建出高效、安全的 API 系统。