1. 概述

在 Web API 設(shè)計中，客戶端需要通過多種方式向服務(wù)端傳遞參數(shù)。根據(jù) HTTP 協(xié)議和 RESTful 風(fēng)格，常見的參數(shù)傳遞方式包括：Query Parameters、Path Parameters、Body Parameters 和 Header Parameters。本規(guī)范文檔對各類參數(shù)的用途、特點與使用場景進(jìn)行統(tǒng)一說明。

2. 參數(shù)傳遞方式分類

2.1 Query Parameters（查詢參數(shù)）

位置：
附加在 URL 的 ? 之后，以 key=value 形式出現(xiàn)，多個參數(shù)使用 & 分隔。

示例：

GET /api/dish?page=1&pageSize=10&name=魚香肉絲

特點：

• 參數(shù)直接暴露在 URL 上。

• 適用于篩選、分頁、搜索等查詢類條件。

• 一般用于 GET 請求（但其他方法也可以使用）。

• 參數(shù)長度受 URL 長度限制，不適合傳輸大數(shù)據(jù)。

典型場景：

• 列表分頁

• 條件檢索

• 排序字段傳遞

2.2 Path Parameters（路徑參數(shù)）

位置：
作為 URL 路徑的一部分，用于定位資源。

示例：

GET /api/dish/10

特點：

• 表達(dá)資源層級結(jié)構(gòu)，更符合 RESTful 風(fēng)格。

• 參數(shù)不可省略，通常代表唯一性標(biāo)識（如 ID）。

• 僅在 URL 中傳遞，不出現(xiàn)在請求體中。

典型場景：

• 獲取某條記錄（如 /user/1）

• 刪除某條記錄

• 查詢某個資源的子資源

2.3 Body Parameters（請求體參數(shù)）

位置：

放置在 HTTP 請求體（Request Body）中。

常見數(shù)據(jù)格式：

• JSON（最常用）

• application/x-www-form-urlencoded（傳統(tǒng)表單格式）

• multipart/form-data（文件上傳）

• XML（現(xiàn)較少使用）

• binary（二進(jìn)制，如圖片、視頻）

示例（JSON）：

{
  "name": "魚香肉絲",
  "price": 20,
  "status": 1
}

特點：

• 參數(shù)不暴露在 URL 上，適合傳輸復(fù)雜對象。

• 不受 URL 長度限制。

• 主要用于 POST、PUT、PATCH 請求。

典型場景：

• 新增資源

• 修改資源

• 批量提交數(shù)據(jù)

• 上傳文件

2.4 Header Parameters（請求頭參數(shù)）

位置：
寫入 HTTP Header 中。

示例：

Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
token: xxxxxxx

特點：

• 參數(shù)不顯示在 URL 和 Body 中。

• 主要用于傳遞認(rèn)證信息、格式聲明等元數(shù)據(jù)。

• 不推薦用于傳遞業(yè)務(wù)數(shù)據(jù)。

典型場景：

• JWT Token 身份認(rèn)證

• 設(shè)置 Content-Type

• API 版本信息

• 語言設(shè)置（Accept-Language）

3. 非主流但常見的方式

3.1 Cookies

用于在瀏覽器環(huán)境中自動攜帶狀態(tài)信息，常見于登錄狀態(tài)維持。

特點：

• 瀏覽器自動附帶，無需手動傳遞。

• 后端可讀取 Cookie 獲取用戶憑證或偏好設(shè)置。

3.2 URL Fragment（片段標(biāo)識符）

例如 #section1

不參與 HTTP 請求，在 API 中不使用，僅用于前端頁面定位。

4. 四類主要參數(shù)的對比

5. 使用建議（最佳實踐）

• 查詢參數(shù)使用 Query。如分頁 page、pageSize。

• 資源標(biāo)識使用 Path。如 /user/{id}。

• 新增/修改使用 Body（JSON）。

• 認(rèn)證信息使用 Header（如 Authorization）。

• 避免在 Header 中傳遞業(yè)務(wù)字段。

• 避免在 Query 或 Path 中傳輸過多復(fù)雜數(shù)據(jù)。

6. 總結(jié)

API 參數(shù)傳遞主要包含四種方式：Query、Path、Body 和 Header。它們各自適用于不同場景，合理選擇傳參方式有助于接口保持語義清晰、結(jié)構(gòu)規(guī)范、易于維護(hù)。

到此這篇關(guān)于java中4種API參數(shù)傳遞方式統(tǒng)一說明的文章就介紹到這了,更多相關(guān)java API參數(shù)傳遞方式內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評論