跳到主要内容

方法参数

DeepSeek V3 中英对照 Method Arguments

下表展示了支持的控制器方法参数。

在需要阻塞 I/O（例如读取请求体）的参数上，支持响应式类型（如 Reactor、RxJava 或其他）。这在“描述”列中进行了标注。对于不需要阻塞的参数，不期望使用响应式类型。

JDK 1.8 的 java.util.Optional 支持作为方法参数与具有 required 属性的注解（例如 @RequestParam、@RequestHeader 等）结合使用，并且等同于 required=false。

控制器方法参数描述
ServerWebExchange访问完整的 ServerWebExchange — HTTP 请求和响应的容器，包含请求和会话属性、checkNotModified 方法等。
ServerHttpRequest, ServerHttpResponse访问 HTTP 请求或响应。
WebSession访问会话。除非添加了属性，否则不会强制启动新会话。支持响应式类型。
java.security.Principal当前经过身份验证的用户 —— 如果已知，可能是一个特定的 Principal 实现类。支持响应式类型。
org.springframework.http.HttpMethod请求的 HTTP 方法。
java.util.Locale当前请求的区域设置，由最具体的 LocaleResolver 确定 —— 实际上是配置的 LocaleResolver/LocaleContextResolver。
java.util.TimeZone + java.time.ZoneId与当前请求关联的时区，由 LocaleContextResolver 确定。
@PathVariable用于访问 URI 模板变量。请参阅 URI 模式。
@MatrixVariable用于访问 URI 路径段中的键值对。请参阅矩阵变量。
@RequestParam用于访问查询参数。参数值会被转换为声明的方法参数类型。请参阅 @RequestParam。

需要注意的是，使用 @RequestParam 是可选的——例如，用于设置其属性。请参阅本表后面的“其他任何参数”部分。
@RequestHeader用于访问请求头信息。请求头的值会被转换为声明的方法参数类型。详情请参阅 @RequestHeader。
@CookieValue用于访问 Cookie。Cookie 值会被转换为声明的方法参数类型。参见 @CookieValue。
@RequestBody用于访问 HTTP 请求体。通过使用 HttpMessageReader 实例将请求体内容转换为声明的方法参数类型。支持响应式类型。请参阅 @RequestBody。
HttpEntity<B>用于访问请求头和请求体。请求体通过 HttpMessageReader 实例进行转换。支持响应式类型。详情请参阅 HttpEntity。
@RequestPart用于访问 multipart/form-data 请求中的某一部分。支持响应式类型。详见 Multipart 内容 和 Multipart 数据。
java.util.Map or org.springframework.ui.Model用于访问在 HTML 控制器中使用的模型，该模型作为视图渲染的一部分暴露给模板。
@ModelAttribute用于访问模型中的现有属性（如果不存在则实例化），并应用数据绑定和验证。请参阅 @ModelAttribute 以及 Model 和 DataBinder。

请注意，@ModelAttribute 的使用是可选的——例如，用于设置其属性。请参阅本表后面的“其他任意参数”部分。
Errors or BindingResult用于访问命令对象（即 @ModelAttribute 参数）的验证和数据绑定错误。Errors 或 BindingResult 参数必须在验证方法参数之后立即声明。
SessionStatus + class-level @SessionAttributes用于标记表单处理完成，这将触发通过类级别 @SessionAttributes 注解声明的会话属性的清理。有关更多详细信息，请参阅 @SessionAttributes。
UriComponentsBuilder用于准备相对于当前请求的主机、端口、方案和上下文路径的 URL。请参阅 URI 链接。
@SessionAttribute访问任何会话属性——与作为类级别 @SessionAttributes 声明的结果存储在会话中的模型属性不同。有关更多详细信息，请参阅 @SessionAttribute。
@RequestAttribute用于访问请求属性。有关详细信息，请参阅 @RequestAttribute。
其他任何参数如果方法参数未匹配到上述任何一种情况，默认情况下，如果它是一个简单类型（由 BeanUtils#isSimpleProperty 确定），则将其解析为 @RequestParam，否则将其解析为 @ModelAttribute。