方法引數

下表描述了支援的控制器方法引數。任何引數都不支援 Reactive 型別。

JDK 8 的 `java.util.Optional` 支援作為方法引數，與帶有 `required` 屬性的註解（例如 `@RequestParam`、`@RequestHeader` 等）結合使用時，等同於 `required=false`。

控制器方法引數描述

控制器方法引數	描述
`WebRequest`、`NativeWebRequest`	泛型訪問請求引數以及請求和會話屬性，無需直接使用 Servlet API。
`jakarta.servlet.ServletRequest`、`jakarta.servlet.ServletResponse`	選擇任何特定的請求或響應型別——例如 `ServletRequest`、`HttpServletRequest` 或 Spring 的 `MultipartRequest`、`MultipartHttpServletRequest`。
`jakarta.servlet.http.HttpSession`	強制要求存在一個會話。因此，此類引數永遠不會為 `null`。請注意，會話訪問不是執行緒安全的。如果允許多個請求同時訪問會話，請考慮將 `RequestMappingHandlerAdapter` 例項的 `synchronizeOnSession` 標誌設定為 `true`。
`jakarta.servlet.http.PushBuilder`	用於程式化 HTTP/2 資源推送的 Servlet 4.0 push builder API。請注意，根據 Servlet 規範，如果客戶端不支援該 HTTP/2 功能，注入的 `PushBuilder` 例項可能為 null。
`java.security.Principal`	當前已認證的使用者——如果已知，可能是特定的 `Principal` 實現類。請注意，如果此引數帶有註解以允許自定義解析器在回退到透過 `HttpServletRequest#getUserPrincipal` 進行預設解析之前解析它，則不會立即解析此引數。例如，Spring Security 的 `Authentication` 實現了 `Principal`，並透過 `HttpServletRequest#getUserPrincipal` 以此類形式注入，除非它也用 `@AuthenticationPrincipal` 註解，在這種情況下它會由自定義的 Spring Security 解析器透過 `Authentication#getPrincipal` 進行解析。
`HTTP 方法`	請求的 HTTP 方法。
`java.util.Locale`	當前請求的區域設定，由最具體的 `LocaleResolver`（實際上是已配置的 `LocaleResolver` 或 `LocaleContextResolver`）確定。
`java.util.TimeZone` + `java.time.ZoneId`	與當前請求相關聯的時區，由 `LocaleContextResolver` 確定。
`java.io.InputStream`、`java.io.Reader`	用於訪問 Servlet API 暴露的原始請求體。
`java.io.OutputStream`、`java.io.Writer`	用於訪問 Servlet API 暴露的原始響應體。
`@PathVariable`	用於訪問 URI 模板變數。參見 URI 模式。
`@MatrixVariable`	用於訪問 URI 路徑段中的名稱-值對。參見矩陣變數。
`@RequestParam`	用於訪問 Servlet 請求引數，包括 multipart 檔案。引數值會被轉換為宣告的方法引數型別。參見 `@RequestParam` 以及 Multipart。請注意，對於簡單的引數值，使用 `@RequestParam` 是可選的。參見本表末尾的“任何其他引數”。
`@RequestHeader`	用於訪問請求頭。頭值會被轉換為宣告的方法引數型別。參見 `@RequestHeader`。
`@CookieValue`	用於訪問 cookie。Cookie 值會被轉換為宣告的方法引數型別。參見 `@CookieValue`。
`@RequestBody`	用於訪問 HTTP 請求體。請求體內容會使用 `HttpMessageConverter` 實現轉換為宣告的方法引數型別。參見 `@RequestBody`。
`HttpEntity<B>`	用於訪問請求頭和請求體。請求體會使用 `HttpMessageConverter` 進行轉換。參見 HttpEntity。
`@RequestPart`	用於訪問 `multipart/form-data` 請求中的某個部分，使用 `HttpMessageConverter` 轉換該部分的請求體。參見 Multipart。
`java.util.Map`、`org.springframework.ui.Model`、`org.springframework.ui.ModelMap`	用於訪問在 HTML 控制器中使用並暴露給模板以進行檢視渲染的 Model。
`RedirectAttributes`	指定在重定向時要使用的屬性（即附加到查詢字串）以及要暫時儲存直到重定向後的請求的 flash 屬性。參見重定向屬性和 Flash 屬性。
`@ModelAttribute`	用於訪問模型中已存在的屬性（如果不存在則例項化），並應用資料繫結和校驗。參見 `@ModelAttribute` 以及 Model 和 `DataBinder`。請注意，使用 `@ModelAttribute` 是可選的（例如，用於設定其屬性）。參見本表末尾的“任何其他引數”。
`Errors`、`BindingResult`	用於訪問命令物件（即 `@ModelAttribute` 引數）的校驗和資料繫結錯誤，或 `@RequestBody` 或 `@RequestPart` 引數校驗中的錯誤。您必須在被校驗的方法引數後緊接著宣告一個 `Errors` 或 `BindingResult` 引數。
`SessionStatus` + 類級別 `@SessionAttributes`	用於標記表單處理完成，這會觸發清除透過類級別 `@SessionAttributes` 註解宣告的會話屬性。有關更多詳細資訊，請參見 `@SessionAttributes`。
`UriComponentsBuilder`	用於準備一個相對於當前請求的主機、埠、方案、上下文路徑和 servlet 對映字面部分的 URL。參見 URI 連結。
`@SessionAttribute`	用於訪問任何會話屬性，這與類級別 `@SessionAttributes` 宣告導致儲存在會話中的模型屬性不同。有關更多詳細資訊，請參見 `@SessionAttribute`。
`@RequestAttribute`	用於訪問請求屬性。有關更多詳細資訊，請參見 `@RequestAttribute`。
任何其他引數	如果方法引數與本表中之前的任何值都不匹配且它是簡單型別（由 BeanUtils#isSimpleProperty 確定），則它被解析為 `@RequestParam`。否則，它被解析為 `@ModelAttribute`。

`WebRequest`、`NativeWebRequest`

泛型訪問請求引數以及請求和會話屬性，無需直接使用 Servlet API。

`jakarta.servlet.ServletRequest`、`jakarta.servlet.ServletResponse`

選擇任何特定的請求或響應型別——例如 `ServletRequest`、`HttpServletRequest` 或 Spring 的 `MultipartRequest`、`MultipartHttpServletRequest`。

jakarta.servlet.http.HttpSession

強制要求存在一個會話。因此，此類引數永遠不會為 `null`。請注意，會話訪問不是執行緒安全的。如果允許多個請求同時訪問會話，請考慮將 `RequestMappingHandlerAdapter` 例項的 `synchronizeOnSession` 標誌設定為 `true`。

jakarta.servlet.http.PushBuilder

用於程式化 HTTP/2 資源推送的 Servlet 4.0 push builder API。請注意，根據 Servlet 規範，如果客戶端不支援該 HTTP/2 功能，注入的 `PushBuilder` 例項可能為 null。

java.security.Principal

當前已認證的使用者——如果已知，可能是特定的 `Principal` 實現類。

請注意，如果此引數帶有註解以允許自定義解析器在回退到透過 `HttpServletRequest#getUserPrincipal` 進行預設解析之前解析它，則不會立即解析此引數。例如，Spring Security 的 `Authentication` 實現了 `Principal`，並透過 `HttpServletRequest#getUserPrincipal` 以此類形式注入，除非它也用 `@AuthenticationPrincipal` 註解，在這種情況下它會由自定義的 Spring Security 解析器透過 `Authentication#getPrincipal` 進行解析。

HTTP 方法

請求的 HTTP 方法。

java.util.Locale

當前請求的區域設定，由最具體的 `LocaleResolver`（實際上是已配置的 `LocaleResolver` 或 `LocaleContextResolver`）確定。

java.util.TimeZone + java.time.ZoneId

與當前請求相關聯的時區，由 `LocaleContextResolver` 確定。

java.io.InputStream、java.io.Reader

用於訪問 Servlet API 暴露的原始請求體。

java.io.OutputStream、java.io.Writer

用於訪問 Servlet API 暴露的原始響應體。

@PathVariable

用於訪問 URI 模板變數。參見 URI 模式。

@MatrixVariable

用於訪問 URI 路徑段中的名稱-值對。參見矩陣變數。

@RequestParam

用於訪問 Servlet 請求引數，包括 multipart 檔案。引數值會被轉換為宣告的方法引數型別。參見 @RequestParam 以及 Multipart。

請注意，對於簡單的引數值，使用 `@RequestParam` 是可選的。參見本表末尾的“任何其他引數”。

@RequestHeader

用於訪問請求頭。頭值會被轉換為宣告的方法引數型別。參見 @RequestHeader。

@CookieValue

用於訪問 cookie。Cookie 值會被轉換為宣告的方法引數型別。參見 @CookieValue。

@RequestBody

用於訪問 HTTP 請求體。請求體內容會使用 `HttpMessageConverter` 實現轉換為宣告的方法引數型別。參見 @RequestBody。

HttpEntity<B>

用於訪問請求頭和請求體。請求體會使用 `HttpMessageConverter` 進行轉換。參見 HttpEntity。

@RequestPart

用於訪問 `multipart/form-data` 請求中的某個部分，使用 `HttpMessageConverter` 轉換該部分的請求體。參見 Multipart。

java.util.Map、org.springframework.ui.Model、org.springframework.ui.ModelMap

用於訪問在 HTML 控制器中使用並暴露給模板以進行檢視渲染的 Model。

RedirectAttributes

指定在重定向時要使用的屬性（即附加到查詢字串）以及要暫時儲存直到重定向後的請求的 flash 屬性。參見重定向屬性和 Flash 屬性。

@ModelAttribute

用於訪問模型中已存在的屬性（如果不存在則例項化），並應用資料繫結和校驗。參見 @ModelAttribute 以及 Model 和 DataBinder。

請注意，使用 `@ModelAttribute` 是可選的（例如，用於設定其屬性）。參見本表末尾的“任何其他引數”。

Errors、BindingResult

用於訪問命令物件（即 `@ModelAttribute` 引數）的校驗和資料繫結錯誤，或 `@RequestBody` 或 `@RequestPart` 引數校驗中的錯誤。您必須在被校驗的方法引數後緊接著宣告一個 `Errors` 或 `BindingResult` 引數。

SessionStatus + 類級別 @SessionAttributes

用於標記表單處理完成，這會觸發清除透過類級別 `@SessionAttributes` 註解宣告的會話屬性。有關更多詳細資訊，請參見 @SessionAttributes。

UriComponentsBuilder

用於準備一個相對於當前請求的主機、埠、方案、上下文路徑和 servlet 對映字面部分的 URL。參見 URI 連結。

@SessionAttribute

用於訪問任何會話屬性，這與類級別 `@SessionAttributes` 宣告導致儲存在會話中的模型屬性不同。有關更多詳細資訊，請參見 @SessionAttribute。

@RequestAttribute

用於訪問請求屬性。有關更多詳細資訊，請參見 @RequestAttribute。

任何其他引數

如果方法引數與本表中之前的任何值都不匹配且它是簡單型別（由 BeanUtils#isSimpleProperty 確定），則它被解析為 `@RequestParam`。否則，它被解析為 `@ModelAttribute`。