跳到主要内容

方法参数

ChatGPT-4o-mini 中英对照 Method Arguments

下表描述了支持的控制器方法参数。对于任何参数，不支持反应式类型。

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.PushBuilderServlet 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 patterns。
@MatrixVariable用于访问 URI 路径段中的名称-值对。请参见 Matrix Variables。
@RequestParam要访问 Servlet 请求参数，包括 multipart 文件。参数值会被转换为声明的方法参数类型。请参见 @RequestParam 以及 Multipart。

请注意，对于简单参数值，使用 @RequestParam 是可选的。请参见本表末尾的“任何其他参数”。
@RequestHeader用于访问请求头。头部值会被转换为声明的方法参数类型。请参见 @RequestHeader。
@CookieValue对于访问 cookies。Cookies 的值会被转换为声明的方法参数类型。请参见 @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指定在重定向情况下使用的属性（即，附加到查询字符串中）和闪存属性，这些属性将在重定向后的请求中暂时存储。请参见 Redirect Attributes 和 Flash Attributes。
@ModelAttribute对于访问模型中现有的属性（如果不存在则实例化）并应用数据绑定和验证。请参见 @ModelAttribute 以及 Model 和 DataBinder。

请注意，使用 @ModelAttribute 是可选的（例如，用于设置其属性）。请参见此表末尾的“任何其他参数”。
Errors, BindingResult对于来自命令对象（即 @ModelAttribute 参数）的验证和数据绑定错误，或者来自 @RequestBody 或 @RequestPart 参数的验证错误。您必须在经过验证的方法参数后立即声明一个 Errors 或 BindingResult 参数。
SessionStatus + class-level @SessionAttributes用于标记表单处理完成，这会触发通过类级别的 @SessionAttributes 注解声明的会话属性的清理。有关更多详细信息，请参见 @SessionAttributes。
UriComponentsBuilder为了准备一个相对于当前请求的主机、端口、协议、上下文路径和 servlet 映射的字面部分的 URL。请参见 URI Links。
@SessionAttribute对于访问任何会话属性，与作为类级别 @SessionAttributes 声明结果存储在会话中的模型属性相对。有关更多详细信息，请参见 @SessionAttribute。
@RequestAttribute用于访问请求属性。有关更多详细信息，请参见 @RequestAttribute。
任何其他论点如果方法参数没有与此表中的任何早期值匹配，并且它是一个简单类型（由 BeanUtils#isSimpleProperty 确定），则它被解析为 @RequestParam。否则，它被解析为 @ModelAttribute。