處理Web請求路徑參數

1. 路徑變量（Path Variable）

2. 查詢參數（Query Parameter）

3. 表單參數（Form Data）

4. 請求體JSON參數（Request Body JSON）

5. 請求頭參數（Header Parameters）

6. 矩陣變量（Matrix Variables）

特殊：參數綁定

Content-Type（補充）

接口測試

(1) Header（請求頭參數）

(2) Query（查詢參數）

(3) Path（路徑變量）

(4) Body（請求體）

(5）binary（二進制數據）

(6）msgpack（MessagePack格式）

錯誤

1. 路徑變量（Path Variable）

寫法：

@GetMapping("/users/{id}")
public ResponseEntity<User> getUserById(@PathVariable Long id) {// 業務邏輯
}

特點：

使用@PathVariable注解
參數直接嵌入URL路徑中
RESTful風格推薦使用
適合必傳的、標識性的參數

ApiPost測試配置：

請求URL填寫：http://localhost:8080/users/123
請求方法選擇GET
不需要額外參數設置

2. 查詢參數（Query Parameter）

寫法：

@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(@RequestParam(required = false, defaultValue = "1") Integer page,@RequestParam(required = false, defaultValue = "10") Integer size) {// 業務邏輯
}

特點：

使用@RequestParam注解
參數以?key=value&key2=value2形式附加在URL后
適合可選參數、過濾條件
可以設置默認值和是否必需

ApiPost測試配置：

請求URL填寫：http://localhost:8080/users?page=2&size=20
或者使用ApiPost的"Params"選項卡添加參數：
- 參數名：page，值：2
- 參數名：size，值：20

3. 表單參數（Form Data）

寫法：

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestParam String username, @RequestParam String password) {// 業務邏輯
}

特點：

同樣使用@RequestParam注解
參數通過請求體發送（Content-Type: application/x-www-form-urlencoded）
適合POST請求中的簡單參數
參數不會顯示在URL中

ApiPost測試配置：

請求URL填寫：http://localhost:8080/users
請求方法選擇POST
在"Body"選項卡中選擇"form-data"或"x-www-form-urlencoded"
添加參數：
- 參數名：username，值：user1
- 參數名：password，值：123456

前三種方法對比

特性	路徑變量	查詢參數	表單參數
注解	@PathVariable	@RequestParam	@RequestParam
URL可見性	路徑部分可見	URL后可見	不可見
主要用途	資源標識	過濾、分頁等可選參數	POST請求的簡單參數
請求方法	通常GET	通常GET	通常POST/PUT
參數位置	URL路徑中	URL問號后	請求體中
適合參數類型	必傳、標識性參數	可選參數	簡單鍵值對參數

選擇建議

路徑變量：用于標識特定資源，如/users/{id}
查詢參數：用于過濾、排序、分頁等，如/users?role=admin&page=1
表單參數：用于簡單的POST表單提交，復雜數據建議使用JSON body

4. 請求體JSON參數（Request Body JSON）

寫法：

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody UserDTO userDTO) {// 業務邏輯
}

特點：

使用@RequestBody注解
接收JSON格式的請求體（Content-Type: application/json）
適合傳輸復雜的結構化數據
需要定義對應的DTO類
是REST API最常用的POST/PUT參數傳遞方式

ApiPost測試配置：

請求URL：http://localhost:8080/users
請求方法：POST
在"Body"選項卡中選擇"raw"和"JSON"
輸入JSON數據：

{"username": "testuser","password": "123456","email": "test@example.com"
}

5. 請求頭參數（Header Parameters）

寫法：

@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(@RequestHeader("Authorization") String authToken,@RequestHeader(value = "User-Agent", required = false) String userAgent) {// 業務邏輯
}

特點：

使用@RequestHeader注解
從HTTP請求頭中獲取參數
常用于認證令牌、設備信息等
可以設置是否必需

ApiPost測試配置：

請求URL：http://localhost:8080/users
請求方法：GET
在"Headers"選項卡中添加：
- Authorization: Bearer xxxxxxxx
- User-Agent: ApiPost/1.0

6. 矩陣變量（Matrix Variables）

寫法：

// 需要先啟用矩陣變量（Spring Boot默認禁用）
@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void configurePathMatch(PathMatchConfigurer configurer) {configurer.setUseSuffixPatternMatch(false);configurer.setUseRegisteredSuffixPatternMatch(true);configurer.setUseTrailingSlashMatch(true);}
}// 控制器中使用
@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable String id,@MatrixVariable(pathVar = "id") Map<String, String> matrixVars) {// 業務邏輯
}

特點：

使用@MatrixVariable注解
URL格式：/users/id;key=value;key2=value2
允許在路徑段中添加鍵值對參數
需要額外配置啟用
使用較少，但在某些特殊場景有用

ApiPost測試配置：

請求URL：http://localhost:8080/users/123;department=IT;role=admin
請求方法：GET
不需要額外參數設置

六種寫法的完整對比

類型	注解	位置	常用場景	Content-Type	示例URL
路徑變量	`@PathVariable`	URL路徑	資源標識	無	`/users/123`
查詢參數	`@RequestParam`	URL后	過濾/分頁	無	`/users?page=1`
表單參數	`@RequestParam`	請求體	簡單表單	`x-www-form-urlencoded`	`/users`?(POST)
JSON參數	`@RequestBody`	請求體	復雜數據	`application/json`	`/users`?(POST)
矩陣變量	`@MatrixVariable`	URL路徑段	特殊場景	無	`/users/123;dept=IT`
請求頭	`@RequestHeader`	HTTP頭	認證/元數據	無	`/users`?(帶Headers)

特殊：參數綁定

可以直接用對象類接收傳遞的 Web 請求路徑參數（或查詢參數），通常稱為?"參數綁定"（Parameter Binding）?或?"對象封裝"，

后端框架（如 Spring MVC）會自動將這些鍵值對映射到對象的屬性上，前提是屬性名與參數名匹配。

這種方式的優點是：

避免在方法中寫大量 @RequestParam 注解。
直接面向業務對象編程，更符合 OOP 思想。

注意事項

屬性名匹配：前端參數名必須與對象字段名一致（或通過注解配置映射關系）。
類型轉換：框架會自動處理簡單類型（如 String/int），但復雜類型（如日期）可能需要自定義轉換器。
嵌套對象：部分框架支持嵌套對象綁定（如 user.name=John），但需明確約定參數命名格式。

1. 查詢參數（Query Parameters）的典型形式

前端請求的 URL 通常如下：

GET /api/users?name=John&age=25&city=Beijing

?后端用對象接收：

// Spring Boot 示例
@GetMapping("/api/users")
public ResponseEntity<?> getUsers(UserQuery query) {// query 會自動封裝 name="John", age=25, city="Beijing"// ...
}// 封裝參數的對象
public class UserQuery {private String name;private Integer age;private String city;// getters/setters
}

2. 路徑參數（Path Variables）

URL 示例：

GET /api/users/123

后端對象綁定（需配合注解）：

@GetMapping("/api/users/{id}")
public ResponseEntity<?> getUser(@PathVariable("id") Long id) {// 直接提取路徑參數 id=123
}// 如果用對象接收（需框架支持，如 Spring 的 @ModelAttribute）：
@GetMapping("/api/users/{id}")
public ResponseEntity<?> getUser(@ModelAttribute UserQuery query) {// 需要 query 中有 id 字段
}

3. 表單數據（Form Data）

表單 POST 請求：
前端提交 Content-Type: application/x-www-form-urlencoded，后端同樣可以用對象接收。

// 前端請求：POST /api/users （Body: name=John&age=25，Content-Type: application/x-www-form-urlencoded）
@PostMapping("/api/users")
public ResponseEntity<?> createUser(UserForm form) {// form 對象會填充 name="John", age=25
}

4. JSON 請求體（Request Body）

JSON 請求體：
需用 @RequestBody 明確標識：

@PostMapping("/api/users")
public ResponseEntity<?> createUser(@RequestBody UserRequest request) {// 接收 JSON 數據，如 {"name": "John", "age": 25}
}

無注解對象綁定適用于以下兩種數據傳遞方式：

查詢參數（URL 的 ?key=value，所有 HTTP 方法均支持）。
表單數據（請求體的 key=value 格式，需 Content-Type: application/x-www-form-urlencoded，通常用于 POST/PUT）。

Content-Type（補充）

在HTTP請求和響應中，Content-Type是一個非常重要的頭部字段，它用于指示發送或接收的數據的媒體類型（MIME類型），幫助客戶端和服務器正確解析和處理數據。

Content-Type是HTTP協議的一個請求/響應頭，用于指定：

請求中：客戶端發送給服務器的數據格式（如JSON、表單等）。
響應中：服務器返回給客戶端的數據格式（如HTML、JSON等）。

如果沒有正確設置Content-Type，服務器可能無法正確解析請求數據，導致400 Bad Request等錯誤。

類型	`Content-Type`	用途	后端接收方式
JSON	`application/json`	REST API傳輸對象	`@RequestBody`
表單	`x-www-form-urlencoded`	普通表單提交	`@RequestParam`
文件	`multipart/form-data`	文件上傳	`@RequestParam + MultipartFile`
純文本	`text/plain`	日志/文本數據	`@RequestBody String`
HTML	`text/html`	返回網頁	通常由模板引擎處理

接口測試

在接口測試時，選擇 Header、Query、Path、Body 等選項取決于你的接口設計參數傳遞方式。

(1) Header（請求頭參數）

用途：傳遞認證信息（如Authorization）、客戶端信息（如User-Agent）等。

何時選擇：

接口需要token或API-KEY。
需要設置Content-Type、Accept等HTTP標準頭。

ApiPost配置：

在 Header 選項卡中添加鍵值對，例如：

Authorization: Bearer xxxxxx
Content-Type: application/json

(2) Query（查詢參數）

用途：URL問號后的參數（如?page=1&size=10），用于過濾、分頁等。

何時選擇：

參數是可選或非敏感數據（如分頁、排序字段）。
接口使用@RequestParam接收。

ApiPost配置：

在 Query 選項卡中添加參數，例如：

Key	Value
page	1
size	10

最終URL會自動拼接為：http://api.example.com/users?page=1&size=10。

(3) Path（路徑變量）

用途：RESTful風格URL中的變量（如/users/{id}）。

何時選擇：

接口URL包含動態路徑（如/users/123）。
后端使用@PathVariable接收。

ApiPost配置：

直接在URL中填寫路徑變量，例如

http://api.example.com/users/123

無需額外配置（除非工具支持路徑變量占位符）。

(4) Body（請求體）

用途：傳輸復雜數據（如JSON、表單、文件）。

何時選擇：

POST/PUT請求需要提交數據。
接口使用@RequestBody或@RequestParam（表單）。

ApiPost配置：

根據數據類型選擇 Body 的子選項：

類型	適用場景	對應`Content-Type`
`none`	無請求體（如GET請求）	無
`form-data`	上傳文件或混合表單	`multipart/form-data`
`x-www-form-urlencoded`	普通表單提交（鍵值對）	`application/x-www-form-urlencoded`
`raw`（JSON/XML等）	發送JSON/XML等結構化數據	`application/json`

(5）`binary`（二進制數據）

用途

直接上傳原始二進制文件（如圖片、PDF、音頻等），無需編碼。
適用于需要直接傳輸二進制流的接口（如文件上傳、自定義協議通信）。

使用場景

上傳非文本類文件（如?.jpg,?.pdf,?.zip）。
與后端通信使用自定義二進制協議。

ApiPost配置方法

在?Body?選項卡中選擇?binary。
點擊?"選擇文件"?上傳二進制文件（如?image.png）。
工具會自動設置請求頭：

(6）msgpack（MessagePack格式）

用途

傳輸 MessagePack 格式的數據（一種高效的二進制序列化格式，類似JSON但體積更小）。
適用于高性能場景（如物聯網設備通信、游戲后端）。

特點

比JSON更緊湊，解析速度更快。
支持多種語言（需前后端同時支持MessagePack庫）。

使用場景

需要減少網絡傳輸體積的API。
與嵌入式設備或移動端通信。

特性	`binary`	`msgpack`
數據格式	原始二進制流	結構化二進制序列化數據
典型用途	文件上傳、自定義協議	高效傳輸結構化數據（替代JSON）
Content-Type	`application/octet-stream`	`application/msgpack`
可讀性	不可讀（需解析）	不可讀（但可反序列化為JSON）
體積	取決于文件大小	比JSON小30%~50%