docs: add spring startup roadmap and debug app

Author: aotemiao

roadmap.md

@@ -171,18 +171,26 @@ private ClassLoader determineClassLoader(@Nullable ClassLoader classLoader) {
 		Object target = null;
 
 		try {
+			// --- 第一部分：特殊方法的快速通道处理 ---
+			// 在执行 AOP 增强逻辑之前，先处理掉一些不需要 AOP 的通用方法，以提高性能。
+
+			// 1. 如果调用的是 equals() 方法，并且目标类自己没实现它，就直接用代理的 equals 逻辑。
 			if (!this.cache.equalsDefined && AopUtils.isEqualsMethod(method)) {
 				// The target does not implement the equals(Object) method itself.
 				return equals(args[0]);
 			}
+			// 2. 如果调用的是 hashCode() 方法，并且目标类自己没实现它，就直接用代理的 hashCode 逻辑。
 			else if (!this.cache.hashCodeDefined && AopUtils.isHashCodeMethod(method)) {
 				// The target does not implement the hashCode() method itself.
 				return hashCode();
 			}
+			// 3. 处理 Spring 内部的 DecoratingProxy 接口方法。
 			else if (method.getDeclaringClass() == DecoratingProxy.class) {
 				// There is only getDecoratedClass() declared -> dispatch to proxy config.
 				return AopProxyUtils.ultimateTargetClass(this.advised);
 			}
+			// 4. 如果调用的是 Advised 接口中的方法（用于获取 AOP 配置信息），则直接在代理配置上执行并返回。
+			//    这允许我们检查一个代理对象自身的 AOP 配置。
 			else if (!this.advised.isOpaque() && method.getDeclaringClass().isInterface() &&
 					method.getDeclaringClass().isAssignableFrom(Advised.class)) {
 				// Service invocations on ProxyConfig with the proxy config...
@@ -191,39 +199,63 @@ else if (!this.advised.isOpaque() && method.getDeclaringClass().isInterface() &&
 
 			Object retVal;
 
+			// --- 第二部分：准备工作与获取“调用链” ---
+
+			// 5. 如果配置了要暴露代理对象（expose-proxy=true）
 			if (this.advised.isExposeProxy()) {
 				// Make invocation available if necessary.
+				// 将当前代理对象放入一个 ThreadLocal 中，这样在目标方法内部就可以通过 AopContext.currentProxy() 拿到它。
+				// 这解决了在方法内部调用自身其他方法时，无法触发 AOP 的问题。
 				oldProxy = AopContext.setCurrentProxy(proxy);
 				setProxyContext = true;
 			}
 
 			// Get as late as possible to minimize the time we "own" the target,
 			// in case it comes from a pool.
+			// 6. 从 TargetSource 获取真正的目标对象。延迟获取，以减少对池化对象的占用时间。
 			target = targetSource.getTarget();
 			Class<?> targetClass = (target != null ? target.getClass() : null);
 
 			// Get the interception chain for this method.
+			// 7. 【核心步骤】获取将要应用于此方法的“拦截器链”。
+			//    Spring 会根据 AOP 配置（例如 Pointcut 表达式）找到所有匹配的通知（Advice），
+			//    并将它们组成一个执行链（List）。
 			List<Object> chain = this.advised.getInterceptorsAndDynamicInterceptionAdvice(method, targetClass);
 
+
+			// --- 第三部分：执行调用链与目标方法 ---
+
 			// Check whether we have any advice. If we don't, we can fall back on direct
 			// reflective invocation of the target, and avoid creating a MethodInvocation.
+			// 8. 如果拦截器链为空，说明没有任何通知需要应用到此方法上。
 			if (chain.isEmpty()) {
 				// We can skip creating a MethodInvocation: just invoke the target directly
 				// Note that the final invoker must be an InvokerInterceptor so we know it does
 				// nothing but a reflective operation on the target, and no hot swapping or fancy proxying.
+				// 这是一个优化：直接通过反射调用目标对象的原始方法，避免创建 MethodInvocation 对象的开销。
 				@Nullable Object[] argsToUse = AopProxyUtils.adaptArgumentsIfNecessary(method, args);
 				retVal = AopUtils.invokeJoinpointUsingReflection(target, method, argsToUse);
 			}
 			else {
 				// We need to create a method invocation...
+				// 9. 【核心步骤】如果拦截器链不为空，就需要执行 AOP 逻辑。
+				//    创建一个 MethodInvocation 对象，它封装了本次调用的所有信息（代理、目标、方法、参数、调用链等）。
 				MethodInvocation invocation =
 						new ReflectiveMethodInvocation(proxy, target, method, args, targetClass, chain);
 				// Proceed to the joinpoint through the interceptor chain.
+				//    【启动调用链】调用 proceed() 方法，这会像多米诺骨牌一样，
+				//    从第一个拦截器开始，依次执行（例如 @Around -> @Before -> 目标方法 -> @After -> @Around），
+				//    最后返回目标方法的执行结果。
 				retVal = invocation.proceed();
 			}
 
+			// --- 第四部分：返回值处理 ---
+
 			// Massage return value if necessary.
+			// 10. 对返回值进行一些特殊处理。
 			Class<?> returnType = method.getReturnType();
+			// 如果目标方法返回了 `this`（即目标对象自身），并且方法的返回类型与代理类型兼容，
+			// 那么应该返回代理对象 `proxy` 而不是原始的 `target`，以确保调用者始终持有的是代理。
 			if (retVal != null && retVal == target &&
 					returnType != Object.class && returnType.isInstance(proxy) &&
 					!RawTargetAccess.class.isAssignableFrom(method.getDeclaringClass())) {
@@ -232,21 +264,28 @@ else if (!this.advised.isOpaque() && method.getDeclaringClass().isInterface() &&
 				// a reference to itself in another returned object.
 				retVal = proxy;
 			}
+			// 如果方法要求返回基本类型，但结果是 null，则抛出异常。
 			else if (retVal == null && returnType != void.class && returnType.isPrimitive()) {
 				throw new AopInvocationException(
 						"Null return value from advice does not match primitive return type for: " + method);
 			}
+			// 对 Kotlin 协程的特殊处理
 			if (coroutinesReactorPresent && KotlinDetector.isSuspendingFunction(method)) {
 				return COROUTINES_FLOW_CLASS_NAME.equals(new MethodParameter(method, -1).getParameterType().getName()) ?
 						CoroutinesUtils.asFlow(retVal) : CoroutinesUtils.awaitSingleOrNull(retVal, args[args.length - 1]);
 			}
 			return retVal;
 		}
 		finally {
+			// --- 第五部分：清理工作 ---
+
+			// 11. 如果目标对象不是静态的（例如，来自对象池），则释放它。
 			if (target != null && !targetSource.isStatic()) {
 				// Must have come from TargetSource.
 				targetSource.releaseTarget(target);
 			}
+
+			// 12. 如果之前设置了 AopContext，现在必须将其从 ThreadLocal 中清除，以避免内存泄漏。
 			if (setProxyContext) {
 				// Restore old proxy.
 				AopContext.setCurrentProxy(oldProxy);

spring-aop/src/main/java/org/springframework/aop/framework/JdkDynamicAopProxy.java

@@ -154,28 +154,52 @@ public void setArguments(@Nullable Object... arguments) {
 	@Override
 	public @Nullable Object proceed() throws Throwable {
 		// We start with an index of -1 and increment early.
+		// 1. 判断是否已执行完所有拦截器 (递归的终止条件)
+		// this.interceptorsAndDynamicMethodMatchers 是一个包含所有拦截器的列表
+		// currentInterceptorIndex 的初始值为-1
+		// 如果当前拦截器的索引等于拦截器列表的最后一个索引，说明所有拦截器都执行完了
 		if (this.currentInterceptorIndex == this.interceptorsAndDynamicMethodMatchers.size() - 1) {
+			// 调用原始的目标方法（例如，你自己的业务Service方法）
 			return invokeJoinpoint();
 		}
 
+		// 2. 获取下一个要执行的拦截器
+		// 使用 ++this.currentInterceptorIndex，先将索引加1，再从列表中获取元素
+		// 所以第一次调用时，索引从-1变为0，获取第一个拦截器
 		Object interceptorOrInterceptionAdvice =
 				this.interceptorsAndDynamicMethodMatchers.get(++this.currentInterceptorIndex);
+
+		// 3. 判断拦截器的类型
 		if (interceptorOrInterceptionAdvice instanceof InterceptorAndDynamicMethodMatcher dm) {
 			// Evaluate dynamic method matcher here: static part will already have
 			// been evaluated and found to match.
+			// 3.1 类型一：动态匹配的拦截器
+			// 这种拦截器的切点(Pointcut)不仅需要匹配方法签名（静态匹配），
+			// 还需要在运行时根据方法的【参数】来决定是否执行（动态匹配）。
+			// Spring在构建拦截器链时，静态匹配的部分已经完成了。
 			Class<?> targetClass = (this.targetClass != null ? this.targetClass : this.method.getDeclaringClass());
+
+			// 在这里进行动态匹配的检查，检查传入的参数是否满足条件
 			if (dm.matcher().matches(this.method, targetClass, this.arguments)) {
+				// 动态匹配成功，则执行该拦截器的 invoke 方法
+				// 拦截器的 invoke 方法内部会再次调用 proceed()，从而形成调用链
 				return dm.interceptor().invoke(this);
 			}
 			else {
 				// Dynamic matching failed.
 				// Skip this interceptor and invoke the next in the chain.
+				// 动态匹配失败，则跳过当前这个拦截器
+				// 直接递归调用 proceed()，去执行下一个拦截器
 				return proceed();
 			}
 		}
 		else {
 			// It's an interceptor, so we just invoke it: The pointcut will have
 			// been evaluated statically before this object was constructed.
+			// 3.2 类型二：静态匹配的拦截器
+			// 这是最常见的类型。它的切点在编译期或启动时就能确定，无需在运行时检查参数。
+			// 直接执行该拦截器的 invoke 方法。
+			// 同样，拦截器的 invoke 方法内部会再次调用 proceed()，将控制权交给下一个拦截器。
 			return ((MethodInterceptor) interceptorOrInterceptionAdvice).invoke(this);
 		}
 	}

spring-aop/src/main/java/org/springframework/aop/framework/ReflectiveMethodInvocation.java

@@ -285,11 +285,49 @@ public PropertyValues postProcessProperties(PropertyValues pvs, Object bean, Str
 	@Override
 	public @Nullable Object postProcessAfterInitialization(@Nullable Object bean, String beanName) {
 		if (bean != null) {
+			// 1. 生成一个 key，通常就是 beanName
 			Object cacheKey = getCacheKey(bean.getClass(), beanName);
+			/*
+			 * 2. --- 核心判断逻辑 ---
+			 * `earlyBeanReferences` 是一个临时缓存，它记录了所有为了解决循环依赖问题而
+			 * 被提前暴露的 Bean 的引用。这行代码是整个方法的分水岭
+			 */
 			if (this.earlyBeanReferences.remove(cacheKey) != bean) {
+				/*
+				 * 进入此 if 块，意味着以下两种情况之一：
+				 *
+				 * 情况 A：这是一个“普通 Bean”，没有参与循环依赖。
+				 * - 那么 `earlyBeanReferences` 缓存中就没有它的记录
+				 * - `remove(cacheKey)` 会返回 `null`
+				 * - 判断条件变为 `null != bean`，结果为 `true`
+				 * - 流程：进入标准的代理创建流程 `wrapIfNecessary`
+				 *
+				 * 情况 B：这是一个“参与了循环依赖的 Bean”，并且在提前暴露时就已经创建了代理
+				 * - 在 `getEarlyBeanReference` 阶段，一个代理对象被创建并放入了 `earlyBeanReferences` 缓存
+				 * - `remove(cacheKey)` 会返回那个【代理对象】
+				 * - `bean` 参数是当前初始化完成的【原始对象】
+				 * - 判断条件变为 `代理对象 != 原始对象`，结果为 `true`
+				 * - 流程：同样进入 `wrapIfNecessary`。这个方法足够智能，会发现代理已创建，并确保返回正确的代理实例
+				 */
+
+				// `wrapIfNecessary` 会检查所有已知的切面（Aspects），判断当前 bean 是否是其目标
+				// - 如果是，并且代理还未创建，则创建并返回一个新的代理对象来替换原始 bean
+				// - 如果不是，则直接返回原始的 bean 对象
 				return wrapIfNecessary(bean, beanName, cacheKey);
 			}
 		}
+		/*
+		 * 3. 如果代码执行到这里，说明上面的 `if` 条件不满足 (`false`)
+		 * 这只对应一种非常特殊且重要的情况：
+		 *
+		 * 情况 C：这是一个“参与了循环依赖的 Bean”，但在提前暴露时【没有】为它创建代理
+		 * - 在 `getEarlyBeanReference` 阶段，Spring 判断它不需要提前代理，于是将【原始对象】本身放入了 `earlyBeanReferences` 缓存
+		 * - `remove(cacheKey)` 会返回那个【原始对象】
+		 * - `bean` 参数也是这个【原始对象】
+		 * - 判断条件变为 `原始对象 != 原始对象`，结果为 `false`
+		 * - 流程：为了保证在整个容器中该 Bean 引用的绝对一致性（因为依赖它的其他 Bean 已经注入了原始对象），
+		 * Spring 决定在此阶段也【不再】为它创建代理，直接返回原始的 bean 实例
+		 */
 		return bean;
 	}
 
@@ -323,27 +361,50 @@ protected Object getCacheKey(Class<?> beanClass, @Nullable String beanName) {
 	 * @return a proxy wrapping the bean, or the raw bean instance as-is
 	 */
 	protected Object wrapIfNecessary(Object bean, String beanName, Object cacheKey) {
+		// --- 第一部分：快速失败与跳过检查 ---
+		// 1. 如果这个 bean 已经被一个 TargetSource 处理，说明它有特殊的代理逻辑，这里就不再处理
 		if (StringUtils.hasLength(beanName) && this.targetSourcedBeans.contains(beanName)) {
 			return bean;
 		}
+		// 2. 检查缓存：如果之前已经判断过这个 bean 不需要被代理，就直接返回
+		//    advisedBeans 是一个缓存 Map，避免对同一个 Bean 重复进行 costly 的 AOP 匹配
 		if (Boolean.FALSE.equals(this.advisedBeans.get(cacheKey))) {
 			return bean;
 		}
+		// 3. 检查是否是“基础设施类”或应该被“跳过”
+		//    isInfrastructureClass: AOP 框架自身的组件（如 Advisor, Pointcut）不应该被自己代理，否则会无限循环
+		//    shouldSkip: 更通用的跳过逻辑，例如，避免代理 AOP 已经处理过的 Bean
 		if (isInfrastructureClass(bean.getClass()) || shouldSkip(bean.getClass(), beanName)) {
 			this.advisedBeans.put(cacheKey, Boolean.FALSE);
 			return bean;
 		}
 
 		// Create proxy if we have advice.
+		// --- 第二部分：核心代理创建逻辑 ---
+		// 如果 Bean 通过了所有豁免检查，就要进入真正的“安检扫描”环节
+
+		// 1. 【核心】为当前 Bean 查找匹配的通知（Advices）和顾问（Advisors）
+		//    这是 AOP 最关键的匹配步骤。Spring 会遍历所有已知的切面（@Aspect），
+		//    用它们的切点（Pointcut）去匹配当前 bean 的类和方法
 		Object[] specificInterceptors = getAdvicesAndAdvisorsForBean(bean.getClass(), beanName, null);
+		// 2. 判断是否有匹配的通知
+		//    如果返回的数组不是 DO_NOT_PROXY（一个空对象标记），说明找到了至少一个适用于此 bean 的通知
 		if (specificInterceptors != DO_NOT_PROXY) {
+			// 缓存标记，说明此 bean 需要被代理
 			this.advisedBeans.put(cacheKey, Boolean.TRUE);
+			// 3. 【执行】创建代理对象
+			//    这个方法会调用 ProxyFactory，使用 CGLIB 或 JDK 动态代理技术，
+			//    创建一个包装了原始 bean 实例并织入了相应通知（interceptors）的代理对象
 			Object proxy = createProxy(
 					bean.getClass(), beanName, specificInterceptors, new SingletonTargetSource(bean));
+			// 缓存代理的类型，用于后续的类型匹配
 			this.proxyTypes.put(cacheKey, proxy.getClass());
+			// 4. 返回创建好的代理对象。这个代理将替换掉原始的 bean 实例
 			return proxy;
 		}
 
+		// 如果没有找到任何匹配的通知，说明这个 Bean 不需要被代理
+		// 缓存这个结果，并返回原始的 bean 实例
 		this.advisedBeans.put(cacheKey, Boolean.FALSE);
 		return bean;
 	}
@@ -444,31 +505,51 @@ private Class<?> createProxyClass(Class<?> beanClass, @Nullable String beanName,
 	private Object buildProxy(Class<?> beanClass, @Nullable String beanName,
 			Object @Nullable [] specificInterceptors, TargetSource targetSource, boolean classOnly) {
 
+		// --- 准备阶段：配置装配工具 (ProxyFactory) ---
+
 		if (this.beanFactory instanceof ConfigurableListableBeanFactory clbf) {
+			// 在 BeanFactory 中暴露目标类的类型，方便其他组件解析（例如，按类型注入时能正确找到）
 			AutoProxyUtils.exposeTargetClass(clbf, beanName, beanClass);
 		}
 
+		// ProxyFactory 是创建代理的核心工具，就像装机的“工作台”
 		ProxyFactory proxyFactory = new ProxyFactory();
+		// 从 AutoProxyCreator 复制通用配置（如 exposeProxy=true 等）到工作台
 		proxyFactory.copyFrom(this);
+		// 暂时允许对配置进行修改
 		proxyFactory.setFrozen(false);
 
+
+		// --- 决策阶段：选择代理策略（用 CGLIB 还是 JDK 动态代理？）---
+		// 这就像决定是用一个“兼容主板”（JDK代理）还是一个“品牌定制主板”（CGLIB代理）。
+
+		// shouldProxyTargetClass 会检查全局配置或 bean 上的 @Scope(proxyMode=...) 等
 		if (shouldProxyTargetClass(beanClass, beanName)) {
+			// 强制使用 CGLIB 代理（基于类的代理），它通过创建子类来实现
 			proxyFactory.setProxyTargetClass(true);
 		}
 		else {
+			// 尝试使用 JDK 动态代理（基于接口的代理）
+			// 首先，检查 bean 是否暴露了特定的接口
 			Class<?>[] ifcs = (this.beanFactory instanceof ConfigurableListableBeanFactory clbf ?
 					AutoProxyUtils.determineExposedInterfaces(clbf, beanName) : null);
 			if (ifcs != null) {
+				// 如果有接口，就明确告诉工厂使用 JDK 代理模式
 				proxyFactory.setProxyTargetClass(false);
+				// 并将所有接口添加到代理配置中，代理将会实现这些接口
 				for (Class<?> ifc : ifcs) {
 					proxyFactory.addInterface(ifc);
 				}
 			}
+			// 如果没有找到明确的接口，或者即使找到了接口但策略仍不确定
 			if (ifcs != null ? ifcs.length == 0 : !proxyFactory.isProxyTargetClass()) {
+				// 再次评估 beanClass 本身实现的接口，这是一个备用策略
 				evaluateProxyInterfaces(beanClass, proxyFactory);
 			}
 		}
 
+		// 特殊处理：如果目标本身就是 JDK 代理或 Lambda 表达式，为了支持“引入增强”(Introduction)，
+		// 需要将其实现的接口也添加到新的代理中。
 		if (proxyFactory.isProxyTargetClass()) {
 			// Explicit handling of JDK proxy targets and lambdas (for introduction advice scenarios)
 			if (Proxy.isProxyClass(beanClass) || ClassUtils.isLambdaClass(beanClass)) {
@@ -479,21 +560,35 @@ private Object buildProxy(Class<?> beanClass, @Nullable String beanName,
 			}
 		}
 
+		// --- 组装阶段：将 AOP 组件装配到工厂 ---
+
+		// 将原始的拦截器（Interceptors）数组转换为标准的 Advisor 数组。
+		// Advisor = 通知(Advice) + 切点(Pointcut)，即“做什么”+“在哪里做”。
 		Advisor[] advisors = buildAdvisors(beanName, specificInterceptors);
+		// 将“增强功能”（如事务、日志 Advisor）安装到工作台上
 		proxyFactory.addAdvisors(advisors);
+		// 将“核心部件”（目标 bean 对象）安装到工作台上
 		proxyFactory.setTargetSource(targetSource);
+		// 提供一个钩子方法，允许子类对工作台进行最后的定制化修改
 		customizeProxyFactory(proxyFactory);
 
+		// --- 生产阶段：生成最终的代理对象 ---
+
+		// 锁定配置，不允许再修改
 		proxyFactory.setFrozen(isFrozen());
 		if (advisorsPreFiltered()) {
+			// 一个优化，告诉工厂 Advisor 已经预先过滤，无需再次检查
 			proxyFactory.setPreFiltered(true);
 		}
 
 		// Use original ClassLoader if bean class not locally loaded in overriding class loader
+		// 获取合适的 ClassLoader
 		ClassLoader classLoader = getProxyClassLoader();
 		if (classLoader instanceof SmartClassLoader smartClassLoader && classLoader != beanClass.getClassLoader()) {
 			classLoader = smartClassLoader.getOriginalClassLoader();
 		}
+		// 调用工厂的 getProxy() 或 getProxyClass() 方法，正式“生产”出代理。
+		// 工厂会根据之前设置的策略（CGLIB 或 JDK）来创建最终的产品。
 		return (classOnly ? proxyFactory.getProxyClass(classLoader) : proxyFactory.getProxy(classLoader));
 	}