// 基于 Spring Framework 5.3.39 (本地 JavaSourceReadingLab), org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter
public class RequestMappingHandlerAdapter extends AbstractHandlerMethodAdapter implements BeanFactoryAware, InitializingBean {

	// 只要是 HandlerMethod 一律接手。真正的匹配早在 HandlerMapping 阶段做完了，adapter 不再挑
	@Override
	protected boolean supportsInternal(HandlerMethod handlerMethod) {
		return true;
	}

	// ha.handle() 最终落到这里
	@Override
	protected ModelAndView handleInternal(HttpServletRequest request,
			HttpServletResponse response, HandlerMethod handlerMethod) throws Exception {

		ModelAndView mav;
		checkRequest(request);      // 校验 HTTP 方法是否被支持、是否要求 session

		// Execute invokeHandlerMethod in synchronized block if required.
		if (this.synchronizeOnSession) {
			// ... 省略：可选的按 session 串行化，默认关闭
		}
		else {
			// No synchronization on session demanded at all...
			mav = invokeHandlerMethod(request, response, handlerMethod);
		}
		// ... 省略 Cache-Control 处理
		return mav;
	}

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

		WebAsyncManager asyncManager = WebAsyncUtils.getAsyncManager(request);
		// ... 省略异步基础设施装配 (asyncWebRequest / taskExecutor / 拦截器注册)

		ServletWebRequest webRequest = (asyncWebRequest instanceof ServletWebRequest ?
				(ServletWebRequest) asyncWebRequest : new ServletWebRequest(request, response));

		try {
			WebDataBinderFactory binderFactory = getDataBinderFactory(handlerMethod);   // 收集 @InitBinder 方法
			ModelFactory modelFactory = getModelFactory(handlerMethod, binderFactory);  // 收集 @ModelAttribute 方法

			// HandlerMethod 只是"方法描述"，每次请求包装成可执行的 ServletInvocableHandlerMethod（无状态→有状态）
			ServletInvocableHandlerMethod invocableMethod = createInvocableHandlerMethod(handlerMethod);
			if (this.argumentResolvers != null) {
				invocableMethod.setHandlerMethodArgumentResolvers(this.argumentResolvers);   // 全局共享的解析器链
			}
			if (this.returnValueHandlers != null) {
				invocableMethod.setHandlerMethodReturnValueHandlers(this.returnValueHandlers);
			}
			invocableMethod.setDataBinderFactory(binderFactory);
			invocableMethod.setParameterNameDiscoverer(this.parameterNameDiscoverer);   // 靠它从字节码里挖参数名

			ModelAndViewContainer mavContainer = new ModelAndViewContainer();   // 本次请求的 model/view 状态载体
			mavContainer.addAllAttributes(RequestContextUtils.getInputFlashMap(request));
			modelFactory.initModel(webRequest, mavContainer, invocableMethod);  // 先执行 @ModelAttribute 方法填充 model
			mavContainer.setIgnoreDefaultModelOnRedirect(this.ignoreDefaultModelOnRedirect);

			// ... 省略异步结果恢复分支 (asyncManager.hasConcurrentResult())

			invocableMethod.invokeAndHandle(webRequest, mavContainer);   // 参数解析→反射调用→返回值处理，全在这一句里
			if (asyncManager.isConcurrentHandlingStarted()) {
				return null;
			}

			return getModelAndView(mavContainer, modelFactory, webRequest);   // requestHandled=true 时返回 null
		}
		finally {
			webRequest.requestCompleted();
		}
	}

	// 参数解析器链的默认装配。顺序就是优先级，这个顺序本身是语义
	private List<HandlerMethodArgumentResolver> getDefaultArgumentResolvers() {
		List<HandlerMethodArgumentResolver> resolvers = new ArrayList<>(30);

		// Annotation-based argument resolution
		resolvers.add(new RequestParamMethodArgumentResolver(getBeanFactory(), false));   // @RequestParam（严格模式）
		resolvers.add(new PathVariableMethodArgumentResolver());                          // @PathVariable
		resolvers.add(new ServletModelAttributeMethodProcessor(false));                   // @ModelAttribute
		resolvers.add(new RequestResponseBodyMethodProcessor(getMessageConverters(), this.requestResponseBodyAdvice));   // @RequestBody
		resolvers.add(new RequestHeaderMethodArgumentResolver(getBeanFactory()));         // @RequestHeader
		// ... 省略其余注解型解析器

		// Type-based argument resolution
		resolvers.add(new ServletRequestMethodArgumentResolver());    // 直接注入 HttpServletRequest 这类原生对象
		resolvers.add(new ServletResponseMethodArgumentResolver());
		// ... 省略其余类型解析器

		// Custom arguments
		if (getCustomArgumentResolvers() != null) {
			resolvers.addAll(getCustomArgumentResolvers());
		}

		// Catch-all：兜底。裸写 String id 没加注解，落到这里按 @RequestParam 默认规则处理
		resolvers.add(new PrincipalMethodArgumentResolver());
		resolvers.add(new RequestParamMethodArgumentResolver(getBeanFactory(), true));
		resolvers.add(new ServletModelAttributeMethodProcessor(true));

		return resolvers;
	}

	// 返回值处理器链，同样顺序即优先级
	private List<HandlerMethodReturnValueHandler> getDefaultReturnValueHandlers() {
		List<HandlerMethodReturnValueHandler> handlers = new ArrayList<>(20);

		// Single-purpose return value types
		handlers.add(new ModelAndViewMethodReturnValueHandler());
		handlers.add(new HttpEntityMethodProcessor(getMessageConverters(),
				this.contentNegotiationManager, this.requestResponseBodyAdvice));   // ResponseEntity
		// ... 省略流式/异步返回值处理器

		// Annotation-based return value types
		handlers.add(new ServletModelAttributeMethodProcessor(false));
		handlers.add(new RequestResponseBodyMethodProcessor(getMessageConverters(),
				this.contentNegotiationManager, this.requestResponseBodyAdvice));   // @ResponseBody：走 MessageConverter 直写响应体

		// Multi-purpose return value types
		handlers.add(new ViewNameMethodReturnValueHandler());   // 返回 String 默认当视图名，这就是为什么忘了 @ResponseBody 会 404 找视图
		handlers.add(new MapMethodProcessor());
		// ... 省略自定义与兜底
		return handlers;
	}
}

// 基于 Spring Framework 5.3.39 (本地 JavaSourceReadingLab), org.springframework.web.method.support.InvocableHandlerMethod
public class InvocableHandlerMethod extends HandlerMethod {

	// "HTTP → 方法调用"的最后一跳：先凑齐参数数组，再反射
	@Nullable
	public Object invokeForRequest(NativeWebRequest request, @Nullable ModelAndViewContainer mavContainer,
			Object... providedArgs) throws Exception {

		Object[] args = getMethodArgumentValues(request, mavContainer, providedArgs);
		// ... 省略 trace 日志
		return doInvoke(args);
	}

	// 逐个参数问一遍解析器链：谁 supports 谁上
	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);   // 外部直供的参数(如 @ExceptionHandler 的异常对象)优先，按类型匹配
			if (args[i] != null) {
				continue;
			}
			if (!this.resolvers.supportsParameter(parameter)) {        // composite 内部有 参数→解析器 缓存，链只完整走第一次
				throw new IllegalStateException(formatArgumentError(parameter, "No suitable resolver"));
			}
			try {
				args[i] = this.resolvers.resolveArgument(parameter, mavContainer, request, this.dataBinderFactory);
			}
			catch (Exception ex) {
				// Leave stack trace for later, exception may actually be resolved and handled...
				// ... 省略 debug 日志
				throw ex;
			}
		}
		return args;
	}

	// 反射调用本体
	@Nullable
	protected Object doInvoke(Object... args) throws Exception {
		Method method = getBridgedMethod();     // 泛型桥接方法处理，拿到真正带类型信息的方法
		try {
			if (KotlinDetector.isSuspendingFunction(method)) {
				return CoroutinesUtils.invokeSuspendingFunction(method, getBean(), args);
			}
			return method.invoke(getBean(), args);
		}
		catch (IllegalArgumentException ex) {
			assertTargetBean(method, getBean(), args);
			String text = (ex.getMessage() != null ? ex.getMessage() : "Illegal argument");
			throw new IllegalStateException(formatInvokeError(text, args), ex);
		}
		catch (InvocationTargetException ex) {
			// Unwrap for HandlerExceptionResolvers ...
			// 拆掉反射包装，让业务异常以原始类型抛出去，@ExceptionHandler 才能按异常类型匹配
			Throwable targetException = ex.getTargetException();
			if (targetException instanceof RuntimeException) {
				throw (RuntimeException) targetException;
			}
			else if (targetException instanceof Error) {
				throw (Error) targetException;
			}
			else if (targetException instanceof Exception) {
				throw (Exception) targetException;
			}
			else {
				throw new IllegalStateException(formatInvokeError("Invocation failure", args), targetException);
			}
		}
	}
}