/**
 * @Configuration 是一个核心注解，用于指示该类是一个 Spring 配置类，
 * 可能包含一个或多个 @Bean 定义方法。此注解与 XML 配置是等效的，但以编程方式
 * 提供了更多的类型安全和灵活性。它通常与 @Bean、@ComponentScan 和其他注解结合使用，
 * 为 Spring 应用程序上下文定义 beans 和配置。
 * 
 * 通过 @Component 注解，@Configuration 被视为一个组件，
 * 这意味着 Spring 的组件扫描可以自动检测和处理它。
 * 
 * 例如，当在应用程序上下文中注册 @Configuration 类时，
 * 该类中定义的 @Bean 方法将被解析，并在上下文中注册相应的 beans。
 *
 * @author Rod Johnson
 * @author Chris Beams
 * @author Juergen Hoeller
 * @since 3.0
 * @see Bean
 * @see Profile
 * @see Import
 * @see ImportResource
 * @see ComponentScan
 * @see Lazy
 * @see PropertySource
 * @see AnnotationConfigApplicationContext
 * @see ConfigurationClassPostProcessor
 * @see org.springframework.core.env.Environment
 * @see org.springframework.test.context.ContextConfiguration
 */
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Configuration {

	/**
	 * 明确指定与 @Configuration 类相关的 Spring bean 定义的名称。
	 * 如果未指定（这是常见情况），则会自动生成 bean 的名称。
	 * 这个自定义名称仅在 @Configuration 类通过组件扫描被检测到，
	 * 或直接提供给 AnnotationConfigApplicationContext 时才有效。
	 * 如果 @Configuration 类以传统的 XML bean 定义方式注册，
	 * 则 bean 元素的名称/ID 会优先。
	 */
	@AliasFor(annotation = Component.class)
	String value() default "";

	/**
	 * 指定是否应代理 @Bean 方法，以强制执行 bean 生命周期行为。
	 * 例如，即使在用户代码中直接调用了 @Bean 方法，也要返回共享的单例 bean 实例。
	 * 这个特性需要方法拦截，通过在运行时生成的 CGLIB 子类来实现，
	 * 这带有一些限制，如配置类和其方法不能声明为 final。
	 * 
	 * 默认为 true，这允许在配置类内部通过直接方法调用进行"bean之间的引用"，
	 * 以及从另一个配置类对此配置的 @Bean 方法的外部调用。
	 * 如果这不是必需的，因为此特定配置的每个 @Bean 方法都是独立的，
	 * 并设计为容器使用的简单工厂方法，可以将此标志设置为 false 以避免 CGLIB 子类处理。
	 * 
	 * 关闭 bean 方法拦截实际上是独立处理 @Bean 方法，
	 * 就像在非 @Configuration 类上声明的那样，即 "@Bean 简易模式"。
	 * 在行为上，它等同于删除 @Configuration 注解。
	 */
	boolean proxyBeanMethods() default true;
}

public class ConfigurationApplication {

    public static void main(String[] args) {
        AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(MyConfiguration.class);
        MyConfiguration configuration = context.getBean(MyConfiguration.class);

        System.out.println(configuration.myBean());
        System.out.println(configuration.myBean());
    }
}

// proxyBeanMethods默认就是true，此处不设置
@Configuration
public class MyConfiguration {

    @Bean
    public MyBean myBean(){
        return new MyBean();
    }
}

public class MyBean {

}

com.xcs.spring.bean.MyBean@f736069
com.xcs.spring.bean.MyBean@f736069

@Configuration(proxyBeanMethods = false)
public class MyConfiguration {

    @Bean
    public MyBean myBean(){
        return new MyBean();
    }
}

com.xcs.spring.bean.MyBean@3b69e7d1
com.xcs.spring.bean.MyBean@815b41f

public class ConfigurationApplication {

    public static void main(String[] args) {
        AnnotationConfigApplicationContext context = new AnnotationConfigApplicationContext(MyConfiguration.class);
        MyConfiguration configuration = context.getBean(MyConfiguration.class);

        System.out.println(configuration.myBean());
        System.out.println(configuration.myBean());
    }
}

public AnnotationConfigApplicationContext(Class<?>... componentClasses) {
    // 步骤1. 这个构造方法初始化了基本的配置读取器和类路径扫描器
    this();
    // 步骤2. 这个方法将这些类注册到 Spring 上下文中，这样它们可以被识别并进一步处理。
    register(componentClasses);
    // 步骤3. 这个方法触发整个Spring容器的启动过程
    refresh();
}

public AnnotationConfigApplicationContext() {
    StartupStep createAnnotatedBeanDefReader = this.getApplicationStartup().start("spring.context.annotated-bean-reader.create");
    this.reader = new AnnotatedBeanDefinitionReader(this);
    createAnnotatedBeanDefReader.end();
    this.scanner = new ClassPathBeanDefinitionScanner(this);
}

public AnnotatedBeanDefinitionReader(BeanDefinitionRegistry registry) {
    this(registry, getOrCreateEnvironment(registry));
}

public AnnotatedBeanDefinitionReader(BeanDefinitionRegistry registry, Environment environment) {
    Assert.notNull(registry, "BeanDefinitionRegistry must not be null");
    Assert.notNull(environment, "Environment must not be null");
    this.registry = registry;
    this.conditionEvaluator = new ConditionEvaluator(registry, environment, null);
    AnnotationConfigUtils.registerAnnotationConfigProcessors(this.registry);
}

public static void registerAnnotationConfigProcessors(BeanDefinitionRegistry registry) {
    registerAnnotationConfigProcessors(registry, null);
}

public static Set<BeanDefinitionHolder> registerAnnotationConfigProcessors(
			BeanDefinitionRegistry registry, @Nullable Object source) {

    // ... [代码部分省略以简化]

    Set<BeanDefinitionHolder> beanDefs = new LinkedHashSet<>(8);
    
    if (!registry.containsBeanDefinition(CONFIGURATION_ANNOTATION_PROCESSOR_BEAN_NAME)) {
        RootBeanDefinition def = new RootBeanDefinition(ConfigurationClassPostProcessor.class);
        def.setSource(source);
        beanDefs.add(registerPostProcessor(registry, def, CONFIGURATION_ANNOTATION_PROCESSOR_BEAN_NAME));
    }

    // ... [代码部分省略以简化]

    return beanDefs;
}

@Override
public void register(Class<?>... componentClasses) {
    Assert.notEmpty(componentClasses, "At least one component class must be specified");
    StartupStep registerComponentClass = this.getApplicationStartup().start("spring.context.component-classes.register")
        .tag("classes", () -> Arrays.toString(componentClasses));
    this.reader.register(componentClasses);
    registerComponentClass.end();
}

public void register(Class<?>... componentClasses) {
    for (Class<?> componentClass : componentClasses) {
        registerBean(componentClass);
    }
}

public void registerBean(Class<?> beanClass) {
    doRegisterBean(beanClass, null, null, null, null);
}

private <T> void doRegisterBean(Class<T> beanClass, @Nullable String name,
			@Nullable Class<? extends Annotation>[] qualifiers, @Nullable Supplier<T> supplier,
			@Nullable BeanDefinitionCustomizer[] customizers) {

    AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(beanClass);
    
    // ... [代码部分省略以简化]
    
    String beanName = (name != null ? name : this.beanNameGenerator.generateBeanName(abd, this.registry));

    // ... [代码部分省略以简化]

    BeanDefinitionHolder definitionHolder = new BeanDefinitionHolder(abd, beanName);
    definitionHolder = AnnotationConfigUtils.applyScopedProxyMode(scopeMetadata, definitionHolder, this.registry);
    BeanDefinitionReaderUtils.registerBeanDefinition(definitionHolder, this.registry);
}

public static void registerBeanDefinition(
    	BeanDefinitionHolder definitionHolder, BeanDefinitionRegistry registry)
    	throws BeanDefinitionStoreException {

    // Register bean definition under primary name.
    String beanName = definitionHolder.getBeanName();
    registry.registerBeanDefinition(beanName, definitionHolder.getBeanDefinition());

    // Register aliases for bean name, if any.
    String[] aliases = definitionHolder.getAliases();
    if (aliases != null) {
        for (String alias : aliases) {
            registry.registerAlias(beanName, alias);
        }
    }
}

@Override
public void refresh() throws BeansException, IllegalStateException {
     // ... [代码部分省略以简化]
     // 调用在上下文中注册为bean的工厂处理器
     invokeBeanFactoryPostProcessors(beanFactory);
     // ... [代码部分省略以简化]
}

protected void invokeBeanFactoryPostProcessors(ConfigurableListableBeanFactory beanFactory) {
    PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors(beanFactory, getBeanFactoryPostProcessors());
    // ... [代码部分省略以简化]
}

public static void invokeBeanFactoryPostProcessors(
      ConfigurableListableBeanFactory beanFactory, List<BeanFactoryPostProcessor> beanFactoryPostProcessors) {
	// ... [代码部分省略以简化]
   	// Now, invoke the postProcessBeanFactory callback of all processors handled so far.
	invokeBeanFactoryPostProcessors(registryProcessors, beanFactory);
    // ... [代码部分省略以简化]
}

private static void invokeBeanFactoryPostProcessors(
			Collection<? extends BeanFactoryPostProcessor> postProcessors, ConfigurableListableBeanFactory beanFactory) {

    for (BeanFactoryPostProcessor postProcessor : postProcessors) {
        StartupStep postProcessBeanFactory = beanFactory.getApplicationStartup().start("spring.context.bean-factory.post-process")
            .tag("postProcessor", postProcessor::toString);
        postProcessor.postProcessBeanFactory(beanFactory);
        postProcessBeanFactory.end();
    }
}

@Override
public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
    // ... [代码部分省略以简化]
    enhanceConfigurationClasses(beanFactory);
    // ... [代码部分省略以简化]
}

public void enhanceConfigurationClasses(ConfigurableListableBeanFactory beanFactory) {
    // ... [代码部分省略以简化]

    ConfigurationClassEnhancer enhancer = new ConfigurationClassEnhancer();
    for (Map.Entry<String, AbstractBeanDefinition> entry : configBeanDefs.entrySet()) {
        AbstractBeanDefinition beanDef = entry.getValue();
        // If a @Configuration class gets proxied, always proxy the target class
        beanDef.setAttribute(AutoProxyUtils.PRESERVE_TARGET_CLASS_ATTRIBUTE, Boolean.TRUE);
        // Set enhanced subclass of the user-specified bean class
        Class<?> configClass = beanDef.getBeanClass();
        Class<?> enhancedClass = enhancer.enhance(configClass, this.beanClassLoader);
        if (configClass != enhancedClass) {
            // ... [代码部分省略以简化]
            beanDef.setBeanClass(enhancedClass);
        }
    }
    // ... [代码部分省略以简化]
}

public Class<?> enhance(Class<?> configClass, @Nullable ClassLoader classLoader) {
    if (EnhancedConfiguration.class.isAssignableFrom(configClass)) {
        // ... [代码部分省略以简化]
        return configClass;
    }
    Class<?> enhancedClass = createClass(newEnhancer(configClass, classLoader));
    // ... [代码部分省略以简化]
    return enhancedClass;
}

private Enhancer newEnhancer(Class<?> configSuperClass, @Nullable ClassLoader classLoader) {
    Enhancer enhancer = new Enhancer();
    enhancer.setSuperclass(configSuperClass);
    enhancer.setInterfaces(new Class<?>[] {EnhancedConfiguration.class});
    enhancer.setUseFactory(false);
    enhancer.setNamingPolicy(SpringNamingPolicy.INSTANCE);
    enhancer.setStrategy(new BeanFactoryAwareGeneratorStrategy(classLoader));
    enhancer.setCallbackFilter(CALLBACK_FILTER);
    enhancer.setCallbackTypes(CALLBACK_FILTER.getCallbackTypes());
    return enhancer;
}

private Class<?> createClass(Enhancer enhancer) {
    Class<?> subclass = enhancer.createClass();
    // Registering callbacks statically (as opposed to thread-local)
    // is critical for usage in an OSGi environment (SPR-5932)...
    Enhancer.registerStaticCallbacks(subclass, CALLBACKS);
    return subclass;
}

private static final Callback[] CALLBACKS = new Callback[] {
    new BeanMethodInterceptor(),
    new BeanFactoryAwareMethodInterceptor(),
    NoOp.INSTANCE
};

public Object intercept(Object enhancedConfigInstance, Method beanMethod, Object[] beanMethodArgs,
				MethodProxy cglibMethodProxy) throws Throwable {

	// 获取关联的 BeanFactory 通过反射读取了代理类中的$$beanFactory字段
	ConfigurableBeanFactory beanFactory = getBeanFactory(enhancedConfigInstance);
	// 确定当前 @Bean 方法对应的 bean 名称
	String beanName = BeanAnnotationHelper.determineBeanNameFor(beanMethod);

	// 检查当前的 @Bean 方法是否定义了一个作用域代理
	if (BeanAnnotationHelper.isScopedProxy(beanMethod)) {
		String scopedBeanName = ScopedProxyCreator.getTargetBeanName(beanName);
		if (beanFactory.isCurrentlyInCreation(scopedBeanName)) {
			beanName = scopedBeanName;
		}
	}
    // FactoryBeans 在 Spring 中是特殊的 beans，它们不产生 bean 实例本身，而是产生其他 beans。
    // 此代码块处理了当 FactoryBean 被请求时的情况，
    // 确保返回的是 FactoryBean 创建的实际 bean，而不是 FactoryBean 本身。
	if (factoryContainsBean(beanFactory, BeanFactory.FACTORY_BEAN_PREFIX + beanName) &&
		factoryContainsBean(beanFactory, beanName)) {
		// 此部分代码省略，但它处理 FactoryBean 创建的 bean 的返回和增强
	}

	// 检查当前的方法是否是正在被工厂调用的工厂方法
	if (isCurrentlyInvokedFactoryMethod(beanMethod)) {
		// 如果是，直接调用方法的原始实现
		return cglibMethodProxy.invokeSuper(enhancedConfigInstance, beanMethodArgs);
	}

	// 尝试从 bean 工厂中解析并返回 bean 的引用
	return resolveBeanReference(beanMethod, beanMethodArgs, beanFactory, beanName);
}

private Object resolveBeanReference(Method beanMethod, Object[] beanMethodArgs,
				ConfigurableBeanFactory beanFactory, String beanName) {
    
    // 判断bean是否正在创建中
    boolean alreadyInCreation = beanFactory.isCurrentlyInCreation(beanName);
    try {
        // 如果bean正在创建中，暂时将其设置为不在创建中，以避免异常
        if (alreadyInCreation) {
            beanFactory.setCurrentlyInCreation(beanName, false);
        }
        boolean useArgs = !ObjectUtils.isEmpty(beanMethodArgs);
        // 对于单例的bean，如果bean方法的参数包含null，则可能预期它们会被自动装配
        if (useArgs && beanFactory.isSingleton(beanName)) {
            for (Object arg : beanMethodArgs) {
                if (arg == null) {
                    useArgs = false;
                    break;
                }
            }
        }
        // 根据上面的判断，从BeanFactory中获取bean实例
        Object beanInstance = (useArgs ? beanFactory.getBean(beanName, beanMethodArgs) :
                               beanFactory.getBean(beanName));
        // 检查获取的bean实例是否与@Bean方法的返回类型兼容
        if (!ClassUtils.isAssignableValue(beanMethod.getReturnType(), beanInstance)) {
            if (beanInstance.equals(null)) {
                // 如果返回了特定的NullBean实例，进行相应的处理
                // ... [日志输出代码]
                beanInstance = null;
            }
            else {
                // 抛出异常，说明有一个同名但类型不兼容的bean覆盖了当前的bean
                String msg = String.format("@Bean method %s.%s ...", 
                                           // ... [代码省略以简化]
                                           );
                throw new IllegalStateException(msg);
            }
        }
        // 如果当前正在调用另一个@Bean方法，处理其依赖关系
        Method currentlyInvoked = SimpleInstantiationStrategy.getCurrentlyInvokedFactoryMethod();
        if (currentlyInvoked != null) {
            String outerBeanName = BeanAnnotationHelper.determineBeanNameFor(currentlyInvoked);
            beanFactory.registerDependentBean(beanName, outerBeanName);
        }
        return beanInstance;
    }
    finally {
        // 清理阶段，恢复bean的创建状态
        if (alreadyInCreation) {
            beanFactory.setCurrentlyInCreation(beanName, true);
        }
    }
}