知識庫 / JSON RSS 訂閱

1. 概述

Postman 是一款流行的 API 平台，它優化了 API 開發生命週期的各個步驟。Postman 可以在不編寫任何代碼的情況下測試自定義 API。此外，我們還可以使用獨立應用程序或瀏覽器擴展。

在本教程中，我們將學習如何在 Postman 中上傳文件和 JSON 數據。

2. 應用設置

讓我們設置一個基本的 Spring Boot 應用，該應用暴露端點以上傳數據。

2.1. 依賴項

首先，我們定義了一個基本的 Spring 應用，其中包含 spring-boot-starter-web 依賴項，在 <em>pom.xml</em> 中：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

現在，我們可以繼續使用一個基本的模型。

2.2. 模型

接下來，我們定義一個簡單的模型類用於 JSON 輸入：

public class JsonRequest {
    int id;
    String name;
}

為了簡明起見，我們刪除了構造函數、獲取器、設置器等類似聲明。

2.3. 端點 (Endpoints)

最後，我們將根據用例設置一個端點，以處理請求為文件：

@PostMapping("/uploadFile")
public ResponseEntity<String> handleFileUpload(@RequestParam("file") MultipartFile file){
    return ResponseEntity.ok().body("file received successfully");
}

在 handleFileUpload() 方法中，我們期望接收一個 MultipartFile 作為輸入，並隨後返回一個 200 狀態消息，其中包含靜態文本。我們保持了簡單性，並未探索保存或處理輸入文件。

在這種情況下，MultipartFile 由 Spring-Web 提供，它代表一個上傳的文件。該文件隨後存儲在內存中或臨時存儲在主存儲器中，並在請求處理完成後進行刷新。

讓我們也創建一個處理 JSON 數據的端點：

@PostMapping("/uploadJson")
public ResponseEntity<String> handleJsonInput(@RequestBody JsonRequest json){
    return ResponseEntity.ok().body(json.getId()+json.getName());
}

在這裏，通過 handleJsonInput(), 我們期望接收一個類型為 JsonRequest 的對象，即我們定義的模型類。因此，該方法返回一個 200 HTTP 狀態碼，並將輸入詳情（id 和 name）包含在響應中。

我們使用了 @RequestBody 註解，它將輸入反序列化為 JsonRequest 對象。 這樣，我們只需關注 JSON 的簡單處理，以驗證輸入。

3. 上傳數據

現在我們已經配置好應用程序，接下來我們將檢查兩種向其提供輸入的方式。

3.1. 將 JSON 上傳到 Postman

JSON 是一種主要的端點文本類型。 按照以下步驟將它傳遞到暴露的端點。

默認方法是 <em >GET</em>。 因此，一旦我們添加了 <em >localhost</em> URL，我們就會選擇 <em >POST</em> 作為方法：

讓我們點擊“Body”選項卡，然後選擇“raw”。 在顯示“Text”的下拉菜單中，我們選擇“JSON”作為輸入：

此時，我們粘貼輸入 JSON，然後點擊“Send”：

正如預期的那樣，我們收到了響應中的 <em >200</em> 狀態碼，如快照底部所示。 此外，輸入中的 <em >id</em> 和 <em >name</em> 在響應體中返回，這確認 JSON 已在端點上正確處理。

3.2. 將文件上傳到 Postman

讓我們以文檔文件為例進行演示，因為我們沒有對端點可以消耗的文件類型進行任何限制。

現在，我們添加 localhost URL 並選擇 POST 作為方法，因為默認方法是 GET。

接下來，我們點擊 Body 選項卡，然後選擇 form-data。在鍵值對的第一行，我們點擊右側角上的下拉菜單，用於鍵字段，並選擇 File 作為輸入：

在這裏，我們在鍵列中添加文本 File，這對應於端點的 @RequestParam，並在值列中瀏覽到所需路徑。

最後，我們點擊 Send：

當我們點擊 Send 時，我們得到一個 200 HTTP 狀態碼，以及端點定義中靜態文本，這表明文件已成功交付到端點，並且沒有發生任何錯誤或異常。

4. 通過同一請求發送多部分數據和 JSON

讓我們看看如何使用 Postman 在同一請求中發送多部分數據和 JSON。

首先，我們配置 Postman 請求並設置要發送的 JSON 數據，在預請求腳本中：

接下來，我們轉到請求編輯器中的 Body 選項卡，並選擇 form-data 作為主體類型。然後，讓我們添加用於嵌套 JSON 對象和多部分文件的字段：

我們設置了兩行：

• 對於嵌套 JSON，我們從預請求腳本中早期的 jsonData 變量中獲取其值，內容類型為 application/json。
• 對於文件字段，我們點擊 Choose Files 按鈕，打開文件對話框，選擇要上傳的所需文件。選擇文件後，Postman 將其包含在 multipart/form-data 請求中。

最後，讓我們創建一個適當的控制器來處理 multipart/form-data 請求並相應地處理文件和嵌套 JSON 對象：

@PostMapping("/uploadJsonAndMultipartData")
public ResponseEntity<String> handleJsonAndMultipartInput(@RequestPart("data") JsonRequest json, @RequestPart("file") MultipartFile file) {
    return ResponseEntity.ok()
      .body(json.getId() + json.getName());
}

在此端中，handleJsonAndMultipartInput() 方法接受嵌套的 JSON 對象作為 JsonRequest 對象，通過 @RequestPart(“data”)，而文件則作為 MultipartFile 對象，通過 @RequestPart(“file”)。

5. 當所需請求部分 file 未存在時

在 Spring Boot 中，當服務器期望接收名為 file 的多部分請求部分時，如果傳入的請求中未包含該部分，將會發生異常。這種情況通常發生在 Postman 中請求配置不正確或參數名稱不匹配。

為了解決這個問題，我們應該確保 Postman 中請求體類型設置為 form-data，而不是 raw 或 x-www-form-urlencoded。 form-data 表中的鍵名必須與控制器中定義的名稱完全匹配。

5.1. 上傳文件

如果僅上傳文件，則端點應採用以下格式：

@PostMapping(value = "/uploadSingleFile", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> handleSingleFileUpload(@RequestParam("file") MultipartFile file) {
    return ResponseEntity.ok("file received successfully");
}

在這種情況下，我們發送一個名為 form-data 的單個字段，並在 Postman 中將其標記為類型 File，並選擇所需的文件：

發送後，控制器會正確接收到該數據。

5.2. 上傳 JSON 數據和文件

然而，當我們需要在同一請求中上傳 JSON 數據和文件時，我們使用 <em @RequestPart</em> 註解，而不是 <em @RequestBody</em>。 這是因為 <em @RequestBody</em> 期望整個請求體為 JSON，而 <em multipart/form-data</em> 請求包含多個不同部分。

讓我們看一個正確的示例：

@PostMapping(value = "/uploadJsonAndMultipartInput", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
public ResponseEntity<String> handleUploadJsonAndMultipartInput(
  @RequestPart("data") JsonRequest json,
  @RequestPart("file") MultipartFile file) {
    return ResponseEntity.ok(json.getId() + json.getName());
}

同樣，在 Postman 中，我們應該為請求體選擇 form-data 格式。第一個鍵，名為 data，應包含 JSON 對象作為純文本：

{"id": 1, "name": "Alice"}

然後，我們懸停在鍵字段上，選擇 Text，並將 Content-Type 設置為 application/json。 這些步驟確保多部分數據正確結構化，並防止異常發生。

第二個鍵應命名為 file，並設置為類型 File。 接下來，我們使用文件選擇器選擇所需文件。 兩個字段都添加完畢後，點擊 Send。 此時，端點正確地反序列化了請求的兩個部分。

6. 結論

在本文中，我們構建了一個簡單的 Spring Boot 應用程序，並探討了三種通過 Postman 將數據提供給端點的方法。