📌 Spring RestTemplate vs OkHttp：多值參數處理

一、MultiValueMap 與 FormBody 的差異

特性	RestTemplate + MultiValueMap	OkHttp + FormBody
多值參數支持	? 原生支持（add("key", "value") 自動追加）	? 需顯式多次調用 add("key", "value")
參數位置控制	Body 或 URL（開發者需主動區分）	Body 參數強制在請求體，URL 保持干凈
編碼機制	自動 URL 編碼（空格→%20）	自動編碼非 ASCII 字符（中文→%E4%B8%AD）
適用場景	Spring 生態項目，需簡化多值處理	非 Spring 項目、Android 或高性能場景
性能擴展	依賴底層實現（默認 JDK，可切換 OkHttp）	原生支持連接池復用、HTTP/2、異步請求

關鍵誤區澄清
使用 OkHttp 的 FormBody 時，所有參數僅存在于 HTTP 請求體中，不會附加到 URL 末尾。例如：

FormBody formBody = new FormBody.Builder().add("role", "admin").build();  

實際請求結構：

POST /submit HTTP/1.1  
Content-Type: application/x-www-form-urlencoded  role=admin&role=editor  // ? 參數在 Body，URL 仍是 `https://api.example.com/submit`  

---

二、代碼示例：表單提交實戰對比

1. RestTemplate + MultiValueMap（支持多值參數）

MultiValueMap<String, String> params = new LinkedMultiValueMap<>();
params.add("user", "Alice");
params.add("role", "admin"); 
params.add("role", "editor"); // ? 同名參數多值HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED); // 必須設置HttpEntity<MultiValueMap<String, String>> entity = new HttpEntity<>(params, headers);
RestTemplate restTemplate = new RestTemplate();
ResponseEntity<String> response = restTemplate.postForEntity(url, entity, String.class);

2. OkHttp FormBody（需顯式添加多值）

FormBody formBody = new FormBody.Builder().add("user", "Alice").add("role", "admin")  // 同名參數需重復調用.add("role", "editor") .build();Request request = new Request.Builder().url(url) // ? URL 無參數.post(formBody).build();OkHttpClient client = new OkHttpClient();
client.newCall(request).execute();

---

三、轉換方法：MultiValueMap ? FormBody

1. Spring → OkHttp（MultiValueMap → FormBody）

MultiValueMap<String, String> springParams = ...; // Spring 參數
FormBody.Builder okHttpBuilder = new FormBody.Builder();springParams.forEach((key, values) -> values.forEach(value -> okHttpBuilder.add(key, value) // 遍歷追加多值)
);
FormBody okHttpBody = okHttpBuilder.build();

2. OkHttp → Spring（FormBody → MultiValueMap）

FormBody okHttpBody = ...; // OkHttp 請求體
MultiValueMap<String, String> springParams = new LinkedMultiValueMap<>();for (int i = 0; i < okHttpBody.size(); i++) {springParams.add(okHttpBody.name(i), okHttpBody.value(i)); // 按索引解析
}

---

四、Spring Boot 接收 FormBody 請求（x-www-form-urlencoded）

1. 多值參數綁定方案

@PostMapping("/submit")
public String handleForm(@RequestParam("user") String user,          // 單值參數@RequestParam("role") List<String> roles     // 多值參數 → 自動綁定 List
) {return "User: " + user + ", Roles: " + roles; // 輸出：User: Alice, Roles: [admin, editor]
}

2. 通過 POJO 對象接收（需匹配字段名）

public class FormData {private String user;private List<String> role; // 字段名必須與參數名一致// 必需 Setterpublic void setRole(List<String> role) { this.role = role; }
}@PostMapping("/submit")
public String handleForm(FormData formData) {return formData.getRole().toString(); // 輸出 [admin, editor]
}

?? 關鍵注意事項

1. Content-Type 必須為 application/x-www-form-urlencoded
   • 誤用 @RequestBody 會觸發 415 Unsupported MediaType（應用 JSON 處理器）。
2. 多值參數綁定規則
   • 前端需傳遞同名參數（如 role=admin&role=editor），否則 Spring 無法識別多值。
3. 中文亂碼解決方案

   @Bean
   public FilterRegistrationBean<CharacterEncodingFilter> encodingFilter() {CharacterEncodingFilter filter = new CharacterEncodingFilter();filter.setEncoding("UTF-8");filter.setForceEncoding(true); // 強制覆蓋請求/響應編碼return new FilterRegistrationBean<>(filter);
   }
   

---

五、總結：選型建議

場景	推薦方案	原因
高并發/低延遲需求	OkHttp	原生異步、連接池、HTTP/2 支持
非 Spring 項目	OkHttp	無依賴，輕量易集成
簡單表單提交（Spring 內部）	RestTemplate + MultiValueMap	快速實現，避免額外代碼

決策建議：

• 優先 OkHttp：新項目、高性能需求、跨平臺（如 Android）或非 Spring 環境。
• 謹慎保留 MultiValueMap：僅限 Spring 項目且需頻繁處理多值表單的場景，但底層應切換為 OkHttp 引擎。
• 徹底棄用場景：RestTemplate 的阻塞模型無法滿足性能要求，或參數混淆風險過高時。