最佳实践：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 系统。