1. 概述

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

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

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

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

示例：

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

特點(diǎn)：

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

• 適用于篩選、分頁(yè)、搜索等查詢(xún)類(lèi)條件。

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

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

典型場(chǎng)景：

• 列表分頁(yè)

• 條件檢索

• 排序字段傳遞

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

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

示例：

GET /api/dish/10

特點(diǎn)：

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

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

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

典型場(chǎng)景：

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

• 刪除某條記錄

• 查詢(xún)某個(gè)資源的子資源

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

位置：

放置在 HTTP 請(qǐng)求體（Request Body）中。

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

• JSON（最常用）

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

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

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

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

示例（JSON）：

{
  "name": "魚(yú)香肉絲",
  "price": 20,
  "status": 1
}

特點(diǎn)：

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

• 不受 URL 長(zhǎng)度限制。

• 主要用于 POST、PUT、PATCH 請(qǐng)求。

典型場(chǎng)景：

• 新增資源

• 修改資源

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

• 上傳文件

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

位置：
寫(xiě)入 HTTP Header 中。

示例：

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

特點(diǎn)：

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

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

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

典型場(chǎng)景：

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

• 設(shè)置 Content-Type

• API 版本信息

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

3. 非主流但常見(jiàn)的方式

3.1 Cookies

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

特點(diǎn)：

• 瀏覽器自動(dòng)附帶，無(wú)需手動(dòng)傳遞。

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

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

例如 #section1

不參與 HTTP 請(qǐng)求，在 API 中不使用，僅用于前端頁(yè)面定位。

4. 四類(lèi)主要參數(shù)的對(duì)比

5. 使用建議（最佳實(shí)踐）

• 查詢(xún)參數(shù)使用 Query。如分頁(yè) page、pageSize。

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

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

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

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

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

6. 總結(jié)

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

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

最新評(píng)論