方法引數

下表描述了支援的控制器方法引數。任何引數皆不支援反應式類型。

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

控制器方法引數描述

控制器方法引數	描述
`WebRequest`、`NativeWebRequest`	通用存取請求參數以及請求和 Session 屬性，無需直接使用 Servlet API。
`jakarta.servlet.ServletRequest`、`jakarta.servlet.ServletResponse`	選擇任何特定的請求或回應類型，例如 `ServletRequest`、`HttpServletRequest` 或 Spring 的 `MultipartRequest`、`MultipartHttpServletRequest`。
`jakarta.servlet.http.HttpSession`	強制 Session 的存在。因此，此類引數永遠不會是 `null`。請注意，Session 存取不是執行緒安全的。如果允許多個請求同時存取 Session，請考慮將 `RequestMappingHandlerAdapter` 實例的 `synchronizeOnSession` 旗標設定為 `true`。
`jakarta.servlet.http.PushBuilder`	Servlet 4.0 推送建構器 API，用於程式化 HTTP/2 資源推送。請注意，根據 Servlet 規範，如果客户端不支援該 HTTP/2 功能，則注入的 `PushBuilder` 實例可能為 null。
`java.security.Principal`	目前已驗證的使用者 — 如果已知，則可能是特定的 `Principal` 實作類別。請注意，如果此引數被註解，則不會急切地解析它，以便允許自訂解析器在透過 `HttpServletRequest#getUserPrincipal` 回退到預設解析之前解析它。例如，Spring Security `Authentication` 實作 `Principal`，並且將透過 `HttpServletRequest#getUserPrincipal` 注入為此，除非它也使用 `@AuthenticationPrincipal` 進行註解，在這種情況下，它將由自訂 Spring Security 解析器透過 `Authentication#getPrincipal` 解析。
`HttpMethod`	請求的 HTTP 方法。
`java.util.Locale`	目前的請求 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` 請求中的 part，並使用 `HttpMessageConverter` 轉換 part 的本文。請參閱 Multipart。
`java.util.Map`、`org.springframework.ui.Model`、`org.springframework.ui.ModelMap`	用於存取 HTML 控制器中使用的模型，並作為檢視呈現的一部分公開給範本。
`RedirectAttributes`	指定在重新導向時使用的屬性（即，附加到查詢字串）和 flash 屬性，這些屬性將暫時儲存，直到重新導向後的請求。請參閱重新導向屬性和 Flash 屬性。
`@ModelAttribute`	用於存取模型中現有的屬性（如果不存在則實例化），並套用資料繫結和驗證。請參閱 `@ModelAttribute` 以及 Model 和 `DataBinder`。請注意，`@ModelAttribute` 的使用是選用的（例如，設定其屬性）。請參閱本表末尾的「任何其他引數」。
`Errors`、`BindingResult`	用於存取命令物件（即 `@ModelAttribute` 引數）的驗證和資料繫結錯誤，或 `@RequestBody` 或 `@RequestPart` 引數驗證的錯誤。您必須在已驗證的方法引數之後立即宣告 `Errors` 或 `BindingResult` 引數。
`SessionStatus` + 類別層級 `@SessionAttributes`	用於標記表單處理完成，這會觸發透過類別層級 `@SessionAttributes` 註解宣告的 Session 屬性的清理。有關更多詳細資訊，請參閱 `@SessionAttributes`。
`UriComponentsBuilder`	用於準備相對於目前請求的主機、埠、Scheme、Context 路徑和 Servlet 對應的文字部分的 URL。請參閱 URI 連結。
`@SessionAttribute`	用於存取任何 Session 屬性，與由於類別層級 `@SessionAttributes` 宣告而儲存在 Session 中的模型屬性相反。有關更多詳細資訊，請參閱 `@SessionAttribute`。
`@RequestAttribute`	用於存取請求屬性。有關更多詳細資訊，請參閱 `@RequestAttribute`。
任何其他引數	如果方法引數與本表中較早的值都不符，並且它是簡單類型（由 BeanUtils#isSimpleProperty 確定），則會將其解析為 `@RequestParam`。否則，會將其解析為 `@ModelAttribute`。

WebRequest、NativeWebRequest

通用存取請求參數以及請求和 Session 屬性，無需直接使用 Servlet API。

jakarta.servlet.ServletRequest、jakarta.servlet.ServletResponse

選擇任何特定的請求或回應類型，例如 ServletRequest、HttpServletRequest 或 Spring 的 MultipartRequest、MultipartHttpServletRequest。

jakarta.servlet.http.HttpSession

強制 Session 的存在。因此，此類引數永遠不會是 null。請注意，Session 存取不是執行緒安全的。如果允許多個請求同時存取 Session，請考慮將 RequestMappingHandlerAdapter 實例的 synchronizeOnSession 旗標設定為 true。

jakarta.servlet.http.PushBuilder

Servlet 4.0 推送建構器 API，用於程式化 HTTP/2 資源推送。請注意，根據 Servlet 規範，如果客户端不支援該 HTTP/2 功能，則注入的 PushBuilder 實例可能為 null。

java.security.Principal

目前已驗證的使用者 — 如果已知，則可能是特定的 Principal 實作類別。

請注意，如果此引數被註解，則不會急切地解析它，以便允許自訂解析器在透過 HttpServletRequest#getUserPrincipal 回退到預設解析之前解析它。例如，Spring Security Authentication 實作 Principal，並且將透過 HttpServletRequest#getUserPrincipal 注入為此，除非它也使用 @AuthenticationPrincipal 進行註解，在這種情況下，它將由自訂 Spring Security 解析器透過 Authentication#getPrincipal 解析。

HttpMethod

請求的 HTTP 方法。

java.util.Locale

目前的請求 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 請求中的 part，並使用 HttpMessageConverter 轉換 part 的本文。請參閱 Multipart。

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

用於存取 HTML 控制器中使用的模型，並作為檢視呈現的一部分公開給範本。

RedirectAttributes

指定在重新導向時使用的屬性（即，附加到查詢字串）和 flash 屬性，這些屬性將暫時儲存，直到重新導向後的請求。請參閱重新導向屬性和 Flash 屬性。

@ModelAttribute

用於存取模型中現有的屬性（如果不存在則實例化），並套用資料繫結和驗證。請參閱 @ModelAttribute 以及 Model 和 DataBinder。

請注意，@ModelAttribute 的使用是選用的（例如，設定其屬性）。請參閱本表末尾的「任何其他引數」。

Errors、BindingResult

用於存取命令物件（即 @ModelAttribute 引數）的驗證和資料繫結錯誤，或 @RequestBody 或 @RequestPart 引數驗證的錯誤。您必須在已驗證的方法引數之後立即宣告 Errors 或 BindingResult 引數。

SessionStatus + 類別層級 @SessionAttributes

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

UriComponentsBuilder

用於準備相對於目前請求的主機、埠、Scheme、Context 路徑和 Servlet 對應的文字部分的 URL。請參閱 URI 連結。

@SessionAttribute

用於存取任何 Session 屬性，與由於類別層級 @SessionAttributes 宣告而儲存在 Session 中的模型屬性相反。有關更多詳細資訊，請參閱 @SessionAttribute。

@RequestAttribute

用於存取請求屬性。有關更多詳細資訊，請參閱 @RequestAttribute。

任何其他引數

如果方法引數與本表中較早的值都不符，並且它是簡單類型（由 BeanUtils#isSimpleProperty 確定），則會將其解析為 @RequestParam。否則，會將其解析為 @ModelAttribute。