方法参数

下表描述了支持的控制器方法参数。任何参数都不支持 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`。