方法引數

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

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 推送構建器 API。請注意，此 API 已在 Servlet 6.1 中棄用。
`java.security.Principal`	當前已認證的使用者——如果已知，可能是特定的 `Principal` 實現類。請注意，如果此引數被註解以允許自定義解析器在回退到透過 `HttpServletRequest#getUserPrincipal` 進行預設解析之前解析它，則不會急切解析此引數。例如，Spring Security 的 `Authentication` 實現了 `Principal`，並會透過 `HttpServletRequest#getUserPrincipal` 注入，除非它也使用 `@AuthenticationPrincipal` 進行註解，在這種情況下，它會透過 `Authentication#getPrincipal` 由自定義 Spring Security 解析器解析。
`HttpMethod`	請求的 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 請求引數，包括多部分檔案。引數值被轉換為宣告的方法引數型別。請參閱 `@RequestParam` 以及多部分。請注意，對於簡單的引數值，`@RequestParam` 的使用是可選的。請參閱本表末尾的“任何其他引數”。
`@RequestHeader`	用於訪問請求頭。頭值被轉換為宣告的方法引數型別。請參閱 `@RequestHeader`。
`@CookieValue`	用於訪問 cookie。Cookie 值被轉換為宣告的方法引數型別。請參閱 `@CookieValue`。
`@RequestBody`	用於訪問 HTTP 請求體。請求體內容透過使用 `HttpMessageConverter` 實現轉換為宣告的方法引數型別。請參閱 `@RequestBody`。
`HttpEntity<B>`	用於訪問請求頭和請求體。請求體透過 `HttpMessageConverter` 進行轉換。請參閱 HttpEntity。
`@RequestPart`	用於訪問 `multipart/form-data` 請求中的某個部分，並透過 `HttpMessageConverter` 轉換該部分的請求體。請參閱多部分。
`java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap`	用於訪問在 HTML 控制器中使用的模型，並作為檢視渲染的一部分暴露給模板。
`RedirectAttributes`	指定在重定向情況下使用的屬性（即，附加到查詢字串）和臨時儲存的快閃記憶體屬性，直到重定向後的請求。請參閱重定向屬性和快閃記憶體屬性。
`@ModelAttribute`	用於訪問模型中現有屬性（如果不存在則例項化），並應用資料繫結和驗證。請參閱 `@ModelAttribute` 以及模型和 `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 推送構建器 API。請注意，此 API 已在 Servlet 6.1 中棄用。

java.security.Principal

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

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

HttpMethod

請求的 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 請求引數，包括多部分檔案。引數值被轉換為宣告的方法引數型別。請參閱 @RequestParam 以及多部分。

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

@RequestHeader

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

@CookieValue

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

@RequestBody

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

HttpEntity<B>

用於訪問請求頭和請求體。請求體透過 HttpMessageConverter 進行轉換。請參閱 HttpEntity。

@RequestPart

用於訪問 multipart/form-data 請求中的某個部分，並透過 HttpMessageConverter 轉換該部分的請求體。請參閱多部分。

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

用於訪問在 HTML 控制器中使用的模型，並作為檢視渲染的一部分暴露給模板。

RedirectAttributes

指定在重定向情況下使用的屬性（即，附加到查詢字串）和臨時儲存的快閃記憶體屬性，直到重定向後的請求。請參閱重定向屬性和快閃記憶體屬性。

@ModelAttribute

用於訪問模型中現有屬性（如果不存在則例項化），並應用資料繫結和驗證。請參閱 @ModelAttribute 以及模型和 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。