@Controller 参数绑定源码分析

1. 概述

Spring MVC 中，@Controller 处理器方法的参数绑定是框架最核心的能力之一。当 HTTP 请求到达 DispatcherServlet 后，经过拦截器和处理器映射，最终由 RequestMappingHandlerAdapter 调用具体的 @RequestMapping 方法。在此过程中，方法参数的解析完全交由 HandlerMethodArgumentResolver 体系完成。

本文从 RequestMappingHandlerAdapter.invokeHandlerMethod() 入手，逐层深入参数解析的完整链路，涵盖 @PathVariable、@RequestParam、@RequestBody、@ModelAttribute 等常用注解的解析器实现，以及 RequestResponseBodyMethodProcessor 的消息转换器机制和自定义参数解析器实战。

2. RequestMappingHandlerAdapter.invokeHandlerMethod()

RequestMappingHandlerAdapter 实现了 HandlerAdapter 接口，其 handle() 委托给 invokeHandlerMethod() 完成实际的方法调用。

2.1 调用入口

java

// DispatcherServlet.doDispatch()
HandlerAdapter ha = getHandlerAdapter(mappedHandler.getHandler());
ModelAndView mv = ha.handle(request, response, mappedHandler.getHandler());

handle() 内部：

java

@Override
@Nullable
public ModelAndView handle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
    return invokeHandlerMethod(request, response, (HandlerMethod) handler);
}

2.2 invokeHandlerMethod 源码解析

invokeHandlerMethod() 是整个参数绑定流程的起点，负责构建 ServletInvocableHandlerMethod，组装解析器和返回值处理器，最终通过 invokeAndHandle() 执行目标方法：

java

@Nullable
protected ModelAndView invokeHandlerMethod(HttpServletRequest request,
        HttpServletResponse response, HandlerMethod handlerMethod) throws Exception {

    ServletInvocableHandlerMethod invocableMethod =
            createInvocableHandlerMethod(handlerMethod);
    WebDataBinderFactory binderFactory = getDataBinderFactory(handlerMethod);
    invocableMethod.setDataBinderFactory(binderFactory);
    invocableMethod.setHandlerMethodArgumentResolvers(this.argumentResolvers);
    invocableMethod.setHandlerMethodReturnValueHandlers(this.returnValueHandlers);

    ModelAndViewContainer mavContainer = new ModelAndViewContainer();
    ModelFactory modelFactory = getModelFactory(handlerMethod, binderFactory);
    modelFactory.initModel(servletRequest, servletResponse, mavContainer);

    invocableMethod.invokeAndHandle(webRequest, mavContainer, new Object[0]);
    return getModelAndView(mavContainer, modelFactory, webRequest);
}

各步骤职责：

步骤	方法	职责
1	`createInvocableHandlerMethod()`	包装为支持异步和参数注入的 `ServletInvocableHandlerMethod`
2	`getDataBinderFactory()`	构建 `WebDataBinderFactory`，用于参数校验和数据绑定
3	设置 `argumentResolvers`	注入所有已注册的 `HandlerMethodArgumentResolver`
4	设置 `returnValueHandlers`	注入所有已注册的返回值处理器
5	`initModel()`	调用 `@ModelAttribute` 方法，将返回值放入 Model
6	`invokeAndHandle()`	解析方法参数并执行目标方法，处理返回值

2.3 invokeForRequest 与参数解析入口

invokeAndHandle() 内部委托给 invokeForRequest()：

java

// ServletInvocableHandlerMethod
public void invokeAndHandle(ServletWebRequest webRequest,
        ModelAndViewContainer mavContainer, Object... providedArgs) throws Exception {

    Object returnValue = invokeForRequest(webRequest, mavContainer, providedArgs);
    setResponseStatus(webRequest);

    if (returnValue == null && (isRequestNotModified(webRequest) || getResponseStatus() != null
            || mavContainer.isRequestHandled())) {
        mavContainer.setRequestHandled(true);
        return;
    }

    this.returnValueHandlers.handleReturnValue(
            returnValue, getReturnValueType(returnValue), mavContainer, webRequest);
}

java

// InvocableHandlerMethod
@Nullable
public Object invokeForRequest(NativeWebRequest request,
        @Nullable ModelAndViewContainer mavContainer, Object... providedArgs) throws Exception {

    Object[] args = getMethodArgumentValues(request, mavContainer, providedArgs);
    return doInvoke(args);
}

getMethodArgumentValues() 是参数绑定的真正战场。

3. getMethodArgumentValues 与参数解析循环

该方法遍历目标方法的所有参数，为每个参数寻找合适的 HandlerMethodArgumentResolver：

java

protected Object[] getMethodArgumentValues(NativeWebRequest request,
        @Nullable ModelAndViewContainer mavContainer, Object... providedArgs) throws Exception {

    MethodParameter[] parameters = getMethodParameters();
    if (ObjectUtils.isEmpty(parameters)) {
        return EMPTY_ARGS;
    }

    Object[] args = new Object[parameters.length];
    for (int i = 0; i < parameters.length; i++) {
        MethodParameter parameter = parameters[i];
        parameter.initParameterNameDiscovery(this.parameterNameDiscoverer);

        args[i] = findProvidedArgument(parameter, providedArgs);
        if (args[i] != null) continue;

        if (!this.resolvers.supportsParameter(parameter)) {
            throw new IllegalStateException("No suitable resolver for parameter " + parameter.getParameterName());
        }
        try {
            args[i] = this.resolvers.resolveArgument(parameter, mavContainer,
                    request, this.dataBinderFactory);
        } catch (Exception ex) {
            // 异常处理
        }
    }
    return args;
}

整个流程是典型的 "遍历-匹配-解析" 循环。this.resolvers 的类型是 HandlerMethodArgumentResolverComposite，它持有一个 List<HandlerMethodArgumentResolver>，对每个参数依次调用 supportsParameter()，找到第一个返回 true 的解析器后调用其 resolveArgument()。

4. HandlerMethodArgumentResolver 接口体系

HandlerMethodArgumentResolver 是参数绑定体系的灵魂接口：

java

public interface HandlerMethodArgumentResolver {
    boolean supportsParameter(MethodParameter parameter);

    @Nullable
    Object resolveArgument(MethodParameter parameter,
            @Nullable ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            @Nullable WebDataBinderFactory binderFactory) throws Exception;
}

4.1 参数解析器体系结构图

org.springframework.web.method.annotation
├── AbstractNamedValueMethodArgumentResolver        ← 抽象基类
│   ├── PathVariableMethodArgumentResolver           ← @PathVariable
│   ├── RequestParamMethodArgumentResolver           ← @RequestParam
│   ├── RequestHeaderMethodArgumentResolver          ← @RequestHeader
│   ├── CookieValueMethodArgumentResolver            ← @CookieValue
│   ├── RequestAttributeMethodArgumentResolver        ← @RequestAttribute
│   └── SessionAttributeMethodArgumentResolver        ← @SessionAttribute
│
├── RequestParamMapMethodArgumentResolver             ← Map<@RequestParam>
├── PathVariableMapMethodArgumentResolver             ← Map<@PathVariable>
├── RequestHeaderMapMethodArgumentResolver            ← Map<@RequestHeader>
├── MatrixVariableMethodArgumentResolver              ← @MatrixVariable
├── MatrixVariableMapMethodArgumentResolver           ← Map<@MatrixVariable>
├── ExpressionValueMethodArgumentResolver             ← @Value
├── SessionStatusMethodArgumentResolver               ← SessionStatus
├── ModelMethodProcessor                              ← Model
├── ErrorsMethodArgumentResolver                      ← Errors/BindingResult
├── MapMethodProcessor                                ← Map (output)
│
org.springframework.web.servlet.mvc.method.annotation
├── RequestResponseBodyMethodProcessor               ← @RequestBody / @ResponseBody
├── ModelAttributeMethodProcessor                    ← @ModelAttribute
├── ServletModelAttributeMethodProcessor             ← extends 上者
├── ServletRequestMethodArgumentAdapter              ← HttpServletRequest
├── ServletResponseMethodArgumentAdapter             ← HttpServletResponse
└── HttpEntityMethodProcessor                        ← HttpEntity/RequestEntity

解析器遵循优先级顺序：注解明确的解析器优先，兜底类型置后。如 RequestParamMethodArgumentResolver 分两阶段注册——第一阶段仅处理有 @RequestParam 注解的参数，第二阶段作为兜底处理简单类型的非注解参数。

4.2 AbstractNamedValueMethodArgumentResolver

对于从请求中提取命名值的参数，Spring MVC 提供了 AbstractNamedValueMethodArgumentResolver 作为统一抽象基类，采用模板方法模式：

java

public abstract class AbstractNamedValueMethodArgumentResolver
        implements HandlerMethodArgumentResolver {

    @Override
    @Nullable
    public final Object resolveArgument(MethodParameter parameter,
            @Nullable ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            @Nullable WebDataBinderFactory binderFactory) throws Exception {

        NamedValueInfo namedValueInfo = getNamedValueInfo(parameter);
        Object resolvedName = handleResolveValue(namedValueInfo.name);
        Object arg = resolveName(resolvedName.toString(), nestedParameter, webRequest);

        if (arg == null) {
            if (namedValueInfo.defaultValue != null) {
                arg = resolveDefaultValue(namedValueInfo.defaultValue);
            } else if (namedValueInfo.required && !nestedParameter.isOptional()) {
                handleMissingValue(namedValueInfo.name, nestedParameter, webRequest);
            }
            arg = handleNullValue(namedValueInfo.name, arg, nestedParameter.getNestedParameterType());
        }

        if (binderFactory != null) {
            WebDataBinder binder = binderFactory.createBinder(webRequest, null, namedValueInfo.name);
            arg = binder.convertIfNecessary(resolvedArg, parameter.getParameterType(), parameter);
        }

        handleResolvedValue(arg, namedValueInfo.name, parameter, mavContainer, webRequest);
        return arg;
    }

    @Nullable
    protected abstract Object resolveName(String name, MethodParameter parameter,
            NativeWebRequest request) throws Exception;

    protected abstract NamedValueInfo getNamedValueInfo(MethodParameter parameter);
}

该抽象类核心流程为：子类提供命名信息 → 解析占位符/SpEL → 子类从请求中取值 → 处理缺失值 → 类型转换 → 子类 hook。

5. @PathVariable 与 PathVariableMethodArgumentResolver

@PathVariable 从 URI 模板中提取变量值：

java

public class PathVariableMethodArgumentResolver
        extends AbstractNamedValueMethodArgumentResolver
        implements UriComponentsContributor {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        if (!parameter.hasParameterAnnotation(PathVariable.class)) return false;
        if (Map.class.isAssignableFrom(parameter.nestedIfOptional().getNestedParameterType())) return false;
        return true;
    }

    @Override
    protected NamedValueInfo getNamedValueInfo(MethodParameter parameter) {
        PathVariable ann = parameter.getParameterAnnotation(PathVariable.class);
        return new NamedValueInfo(ann.name(), ann.required(), null);
    }

    @Override
    @Nullable
    protected Object resolveName(String name, MethodParameter parameter,
            NativeWebRequest request) throws Exception {
        Map<String, String> uriVariables = getUriTemplateVariables(request);
        return uriVariables.get(name);
    }
}

getUriTemplateVariables() 从请求属性中获取 URL 匹配阶段保存的模板变量：

java

static Map<String, String> getUriTemplateVariables(NativeWebRequest request) {
    Map<String, String> variables = (Map<String, String>) request.getAttribute(
            HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE, RequestAttributes.SCOPE_REQUEST);
    return (variables != null) ? variables : Collections.emptyMap();
}

应用示例：

java

@GetMapping("/users/{userId}/orders/{orderId}")
public Order getOrder(@PathVariable Long userId, @PathVariable String orderId) {
    return orderService.findOrder(userId, orderId);
}

6. @RequestParam 与 RequestParamMethodArgumentResolver

@RequestParam 从查询参数或表单数据中取值：

java

public class RequestParamMethodArgumentResolver
        extends AbstractNamedValueMethodArgumentResolver {

    private final boolean useDefaultResolution;

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        if (parameter.hasParameterAnnotation(RequestParam.class)) {
            if (Map.class.isAssignableFrom(parameter.nestedIfOptional().getNestedParameterType())) {
                RequestParam requestParam = parameter.getParameterAnnotation(RequestParam.class);
                return (requestParam != null && StringUtils.hasText(requestParam.name()));
            }
            return true;
        }
        if (useDefaultResolution) {
            return BeanUtils.isSimpleProperty(parameter.getNestedParameterType());
        }
        return false;
    }

    @Override
    @Nullable
    protected Object resolveName(String name, MethodParameter parameter,
            NativeWebRequest request) throws Exception {

        ServletRequest servletRequest = request.getNativeRequest(ServletRequest.class);
        if (servletRequest instanceof MultipartHttpServletRequest) {
            Object mpValue = ((MultipartHttpServletRequest) servletRequest).getMultiFileMap().get(name);
            if (mpValue != null) return mpValue;
        }

        String[] paramValues = request.getParameterValues(name);
        return (paramValues != null) ?
                (paramValues.length == 1 ? paramValues[0] : paramValues) : null;
    }
}

关键点：

默认值：请求未提供时使用 defaultValue
required 语义：默认 true，缺失抛出 MissingServletRequestParameterException
Multipart 支持：自动处理 MultipartFile 类型

7. @RequestBody 与 RequestResponseBodyMethodProcessor

RequestResponseBodyMethodProcessor 同时实现了 HandlerMethodArgumentResolver 和 HandlerMethodReturnValueHandler，既能处理请求体反序列化，也能处理 @ResponseBody 响应体序列化。

7.1 supportsParameter 与 resolveArgument

java

public class RequestResponseBodyMethodProcessor
        extends AbstractMessageConverterMethodProcessor {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(RequestBody.class);
    }

    @Override
    public Object resolveArgument(MethodParameter parameter,
            @Nullable ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            @Nullable WebDataBinderFactory binderFactory) throws Exception {

        HttpInputMessage inputMessage = createInputMessage(webRequest);
        Object arg = readWithMessageConverters(webRequest, parameter,
                parameter.getNestedGenericParameterType());

        RequestBody ann = parameter.getParameterAnnotation(RequestBody.class);
        if (ann != null && ann.required() && arg == null) {
            throw new HttpMessageNotReadableException("Required request body is missing", inputMessage);
        }

        if (binderFactory != null) {
            WebDataBinder binder = binderFactory.createBinder(webRequest, arg, parameter.getParameterName());
            if (arg != null) {
                validateIfApplicable(binder, parameter);
                if (binder.getBindingResult().hasErrors() && isBindExceptionRequired(binder, parameter)) {
                    throw new MethodArgumentNotValidException(parameter, binder.getBindingResult());
                }
            }
            mavContainer.addAllAttributes(binder.getBindingResult().getModel());
        }
        return arg;
    }
}

7.2 readWithMessageConverters 源码分析

readWithMessageConverters() 是 @RequestBody 反序列化的关键方法，遍历已注册的 HttpMessageConverter 找到合适的转换器执行读取：

java

protected <T> Object readWithMessageConverters(NativeWebRequest webRequest,
        MethodParameter parameter, Type targetType) throws Exception {

    HttpInputMessage inputMessage = createInputMessage(webRequest);

    MediaType contentType = inputMessage.getHeaders().getContentType();
    if (contentType == null) {
        contentType = MediaType.APPLICATION_OCTET_STREAM;
    }

    Class<T> targetClass = (Class<T>) ResolvableType.forMethodParameter(parameter).resolve();
    if (targetClass == null) {
        targetClass = (Class<T>) ResolvableType.forType(targetType).resolve();
    }

    for (HttpMessageConverter<?> converter : this.messageConverters) {
        GenericHttpMessageConverter<?> genericConverter =
                (converter instanceof GenericHttpMessageConverter ?
                        (GenericHttpMessageConverter<?>) converter : null);

        if (genericConverter != null) {
            if (genericConverter.canRead(targetType, targetClass, contentType)) {
                Object body = genericConverter.read(targetType, targetClass, inputMessage);
                if (body != null) return body;
            }
        } else if (targetClass != null && converter.canRead(targetClass, contentType)) {
            Object body = converter.read(targetClass, inputMessage);
            if (body != null) return body;
        }
    }

    throw new HttpMessageNotReadableException(
            "No suitable HttpMessageConverter found for " + contentType, inputMessage);
}

7.3 消息转换器选择流程

请求到达
    │
    ▼
readWithMessageConverters()
    │
    ├─ 1. 封装 HttpInputMessage（Content-Type + InputStream）
    ├─ 2. 确定 targetClass / targetType
    ├─ 3. 遍历 HttpMessageConverter 列表
    │      ├─ MappingJackson2HttpMessageConverter    ← application/json
    │      ├─ MappingJackson2XmlHttpMessageConverter  ← application/xml
    │      ├─ StringHttpMessageConverter              ← text/plain
    │      ├─ FormHttpMessageConverter                ← form-urlencoded
    │      ├─ ByteArrayHttpMessageConverter           ← octet-stream
    │      └─ ResourceHttpMessageConverter            ← 资源文件
    │
    ├─ 4. converter.canRead(targetClass, contentType) ?
    │      ├─ true  → converter.read() 反序列化
    │      └─ false → 下一个 converter
    │
    └─ 5. 无匹配转换器 → 抛出 HttpMessageNotReadableException

8. @ModelAttribute 与 ModelAttributeMethodProcessor

@ModelAttribute 将请求参数绑定到 Model 对象的属性上，常用于表单提交场景。

8.1 解析器实现

java

public class ModelAttributeMethodProcessor
        implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(ModelAttribute.class);
    }

    @Override
    @Nullable
    public Object resolveArgument(MethodParameter parameter,
            @Nullable ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            @Nullable WebDataBinderFactory binderFactory) throws Exception {

        ModelAttribute ann = parameter.getParameterAnnotation(ModelAttribute.class);
        String name = ann.name();
        if (!StringUtils.hasText(name)) {
            name = Conventions.getVariableNameForParameter(parameter);
        }

        Object attribute = (mavContainer.containsAttribute(name) ?
                mavContainer.getModel().get(name) : null);

        if (attribute == null) {
            attribute = createAttribute(name, parameter, binderFactory, webRequest);
        }

        WebDataBinder binder = binderFactory.createBinder(webRequest, attribute, name);
        if (binder.getTarget() != null) {
            bindRequestParameters(binder, webRequest);
            validateIfApplicable(binder, parameter);
            if (binder.getBindingResult().hasErrors() && isBindExceptionRequired(binder, parameter)) {
                throw new BindException(binder.getBindingResult());
            }
        }

        mavContainer.addAllAttributes(binder.getBindingResult().getModel());
        return binder.getTarget();
    }

    protected Object createAttribute(String attributeName,
            MethodParameter parameter, WebDataBinderFactory binderFactory,
            NativeWebRequest webRequest) throws Exception {
        return BeanUtils.instantiateClass(parameter.getParameterType());
    }
}

createAttribute() 默认通过无参构造器创建目标对象。bindRequestParameters() 内部使用 ServletRequestDataBinder，遍历请求参数并通过 JavaBean setter 或直接字段赋值完成绑定：

请求参数                    User 对象
┌──────────────┐       ┌──────────────┐
│ name=张三    │ ─────→ │ name = "张三"│
│ age=25       │ ─────→ │ age = 25    │
│ email=...    │ ─────→ │ email = ... │
└──────────────┘       └──────────────┘
                               ↑
                        ServletRequestDataBinder
                        （属性访问器 + 类型转换）

8.2 @ModelAttribute 绑定示例

java

@PostMapping("/users")
public String createUser(@ModelAttribute User user) {
    userService.save(user);
    return "redirect:/users/" + user.getId();
}

9. 参数解析器的注册与排序

RequestMappingHandlerAdapter 初始化时通过 getDefaultArgumentResolvers() 组装默认解析器列表。注册顺序决定参数匹配的优先级：

java

private List<HandlerMethodArgumentResolver> getDefaultArgumentResolvers() {
    List<HandlerMethodArgumentResolver> resolvers = new ArrayList<>();

    // 第一阶段：注解驱动解析器（高优先级）
    resolvers.add(new RequestParamMethodArgumentResolver(getBeanFactory(), false));
    resolvers.add(new RequestParamMapMethodArgumentResolver());
    resolvers.add(new PathVariableMethodArgumentResolver());
    resolvers.add(new PathVariableMapMethodArgumentResolver());
    resolvers.add(new MatrixVariableMethodArgumentResolver());
    resolvers.add(new MatrixVariableMapMethodArgumentResolver());
    resolvers.add(new ServletModelAttributeMethodProcessor(false));
    // ... 更多注解解析器（@RequestHeader、@CookieValue 等）
    resolvers.add(new RequestResponseBodyMethodProcessor(messageConverters, requestResponseBodyAdvice));
    resolvers.add(new HttpEntityMethodProcessor(messageConverters, requestResponseBodyAdvice));

    // 第二阶段：框架内部类型解析器
    resolvers.add(new ServletRequestMethodArgumentAdapter());
    resolvers.add(new ServletResponseMethodArgumentAdapter());
    resolvers.add(new ModelMethodProcessor());
    resolvers.add(new ErrorsMethodArgumentResolver());

    // 第三阶段：兜底解析器（低优先级）
    resolvers.add(new RequestParamMethodArgumentResolver(getBeanFactory(), true));
    resolvers.add(new ServletModelAttributeMethodProcessor(true));
    return resolvers;
}

注册顺序设计原则：

优先级	阶段	解析器	说明
最高	第一阶段	注解驱动解析器	注解明确的参数优先匹配
中等	第二阶段	框架内部组件	`HttpServletRequest`、`Model`、`Errors` 等
最低	第三阶段	兜底解析器	无注解简单类型→RequestParam，复杂类型→ModelAttribute

10. 自定义参数解析器实战

当默认解析器无法满足需求时，可实现自定义 HandlerMethodArgumentResolver。下面演示从请求头解析当前用户信息的解析器。

10.1 定义目标注解

java

@Target(ElementType.PARAMETER)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface CurrentUser {
    String value() default "X-User-Id";
}

10.2 实现参数解析器

java

public class CurrentUserMethodArgumentResolver
        implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter parameter) {
        return parameter.hasParameterAnnotation(CurrentUser.class)
                && UserInfo.class.isAssignableFrom(parameter.getParameterType());
    }

    @Override
    public Object resolveArgument(MethodParameter parameter,
            @Nullable ModelAndViewContainer mavContainer,
            NativeWebRequest webRequest,
            @Nullable WebDataBinderFactory binderFactory) throws Exception {

        CurrentUser currentUser = parameter.getParameterAnnotation(CurrentUser.class);
        String headerName = (currentUser != null) ? currentUser.value() : "X-User-Id";

        String userId = webRequest.getHeader(headerName);
        if (userId == null || userId.isEmpty()) {
            throw new IllegalArgumentException("Missing user id in header: " + headerName);
        }

        UserInfo userInfo = new UserInfo();
        userInfo.setUserId(Long.parseLong(userId));
        userInfo.setUsername("user_" + userId);
        return userInfo;
    }
}

10.3 注册自定义解析器

java

@Configuration
@EnableWebMvc
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addArgumentResolvers(
            List<HandlerMethodArgumentResolver> resolvers) {
        resolvers.add(new CurrentUserMethodArgumentResolver());
    }
}

10.4 使用自定义解析器

java

@RestController
@RequestMapping("/api")
public class UserController {
    @GetMapping("/profile")
    public Result<UserInfo> getProfile(@CurrentUser("X-User-Id") UserInfo currentUser) {
        return Result.success(currentUser);
    }
}

10.5 注意事项

supportsParameter 务必定向：精确限定条件，避免拦截不应由你处理的参数
异常处理：应抛出框架能识别的异常类型
线程安全：解析器是单例的，不应持有请求级别的状态
优先级控制：可通过 Ordered 接口或在 WebMvcConfigurer 中控制列表插入位置

11. 参数绑定完整流程图

DispatcherServlet.doDispatch()
         │
         ▼
    getHandlerAdapter() → RequestMappingHandlerAdapter
         │
         ▼
    handle() → invokeHandlerMethod()
         │
         ├─ 1. 创建 ServletInvocableHandlerMethod
         ├─ 2. 设置 DataBinderFactory
         ├─ 3. 设置 argumentResolvers
         ├─ 4. 设置 returnValueHandlers
         ├─ 5. 初始化 Model 属性 (@ModelAttribute 方法)
         │
         ▼
    invokeAndHandle() → invokeForRequest()
         │
         ▼
    getMethodArgumentValues()
         │
         ├─ for each parameter:
         │      ├─ resolvers.supportsParameter(parameter)
         │      │      ├─ true  → 使用该解析器
         │      │      └─ false → 遍历下一个
         │      │
         │      ▼
         │   resolver.resolveArgument()
         │      ├─ 读取请求数据（URI/参数/请求体/请求头等）
         │      ├─ 类型转换（WebDataBinder.convertIfNecessary）
         │      ├─ 参数校验（JSR-303 @Valid）
         │      └─ 返回参数值
         │
         ├─ args 数组已填充 ↓
         │
         ▼
    doInvoke(args) → 反射执行 @RequestMapping 方法
         │
         ▼
    ReturnValueHandler.handleReturnValue()
         ├─ @ResponseBody → HttpMessageConverter 序列化
         ├─ String → 视图解析
         └─ ModelAndView → 合并模型和视图

12. 参数解析器与类型转换的协作

参数解析器负责从请求中读取原始数据，类型转换由 WebDataBinder 和 ConversionService 完成：

原始数据                 类型转换                      最终参数
┌──────────┐       ┌──────────────┐           ┌──────────────┐
│ "123"     │ ───→ │ NumberFormat  │ ───────→  │ Long(123)    │
│ "2024-01" │ ───→ │ DateFormat    │ ───────→  │ Date         │
│ "true"    │ ───→ │ BooleanConv.  │ ───────→  │ Boolean(true)│
│ {json}    │ ───→ │ Jackson       │ ───────→  │ User 对象    │
└──────────┘       └──────────────┘           └──────────────┘
                         ↑
                 ConversionService（80+ 内置转换器 + 自定义转换器）

内置转换器如 StringToNumberConverterFactory、StringToBooleanConverter、StringToEnumConverterFactory、StringToUUIDConverter、StringToLocaleConverter 等。自定义类型转换可通过 WebMvcConfigurer.addFormatters() 或 WebDataBinder 层面配置。

13. 常见问题与排查思路

13.1 参数解析失败

出现 "No suitable resolver" 或 "Required request body is missing" 时：

1. 确认参数注解是否正确（@RequestParam vs @RequestBody）
2. 确认解析器注册顺序是否符合预期
3. 确认请求包含必要的参数/请求体/请求头
4. 确认类型是否匹配（JSON 格式、日期格式等）
5. 确认 HttpMessageConverter 是否支持当前 Content-Type

13.2 类型转换异常

MethodArgumentTypeMismatchException 的排查方向：

ConversionService 是否注册了对应转换器
日期格式是否匹配（可用 @DateTimeFormat 指定）
枚举值是否匹配名称或 @JsonValue

13.3 @ModelAttribute 绑定失败

目标类需拥有无参构造器
请求参数名与 Java 属性名需匹配
setter 方法至少为 protected 可见性
嵌套属性使用 @ModelAttribute("user.address.city") 语法

14. 总结

Spring MVC 的参数绑定体系设计精巧，充分体现了"职责分离"和"模板方法模式"：

RequestMappingHandlerAdapter.invokeHandlerMethod() 是整个流程的编排入口
HandlerMethodArgumentResolver 定义了参数解析的抽象契约，20+ 内置实现覆盖主流场景
AbstractNamedValueMethodArgumentResolver 为命名值类注解提供统一模板
RequestResponseBodyMethodProcessor 通过 readWithMessageConverters() 实现灵活的反序列化
ModelAttributeMethodProcessor 将请求参数与 JavaBean 属性绑定

理解参数解析底层机制有助于排查绑定问题，也为构建灵活健壮的 Web 应用打下坚实基础。

@Controller 参数绑定源码分析 ​

1. 概述 ​

2. RequestMappingHandlerAdapter.invokeHandlerMethod() ​

2.1 调用入口 ​

2.2 invokeHandlerMethod 源码解析 ​

2.3 invokeForRequest 与参数解析入口 ​

3. getMethodArgumentValues 与参数解析循环 ​

4. HandlerMethodArgumentResolver 接口体系 ​

4.1 参数解析器体系结构图 ​

4.2 AbstractNamedValueMethodArgumentResolver ​

5. @PathVariable 与 PathVariableMethodArgumentResolver ​

6. @RequestParam 与 RequestParamMethodArgumentResolver ​

7. @RequestBody 与 RequestResponseBodyMethodProcessor ​

7.1 supportsParameter 与 resolveArgument ​

7.2 readWithMessageConverters 源码分析 ​

7.3 消息转换器选择流程 ​

8. @ModelAttribute 与 ModelAttributeMethodProcessor ​

8.1 解析器实现 ​

8.2 @ModelAttribute 绑定示例 ​

9. 参数解析器的注册与排序 ​

10. 自定义参数解析器实战 ​

10.1 定义目标注解 ​

10.2 实现参数解析器 ​

10.3 注册自定义解析器 ​

10.4 使用自定义解析器 ​

10.5 注意事项 ​

11. 参数绑定完整流程图 ​

12. 参数解析器与类型转换的协作 ​

13. 常见问题与排查思路 ​

13.1 参数解析失败 ​

13.2 类型转换异常 ​

13.3 @ModelAttribute 绑定失败 ​

14. 总结 ​

@Controller 参数绑定源码分析

1. 概述

2. RequestMappingHandlerAdapter.invokeHandlerMethod()

2.1 调用入口

2.2 invokeHandlerMethod 源码解析

2.3 invokeForRequest 与参数解析入口

3. getMethodArgumentValues 与参数解析循环

4. HandlerMethodArgumentResolver 接口体系

4.1 参数解析器体系结构图

4.2 AbstractNamedValueMethodArgumentResolver

5. @PathVariable 与 PathVariableMethodArgumentResolver

6. @RequestParam 与 RequestParamMethodArgumentResolver

7. @RequestBody 与 RequestResponseBodyMethodProcessor

7.1 supportsParameter 与 resolveArgument

7.2 readWithMessageConverters 源码分析

7.3 消息转换器选择流程

8. @ModelAttribute 与 ModelAttributeMethodProcessor

8.1 解析器实现

8.2 @ModelAttribute 绑定示例

9. 参数解析器的注册与排序

10. 自定义参数解析器实战

10.1 定义目标注解

10.2 实现参数解析器

10.3 注册自定义解析器

10.4 使用自定义解析器

10.5 注意事项

11. 参数绑定完整流程图

12. 参数解析器与类型转换的协作

13. 常见问题与排查思路

13.1 参数解析失败

13.2 类型转换异常

13.3 @ModelAttribute 绑定失败

14. 总结