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 系統。