方法参数

下表描述了支持的控制器方法参数。任何参数都不支持 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`	Servlet 4.0 推送构建器 API，用于以编程方式进行 HTTP/2 资源推送。请注意，根据 Servlet 规范，如果客户端不支持该 HTTP/2 功能，则注入的`PushBuilder`实例可能为 null。
`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` 转换该部分的请求体。参见 Multipart。
`java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap`	用于访问 HTML 控制器中使用的模型，并在视图渲染过程中作为视图的一部分暴露给模板。
`RedirectAttributes`	指定在重定向时使用的属性（即，附加到查询字符串）和闪存属性，这些属性将临时存储，直到重定向后的请求。参见重定向属性和闪存属性。
`@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

Servlet 4.0 推送构建器 API，用于以编程方式进行 HTTP/2 资源推送。请注意，根据 Servlet 规范，如果客户端不支持该 HTTP/2 功能，则注入的PushBuilder实例可能为 null。

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 转换该部分的请求体。参见 Multipart。

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

用于访问 HTML 控制器中使用的模型，并在视图渲染过程中作为视图的一部分暴露给模板。

RedirectAttributes

指定在重定向时使用的属性（即，附加到查询字符串）和闪存属性，这些属性将临时存储，直到重定向后的请求。参见重定向属性和闪存属性。

@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。