public interface BeanDefinitionRegistryPostProcessor extends BeanFactoryPostProcessor {
	/**
     * 允許開發(fā)者在Spring容器加載Bean定義(BeanDefinition)后，實(shí)例化Bean之前，動(dòng)態(tài)修改或注冊(cè)新的BeanDefinition
     * 該接口在框架內(nèi)部被廣泛用于添加特殊Bean，也可用于自定義擴(kuò)展
     * 核心作用：
     * 	1.動(dòng)態(tài)注冊(cè)BeanDefinition：可以在運(yùn)行時(shí)向容器中添加新的BeanDefinition，無需在配置文件中靜態(tài)聲明。
     * 	2.修改現(xiàn)有BeanDefinition：可以修改已注冊(cè)的BeanDefinition屬性（如作用域、懶加載等）
     * 	3.高級(jí)配置處理：在Bean實(shí)例化前完成復(fù)雜的配置解析或依賴處理
     * 執(zhí)行實(shí)際：
     * 	1.早于其他類型的BeanFactoryPostProcessor：Spring會(huì)先調(diào)用所有的BeanDefinitionRegistryPostProcessor，再調(diào)用其他類型的后處理器
     * 	2.在Bean實(shí)例化前：此時(shí)BeanDefinition已經(jīng)加載，但所有Bean都未進(jìn)行實(shí)例化
     */
    void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException;
}

@FunctionalInterface
public interface BeanFactoryPostProcessor {
    /**
     * Spring框架中的一個(gè)核心擴(kuò)展點(diǎn)，允許開發(fā)這在Bean定義加載完成后、Bean實(shí)例化之前修改Bean定義。
     * 主要作用：
     * 	1.動(dòng)態(tài)修改Bean定義：可以在運(yùn)行時(shí)調(diào)整Bean的屬性值、作用域、依賴關(guān)系等
     *  2.注冊(cè)新的Bean定義：通過BeanDefinitionRegistry接口添加新的Bean定義
     * 	3.替換或增強(qiáng)Bean定義：例如，使用自定義實(shí)現(xiàn)替換某些Bean的默認(rèn)配置
     *  4.環(huán)境變量處理：解析占位符、注入外部配置等
     *  5.框架擴(kuò)展：Spring內(nèi)部使用此機(jī)制實(shí)現(xiàn)了許多功能，如： PropertySourcesPlaceholderConfigurer 和 ConfigurationClassPostProcessor。
     * 工作原理：
     *  1.執(zhí)行時(shí)機(jī)：在所有Bean定義加載完成后，Bean實(shí)例化之前執(zhí)行。
     * 	2.順序控制：通過實(shí)現(xiàn)Ordered或PriorityOrdered接口控制執(zhí)行順序。
     * 	3.處理對(duì)象：執(zhí)行處理BeanDefinition，而非Bean實(shí)例。
     * 典型應(yīng)用場景：
     *  1.屬性占位符替換：動(dòng)態(tài)替換配置文件中的${}占位符
     *  2.條件性Bean注冊(cè)：根據(jù)環(huán)境變量決定是否注冊(cè)某些Bean
     * 	3.Bean定義增強(qiáng)：為特定Bean添加額外屬性或方法
     *  4.依賴注入調(diào)整：修改Bean之間的依賴注入關(guān)系
     */
    void postProcessBeanFactory(ConfigurableListableBeanFactory var1) throws BeansException;
}

public interface BeanPostProcessor {
    /**
     * 用在Bean初始化之前進(jìn)行自定義處理的關(guān)鍵方法
     * 允許開發(fā)者在Bean實(shí)例化并完成依賴注入后，調(diào)用初始化回調(diào)（如 InitializingBean.afterPropertiesSet() 或 @PostConstruct）之前，對(duì)Bean進(jìn)行額外處理。
     * 核心功能：
     * 	1.實(shí)例化后處理：在Bean實(shí)例化并填充屬性后執(zhí)行。
     *  2.自定義初始話：在Spring標(biāo)準(zhǔn)初始化回調(diào)前執(zhí)行自定義邏輯
     *  3.屬性增強(qiáng)：動(dòng)態(tài)修改Bean的屬性或狀態(tài)
     *  4.注解處理：解析自定義注解并應(yīng)用特定邏輯
     *  5.實(shí)例替換：返回一個(gè)完全不同的Bean實(shí)例（慎用）
     * 執(zhí)行時(shí)機(jī)：
     *  1.Bean聲明周期順序
     * 	   實(shí)例化 -> 屬性注入 -> postProcessBeforeInitialization -> 初始化回調(diào) -> postProcessAfterInitialization
     *     若處理器返回NULL，則Bean不會(huì)進(jìn)行后續(xù)生命周期處理，直接被跳過
     *  2.與其它回調(diào)的關(guān)系
     * 	   早于@PostConstruct、InitializingBean.afterPropertiesSet()和init-method。
     * 	   晚于@Autowired和@Resource等依賴注入注解的處理
     * 典型應(yīng)用場景：
     *	1.配置驗(yàn)證：初始話前驗(yàn)證Bean的必要屬性是否正確設(shè)置
     *  2.屬性預(yù)處理：轉(zhuǎn)換或加密敏感配置（如數(shù)據(jù)庫密碼）
     *  3.上下文注入：手動(dòng)注入無法通過依賴注入獲取的資源（如 ApplicationContext）
     *  4.注解解析：處理自定義初始化注解（如 @Init）
     *  5.性能監(jiān)控：記錄 Bean 初始化前的狀態(tài)。
     * 常見實(shí)現(xiàn)類
     *  AutowiredAnnotationBeanPostProcessor：處理@Autowired、@Value等依賴注入注解
     *  CommonAnnotationBeanPostProcessor：處理JSR-250注解，如@Resource、@PostConstruct
     *  AnnotationAwareAspectJAutoProxyCreator：為使用@Aspect注解的Bean創(chuàng)建AOP代理
     *  RequiredAnnotationBeanPostProcessor：檢查@Required注解的屬性是否已設(shè)置
     */
    @Nullable
    default Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
        return bean;
    }

  
  	/**
  	 * Bean初始化完成后進(jìn)行自定義處理 
  	 * 核心功能
  	 * 	1.初始化后處理：在Bean完成所有初始話回調(diào)（@PostConstruct、InitializingBean.afterPropertiesSet()和init-method）后執(zhí)行
  	 *  2.包裝實(shí)例：可以返回原始Bean或包裝對(duì)象（如代理對(duì)象）
  	 *  3.FactoryBean支持：同時(shí)作用于FactoryBean本身及其創(chuàng)建的對(duì)象
  	 *  4.短路處理：即使Bean創(chuàng)建過程中被InstantiationAwareBeanPostProcessor短路，此方法扔會(huì)被調(diào)用
     * 執(zhí)行時(shí)機(jī)： 
     *  1.Bean聲明周期順序
     * 	   實(shí)例化 -> 屬性注入 -> postProcessBeforeInitialization -> 初始化回調(diào) -> postProcessAfterInitialization
     *     若處理器返回NULL，則Bean不會(huì)進(jìn)行后續(xù)生命周期處理，直接被跳過
     *  2.與其它回調(diào)的關(guān)系
     * 	   晚于@PostConstruct、InitializingBean.afterPropertiesSet()和init-method。
     * 	   早于 DisposableBean.destroy() 或 @PreDestroy 等銷毀回調(diào)。
  	 * 典型應(yīng)用場景
  	 * 	1.AOP代理創(chuàng)建：AnnotationAwareAspectAutoProxyCreator通過此方法為Bean創(chuàng)建代理
  	 * 	2.Bean增強(qiáng)：添加額為的功能，如日志、事務(wù)、緩存
  	 *  3.自定義注解處理：處理運(yùn)行時(shí)注解，如@Cacheable、@Transactional
  	 *  4.資源注冊(cè)：將Bean注冊(cè)到全局管理器或上下文
  	 *  5.Bean驗(yàn)證：確保初始化后的Bean狀態(tài)合法
  	 * 常見實(shí)現(xiàn)類
  	 *  AnnotationAwareAspectJAutoProxyCreator：為使用@Aspect注解的Bean創(chuàng)建AOP代理
  	 *	ApplicationListenerDetector：檢測并注冊(cè) ApplicationListener 類型的 Bean。
		 *  MethodValidationPostProcessor：為方法參數(shù)添加 JSR-303 驗(yàn)證	
		 *  BeanValidationPostProcessor：對(duì) Bean 進(jìn)行 JSR-303 驗(yàn)證。
  	 */
    @Nullable
    default Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
        return bean;
    }
}

public interface InitializingBean {

	/**
	 * 用于在 Bean 的屬性設(shè)置完成后執(zhí)行初始化邏輯。
	 * 實(shí)現(xiàn)該接口的 Bean 需要實(shí)現(xiàn)其唯一的方法 afterPropertiesSet()，Spring 容器會(huì)在 Bean 的所有屬性都被設(shè)置后自動(dòng)調(diào)用這個(gè)方法
	 * 使用場景:
	 * 	1.自定義初始化邏輯：當(dāng) Bean 的屬性全部設(shè)置完成后，需要執(zhí)行額外的初始化操作（如資源初始化、數(shù)據(jù)加載等）。
	 *  2.參數(shù)校驗(yàn)：確保 Bean 的必要屬性已被正確設(shè)置，避免運(yùn)行時(shí)出現(xiàn) NullPointerException。
	 * 注意事項(xiàng):
	 * 	1.異常處理：afterPropertiesSet() 方法聲明了 throws Exception，因此可以拋出任何異常，但建議捕獲并處理非預(yù)期異常，避免影響容器啟動(dòng)。
	 *  2.依賴順序：確保 afterPropertiesSet() 中依賴的其他 Bean 已完成初始化（可通過 @DependsOn 注解控制依賴順序）。
	 *  3.性能考慮：避免在 afterPropertiesSet() 中執(zhí)行耗時(shí)操作，以免影響應(yīng)用啟動(dòng)速度。
	 */
	void afterPropertiesSet() throws Exception;
}

public class DubboContextPostProcessor
        implements BeanDefinitionRegistryPostProcessor, ApplicationContextAware, EnvironmentAware {

    /**
     * The bean name of {@link DubboConfigConfigurationRegistrar}
     */
    public static final String BEAN_NAME = "dubboContextPostProcessor";

    private ApplicationContext applicationContext;

    private ConfigurableEnvironment environment;

 		/**
     * 主要負(fù)責(zé)初始化核心模型、環(huán)境配置和注冊(cè)關(guān)鍵組件
     */
    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {

        // ApplicationModel：代表整個(gè)Dubbo應(yīng)用實(shí)例，是全局上下文的核心容器
        ApplicationModel applicationModel = DubboBeanUtils.getApplicationModel(beanFactory);
        // ModuleModel：代表應(yīng)用內(nèi)的模塊，支持多模塊隔離（Dubbo3.x新增特性）
        ModuleModel moduleModel = DubboBeanUtils.getModuleModel(beanFactory);

        // 初始化Spring擴(kuò)展注入器
        // SpringExtensionInjector：負(fù)責(zé)將Spring容器中的Bean注入到Dubbo擴(kuò)展點(diǎn)
        // 支持在Dubbo SPI組件中使用Spring管理的Bean，如自定義負(fù)載均衡引用的Spring Bean
        // 實(shí)現(xiàn)了Dubbo與Spring依賴注入體系的雙向打通
        SpringExtensionInjector.get(applicationModel).init(applicationContext);
        SpringExtensionInjector.get(moduleModel).init(applicationContext);
        DubboBeanUtils.getInitializationContext(beanFactory).setApplicationContext(applicationContext);

        // 環(huán)境配置與屬性提取
        // 從Spring Environment中提取以`dubbo.`為前綴的屬性
        // 將這些屬性放入Dubbo的 AppConfigMap ，作為應(yīng)用級(jí)配置
        // 支持配置的優(yōu)先級(jí)：外部配置 > 注解 > XML > 默認(rèn)值
        SortedMap<String, String> dubboProperties = EnvironmentUtils.filterDubboProperties(environment);
        applicationModel.getModelEnvironment().getAppConfigMap().putAll(dubboProperties);

        // 注冊(cè) ConfigManager 單例
        // ConfigManager：Dubbo3.x的配置管理中心，統(tǒng)一管理各類配置源
        // 將其注冊(cè)為 Spring 單例Bean，確保全局唯一性
        // 負(fù)責(zé)配置的聚合、校驗(yàn)和動(dòng)態(tài)刷新
        beanFactory.registerSingleton(ConfigManager.BEAN_NAME, applicationModel.getApplicationConfigManager());
    }

   /**
  	* 在 Spring 容器加載完所有 Bean 定義但尚未實(shí)例化任何 Bean 之前被調(diào)用，主要用于動(dòng)態(tài)注冊(cè)或修改 Dubbo 相關(guān)的 Bean 定義
  	*/
    @Override
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry beanDefinitionRegistry) throws BeansException {
        // Dubbo 3.3.0 與 Spring 集成的核心初始化方法，負(fù)責(zé)在 Spring 應(yīng)用啟動(dòng)時(shí)注冊(cè) Dubbo 基礎(chǔ)設(shè)施組件
        DubboSpringInitializer.initialize(beanDefinitionRegistry);
    }

    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        this.applicationContext = applicationContext;
    }

    @Override
    public void setEnvironment(Environment environment) {
        this.environment = (ConfigurableEnvironment) environment;
    }
}

/**
 * Dubbo spring initialization entry point
 */
public class DubboSpringInitializer {

    private static final Logger logger = LoggerFactory.getLogger(DubboSpringInitializer.class);

    private static final Map<BeanDefinitionRegistry, DubboSpringInitContext> REGISTRY_CONTEXT_MAP =
            new ConcurrentHashMap<>();

    public DubboSpringInitializer() {}

    public static void initialize(BeanDefinitionRegistry registry) {

        // Apache Dubbo框架與Spring整合時(shí)的核心上下文類。
        // 主要用于Spring容器啟動(dòng)過程中初始話Dubbo服務(wù)的相關(guān)配置，實(shí)現(xiàn)服務(wù)的注冊(cè)與發(fā)現(xiàn)、消費(fèi)端引用等功能。
        // 1.配置解析與注冊(cè)
        // 1.1.解析Spring配置文件中Dubbo相關(guān)標(biāo)簽（如"<dubbo:service>"、"<dubbo:reference>"等）的屬性，并將其轉(zhuǎn)換為Dubbo內(nèi)部可識(shí)別的對(duì)象。
        // 1.2.向注冊(cè)中心（如zookeeper）注冊(cè)服務(wù)提供者的接口信息，或?yàn)橄M(fèi)者獲取服務(wù)地址
        // 2.生命周期管理
        // 2.1.在Spring容器啟動(dòng)時(shí)（ContextRefreshedEvent事件），啟動(dòng)Dubbo服務(wù)或建立客戶端連接
        // 2.2.在容器關(guān)閉時(shí)（ContextClosedEvent），優(yōu)雅關(guān)閉Dubbo服務(wù)，釋放資源。
        // 3.整合Spring生態(tài)
        // 3.1.通過實(shí)現(xiàn)Spring的ApplicationContextAware接口，獲取Spring容器上下文，實(shí)現(xiàn)與SpringBean的依賴注入
        DubboSpringInitContext context = new DubboSpringInitContext();

        // 添加上下文到緩存中
        // 如果已經(jīng)存在過，直接返回，不再進(jìn)行初始化。
        if (REGISTRY_CONTEXT_MAP.putIfAbsent(registry, context) != null) {
            return;
        }

        // 獲取beanFactory
        ConfigurableListableBeanFactory beanFactory = findBeanFactory(registry);

        // 初始話化上下文
        initContext(context, registry, beanFactory);
    }

    public static boolean remove(BeanDefinitionRegistry registry) {
        return REGISTRY_CONTEXT_MAP.remove(registry) != null;
    }

    public static boolean remove(ApplicationContext springContext) {
        AutowireCapableBeanFactory autowireCapableBeanFactory = springContext.getAutowireCapableBeanFactory();
        for (Map.Entry<BeanDefinitionRegistry, DubboSpringInitContext> entry : REGISTRY_CONTEXT_MAP.entrySet()) {
            DubboSpringInitContext initContext = entry.getValue();
            if (initContext.getApplicationContext() == springContext
                    || initContext.getBeanFactory() == autowireCapableBeanFactory
                    || initContext.getRegistry() == autowireCapableBeanFactory) {
                DubboSpringInitContext context = REGISTRY_CONTEXT_MAP.remove(entry.getKey());
                logger.info("Unbind " + safeGetModelDesc(context.getModuleModel()) + " from spring container: "
                        + ObjectUtils.identityToString(entry.getKey()));
                return true;
            }
        }
        return false;
    }

    static Map<BeanDefinitionRegistry, DubboSpringInitContext> getContextMap() {
        return REGISTRY_CONTEXT_MAP;
    }

    static DubboSpringInitContext findBySpringContext(ApplicationContext applicationContext) {
        for (DubboSpringInitContext initContext : REGISTRY_CONTEXT_MAP.values()) {
            if (initContext.getApplicationContext() == applicationContext) {
                return initContext;
            }
        }
        return null;
    }

    /**
     *
     * @param context Apache Dubbo框架與Spring整合時(shí)的核心上下文類。
     * @param registry
     *      1.存儲(chǔ) BeanDefinition：將解析后的 Bean 定義（如 XML 配置、注解掃描結(jié)果）注冊(cè)到內(nèi)存中的注冊(cè)表。
     *      2.動(dòng)態(tài)注冊(cè) Bean：允許在運(yùn)行時(shí)動(dòng)態(tài)添加或刪除 BeanDefinition，為框架擴(kuò)展提供支持。
     *      3.統(tǒng)一接口：屏蔽不同容器實(shí)現(xiàn)（如 DefaultListableBeanFactory、GenericApplicationContext）的差異。
     * @param beanFactory
     */
    private static void initContext(
            DubboSpringInitContext context,
            BeanDefinitionRegistry registry,
            ConfigurableListableBeanFactory beanFactory) {
        context.setRegistry(registry);
        context.setBeanFactory(beanFactory);

        // 通過兩種方式加載和執(zhí)行擴(kuò)展點(diǎn)(DubboSpringInitCustomizer、DubboSpringInitCustomizerHolder)，允許用戶或框架內(nèi)部組件在初始化階段介入并修改 Dubbo 的行為
        customize(context);

        // 初始化 ModuleModel
        // Apache Dubbo 框架中的核心抽象，用于表示一個(gè)應(yīng)用內(nèi)的獨(dú)立業(yè)務(wù)模塊。在 Dubbo 的多模塊架構(gòu)中，它提供了對(duì)服務(wù)定義、配置和生命周期的統(tǒng)一管理。
        ModuleModel moduleModel = context.getModuleModel();
        if (moduleModel == null) {
            ApplicationModel applicationModel;
            if (findContextForApplication(ApplicationModel.defaultModel()) == null) {
                // first spring context use default application instance
                applicationModel = ApplicationModel.defaultModel();
                logger.info("Use default application: " + applicationModel.getDesc());
            } else {
                // create a new application instance for later spring context
                applicationModel = FrameworkModel.defaultModel().newApplication();
                logger.info("Create new application: " + applicationModel.getDesc());
            }

            // init ModuleModel
            moduleModel = applicationModel.getDefaultModule();
            context.setModuleModel(moduleModel);
            logger.info("Use default module model of target application: " + moduleModel.getDesc());
        } else {
            logger.info("Use module model from customizer: " + moduleModel.getDesc());
        }
        logger.info(
                "Bind " + moduleModel.getDesc() + " to spring container: " + ObjectUtils.identityToString(registry));

        // 將上下文（context）中的模塊屬性傳遞給 ModuleModel 對(duì)象
        Map<String, Object> moduleAttributes = context.getModuleAttributes();
        if (moduleAttributes.size() > 0) {
            moduleModel.getAttributes().putAll(moduleAttributes);
        }

        // 將 Dubbo 的上下文對(duì)象注冊(cè)為 Spring 容器中的單例 Bean
        //  1.DubboSpringInitContext：Dubbo 與 Spring 集成的初始化上下文
        //  2.ApplicationModel：Dubbo 應(yīng)用模型，代表整個(gè)應(yīng)用
        //  3.ModuleModel：Dubbo 模塊模型，代表應(yīng)用中的一個(gè)業(yè)務(wù)模塊
        registerContextBeans(beanFactory, context);

        // 將 DubboSpringInitContext 標(biāo)記為已與當(dāng)前執(zhí)行環(huán)境綁定
        // 通常用于防止上下文被重復(fù)綁定或確保在特定生命周期階段后不能修改
        context.markAsBound();
        // 將 ModuleModel 的生命周期控制權(quán)移交給外部系統(tǒng)（如 Spring 容器）
        // 意味著該模塊的初始化、啟動(dòng)、銷毀將由外部框架而非 Dubbo 內(nèi)部機(jī)制管理
        moduleModel.setLifeCycleManagedExternally(true);

        // 檢測當(dāng)前是否處于 AOT（ Ahead-of-Time 編譯）模式
        if (!AotWithSpringDetector.useGeneratedArtifacts()) {
            // 如果不使用 AOT 生成的工件（即傳統(tǒng)的 JIT 運(yùn)行時(shí)），則執(zhí)行注冊(cè)邏輯
            // ServicePackagesHolder
            // DubboContextPostProcessor
            // ReferenceBeanManager
            // ReferenceAnnotationWithAotBeanPostProcessor
            // DubboConfigAliasPostProcessor
            // DubboDeployApplicationListener
            // DubboConfigApplicationListener
            // DubboConfigDefaultPropertyValueBeanPostProcessor
            // DubboConfigBeanInitializer
            // DubboInfraBeanRegisterPostProcessor
            DubboBeanUtils.registerCommonBeans(registry);
        }
    }

    private static String safeGetModelDesc(ScopeModel scopeModel) {
        return scopeModel != null ? scopeModel.getDesc() : null;
    }

    private static ConfigurableListableBeanFactory findBeanFactory(BeanDefinitionRegistry registry) {
        ConfigurableListableBeanFactory beanFactory;
        if (registry instanceof ConfigurableListableBeanFactory) {
            beanFactory = (ConfigurableListableBeanFactory) registry;
        } else if (registry instanceof GenericApplicationContext) {
            GenericApplicationContext genericApplicationContext = (GenericApplicationContext) registry;
            beanFactory = genericApplicationContext.getBeanFactory();
        } else {
            throw new IllegalStateException("Can not find Spring BeanFactory from registry: "
                    + registry.getClass().getName());
        }
        return beanFactory;
    }

    private static void registerContextBeans(
            ConfigurableListableBeanFactory beanFactory, DubboSpringInitContext context) {
        // register singleton
        if (!beanFactory.containsSingleton(DubboSpringInitContext.class.getName())) {
            registerSingleton(beanFactory, context);
        }
        if (!beanFactory.containsSingleton(
                context.getApplicationModel().getClass().getName())) {
            registerSingleton(beanFactory, context.getApplicationModel());
        }
        if (!beanFactory.containsSingleton(context.getModuleModel().getClass().getName())) {
            registerSingleton(beanFactory, context.getModuleModel());
        }
    }

    private static void registerSingleton(ConfigurableListableBeanFactory beanFactory, Object bean) {
        beanFactory.registerSingleton(bean.getClass().getName(), bean);
    }

    private static DubboSpringInitContext findContextForApplication(ApplicationModel applicationModel) {
        for (DubboSpringInitContext initializationContext : REGISTRY_CONTEXT_MAP.values()) {
            if (initializationContext.getApplicationModel() == applicationModel) {
                return initializationContext;
            }
        }
        return null;
    }

    /**
     * 通過兩種方式加載和執(zhí)行擴(kuò)展點(diǎn)(DubboSpringInitCustomizer、DubboSpringInitCustomizerHolder)，允許用戶或框架內(nèi)部組件在初始化階段介入并修改 Dubbo 的行為 <br/>
     *
     * <p>DubboSpringInitCustomizer</p>
     * Dubbo 3.3.0 版本引入的擴(kuò)展點(diǎn)接口，用于在 Dubbo 與 Spring 集成的初始化階段，
     * 允許開發(fā)者或框架內(nèi)部組件動(dòng)態(tài)修改配置、注冊(cè) Bean 或執(zhí)行自定義邏輯。
     * <p>該接口類似于 Spring 的 BeanFactoryPostProcessor，在 BeanDefinition 加載完成后、
     * Bean 實(shí)例化前執(zhí)行，可用于實(shí)現(xiàn)以下功能：</p>
     * <ul>
     *   <li>動(dòng)態(tài)配置：在 Dubbo 服務(wù)導(dǎo)出和引用前，修改其配置參數(shù)</li>
     *   <li>組件注冊(cè)：向 Spring 容器動(dòng)態(tài)注冊(cè)自定義 Bean 或修改現(xiàn)有 Bean</li>
     *   <li>條件初始化：根據(jù)環(huán)境變量或運(yùn)行時(shí)條件，決定是否啟用某些功能</li>
     *   <li>集成第三方框架：無縫對(duì)接其他框架（如 Spring Cloud、Kubernetes）</li>
     * </ul>
     * <p>執(zhí)行時(shí)機(jī)：</p>
     * <ol>
     *   <li>在 Spring 容器加載 BeanDefinition 后，實(shí)例化 Bean 前執(zhí)行</li>
     *   <li>早于 @Service、@Reference 注解的處理</li>
     *   <li>按 SPI 優(yōu)先級(jí)順序執(zhí)行多個(gè)自定義器</li>
     * </ol>
     *
     * <p>DubboSpringInitCustomizerHolder</p>
     * Dubbo 3.3.0 提供的線程本地工具類，用于在運(yùn)行時(shí)動(dòng)態(tài)注冊(cè) DubboSpringInitCustomizer。
     * 解決了 SPI 擴(kuò)展機(jī)制的局限性，允許開發(fā)者在不修改配置文件的情況下，臨時(shí)注入自定義初始化邏輯。
     * <p>核心作用：</p>
     * <ul>
     *   <li>動(dòng)態(tài)注冊(cè)自定義器：在程序運(yùn)行時(shí)添加 DubboSpringInitCustomizer 實(shí)現(xiàn)</li>
     *   <li>線程隔離：確保自定義器僅在當(dāng)前線程的 Dubbo 初始化過程中生效</li>
     *   <li>臨時(shí)擴(kuò)展：避免修改全局 SPI 配置，適用于測試或條件性擴(kuò)展</li>
     * </ul>
     * <p>使用場景：</p>
     * <ul>
     *   <li>測試環(huán)境：在單元測試或集成測試中臨時(shí)修改 Dubbo 配置</li>
     *   <li>條件性擴(kuò)展：根據(jù)運(yùn)行時(shí)條件決定是否啟用某些功能</li>
     *   <li>動(dòng)態(tài)修改配置：在不重啟應(yīng)用的情況下調(diào)整 Dubbo 參數(shù)</li>
     * </ul>
     */
    private static void customize(DubboSpringInitContext context) {

        // find initialization customizers
        Set<DubboSpringInitCustomizer> customizers = FrameworkModel.defaultModel()
                .getExtensionLoader(DubboSpringInitCustomizer.class)
                .getSupportedExtensionInstances();
        for (DubboSpringInitCustomizer customizer : customizers) {
            customizer.customize(context);
        }

        // load customizers in thread local holder
        DubboSpringInitCustomizerHolder customizerHolder = DubboSpringInitCustomizerHolder.get();
        customizers = customizerHolder.getCustomizers();
        for (DubboSpringInitCustomizer customizer : customizers) {
            customizer.customize(context);
        }
        customizerHolder.clearCustomizers();
    }
}

/**
 * Dubbo框架中用于處理配置別名的后置處理器
 * 通過實(shí)現(xiàn)BeanPostProcessor接口，在Bean初始化完成后對(duì)特定配置Bean進(jìn)行處理，建立不同配置Bean之間的別名機(jī)制
 * 這個(gè)機(jī)制允許用戶以更靈活的方式引用和復(fù)用配置
 */
public class DubboConfigAliasPostProcessor implements BeanDefinitionRegistryPostProcessor, BeanPostProcessor {

    /**
     * The bean name of {@link DubboConfigConfigurationRegistrar}
     */
    public static final String BEAN_NAME = "dubboConfigAliasPostProcessor";

    private BeanDefinitionRegistry registry;

    @Override
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {
        this.registry = registry;
    }

    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
        // DO NOTHING
    }

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
        // DO NOTHING
        return bean;
    }

    /**
     * Dubbo 框架中用于處理配置 Bean 別名注冊(cè)的核心邏輯。
     * 在 Bean 初始化完成后檢查其是否為 Dubbo 配置 Bean（即 AbstractConfig 的子類），并為其注冊(cè)別名。這個(gè)機(jī)制允許用戶通過配置文件中的 id 屬性更方便地引用這些配置。
     */
    @Override
    public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
        // 只處理類型為 AbstractConfig 的Bean（Dubbo配置Bean的基類）
        if (bean instanceof AbstractConfig) {
            String id = ((AbstractConfig) bean).getId();
            if (hasText(id) // id必須存在
                    && !nullSafeEquals(id, beanName) // id和BeanName不同
                    && !BeanRegistrar.hasAlias(registry, beanName, id)) { // id不能已經(jīng)是別名
                // 將 id 注冊(cè)為 Bean 別名
                registry.registerAlias(beanName, id);
            }
        }
        return bean;
    }
}

/**
 * 確保關(guān)鍵組件在正確的時(shí)機(jī)被注冊(cè)和初始化，特別是處理Dubbo的服務(wù)引用注解（如@Reference）和屬性占位符解析
 *
 * 核心功能與設(shè)計(jì)目的
 * 1.提前注冊(cè)ReferenceAnnotationBeanPostProcessor
 *   1.1.確保@Reference注解能在屬性占位符解析前被處理
 *   1.2.支持早期初始化的Reference（例如在配置類中被依賴的引用）
 * 2.確保PropertySourcesPlaceholderConfigurer存在
 *   2.1.確保Dubbo中的占位符（如${dubbo.registry.address}）能被正常解析
 * 3.自身生命周期管理
 *   3.1.處理完成后從注冊(cè)表中移除自身，避免不必要的Bean實(shí)例化
 */
public class DubboInfraBeanRegisterPostProcessor implements BeanDefinitionRegistryPostProcessor {

    /**
     * The bean name of {@link ReferenceAnnotationBeanPostProcessor}
     */
    public static final String BEAN_NAME = "dubboInfraBeanRegisterPostProcessor";

    private BeanDefinitionRegistry registry;

    @Override
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {
        // 保存BeanDefinitionRegistry引用，用于后續(xù)的Bean定義注冊(cè)操作
        this.registry = registry;
    }

    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {

        // 處理 Spring 3.2.x 兼容性問題
        if (registry != null) {
            // 提前注冊(cè) ReferenceAnnotationBeanPostProcessor
            ReferenceAnnotationBeanPostProcessor referenceAnnotationBeanPostProcessor = beanFactory.getBean(
                    ReferenceAnnotationBeanPostProcessor.BEAN_NAME, ReferenceAnnotationBeanPostProcessor.class);
            beanFactory.addBeanPostProcessor(referenceAnnotationBeanPostProcessor);

            // PropertySourcesPlaceholderConfigurer 未注冊(cè)的情況下，注冊(cè)到 BeanFactory 中
            DubboBeanUtils.registerPlaceholderConfigurerBeanIfNotExists(beanFactory, registry);
        }

        // 移除自定 Bean 定義，避免實(shí)例化
        if (registry != null) {
            registry.removeBeanDefinition(BEAN_NAME);
        }
    }
}

/**
 * Dubbo框架中處理服務(wù)注解的核心組件，實(shí)現(xiàn)了多個(gè)Spring接口，能在Bean定義注冊(cè)階段掃描并處理帶有Dubbo服務(wù)注解（如@Service、@DubboService）的類，將其轉(zhuǎn)換為Dubbo的ServiceBean，并注冊(cè)到Springring器中。
 *
 * 核心功能
 *  1.注冊(cè)多種服務(wù)注解：同時(shí)支持@Service、@DubboService等多種注解
 *  2.包掃描與類檢測：掃描指定包下帶有服務(wù)注解的類
 *  3.服務(wù)定義生成：將注解類轉(zhuǎn)換為ServiceBean定義
 *  4.注解服務(wù)Bean：將生成的ServiceBean注冊(cè)到Spring容器
 *  5.注解屬性處理：解析注解屬性并映射到ServiceBean的配置
 */
public class ServiceAnnotationPostProcessor
        implements BeanDefinitionRegistryPostProcessor,
                EnvironmentAware,
                ResourceLoaderAware,
                BeanClassLoaderAware,
                ApplicationContextAware,
                InitializingBean {

    public static final String BEAN_NAME = "dubboServiceAnnotationPostProcessor";

    /**
     * 要掃描的Dubbo服務(wù)注解
     */
    private static final List<Class<? extends Annotation>> serviceAnnotationTypes = loadServiceAnnotationTypes();

    /**
     * 獲取要處理的Dubbo服務(wù)類注解標(biāo)識(shí)
     * @return
     */
    private static List<Class<? extends Annotation>> loadServiceAnnotationTypes() {
        // 是否啟用Dubbo2的兼容模式              是否已經(jīng)加載了服務(wù)類（存在注解com.alibaba.dubbo.config.annotation.Service）
        if (Dubbo2CompactUtils.isEnabled() && Dubbo2CompactUtils.isServiceClassLoaded()) {
            // 掃描org.apache.dubbo.config.annotation.DubboService、org.apache.dubbo.config.annotation.Service、com.alibaba.dubbo.config.annotation.Service三個(gè)注解標(biāo)識(shí)的類
            return asList(
                    // @since 2.7.7 Add the @DubboService , the issue : https://github.com/apache/dubbo/issues/6007
                    DubboService.class,
                    // @since 2.7.0 the substitute @com.alibaba.dubbo.config.annotation.Service
                    Service.class,
                    // @since 2.7.3 Add the compatibility for legacy Dubbo's @Service , the issue :
                    // https://github.com/apache/dubbo/issues/4330
                    Dubbo2CompactUtils.getServiceClass());
        } else {
            // 掃描org.apache.dubbo.config.annotation.DubboService、org.apache.dubbo.config.annotation.Service注解標(biāo)識(shí)的類
            return asList(
                    // @since 2.7.7 Add the @DubboService , the issue : https://github.com/apache/dubbo/issues/6007
                    DubboService.class,
                    // @since 2.7.0 the substitute @com.alibaba.dubbo.config.annotation.Service
                    Service.class);
        }
    }

    private final ErrorTypeAwareLogger logger = LoggerFactory.getErrorTypeAwareLogger(getClass());

    /**
     * 要掃描的包
     */
    protected final Set<String> packagesToScan;

    /**
     * 存儲(chǔ)已解析的需要掃描的包路徑集合
     */
    private Set<String> resolvedPackagesToScan;

    /**
     * 用于獲取應(yīng)用程序的配置屬性和運(yùn)行環(huán)境信息
     * 1.解析占位符（如 ${dubbo.application.name}）
     * 2.獲取環(huán)境變量和系統(tǒng)屬性
     * 3.條件判斷（如判斷是否為生產(chǎn)環(huán)境）
     */
    private Environment environment;

    /**
     * 資源加載器接口，用于定位和加載應(yīng)用程序中的資源（如類路徑下的文件、URL 資源等）。
     * 在 Dubbo 服務(wù)掃描過程中，它主要用于查找和加載指定包路徑下的類文件，以便識(shí)別帶有 @DubboService 或 @Service 注解的服務(wù)類
     */
    private ResourceLoader resourceLoader;

    /**
     * classLoader 是 Dubbo 實(shí)現(xiàn)動(dòng)態(tài)類加載和服務(wù)發(fā)現(xiàn)的基礎(chǔ)組件，通過與 Spring 框架的集成，Dubbo 能夠:
     * 1.掃描并加載指定包路徑下的服務(wù)類
     * 2.解析注解中的類引用
     * 3.支持復(fù)雜類加載環(huán)境（如微服務(wù)、容器化部署）
     */
    private ClassLoader classLoader;

    /**
     * 在 Dubbo 服務(wù)掃描和注冊(cè)過程中，registry是核心組件，負(fù)責(zé)將掃描到的服務(wù)類轉(zhuǎn)換為 Bean 定義并注冊(cè)到 Spring 容器中。
     * 1.注冊(cè) Bean 定義（registerBeanDefinition(String beanName, BeanDefinition beanDefinition)）
     * 2.獲取 Bean 定義（getBeanDefinition(String beanName)）
     * 3.檢查 Bean 是否存在（containsBeanDefinition(String beanName)）
     */
    private BeanDefinitionRegistry registry;

    /**
     * 用于跟蹤和管理已掃描包及服務(wù)類的輔助組件。它確保 Dubbo 服務(wù)掃描過程中不會(huì)重復(fù)處理相同的包或類，并提供服務(wù)類的元數(shù)據(jù)緩存，提升性能
     * 1.記錄已掃描的包路徑，避免重復(fù)掃描
     * 2.記錄已注冊(cè)的服務(wù)類，確保服務(wù)唯一性
     * 3.提供包路徑和類名的緩存機(jī)制
     */
    protected ServicePackagesHolder servicePackagesHolder;

    /**
     * 標(biāo)識(shí)服務(wù)掃描是否已完成的標(biāo)志位
     * 確保在 Spring 容器的生命周期中，服務(wù)掃描邏輯僅執(zhí)行一次，避免重復(fù)掃描和注冊(cè)服務(wù) Bean。
     */
    private volatile boolean scanned = false;

    public ServiceAnnotationPostProcessor(String... packagesToScan) {
        this(asList(packagesToScan));
    }

    public ServiceAnnotationPostProcessor(Collection<?> packagesToScan) {
        this.packagesToScan = (Set<String>) packagesToScan.stream().collect(Collectors.toSet());
    }

    @Override
    public void afterPropertiesSet() throws Exception {
        // 處理用戶配置的包路徑，解析其中的占位符（如${dubbo.scan.base-packages}），并返回標(biāo)準(zhǔn)化的包路徑集合
        this.resolvedPackagesToScan = resolvePackagesToScan(packagesToScan);
    }

    @Override
    public void postProcessBeanDefinitionRegistry(BeanDefinitionRegistry registry) throws BeansException {
        // 保存BeanDefinitionRegistry引用，用于后續(xù)的Bean定義注冊(cè)操作
        this.registry = registry;
        // 掃描dubbo組件
        scanServiceBeans(resolvedPackagesToScan, registry);
    }

    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
        if (this.registry == null) {
            // 兼容Spring3.x的處理
            this.registry = (BeanDefinitionRegistry) beanFactory;
        }

        // 獲取所有Spring中配置的BeanDefinition名稱
        String[] beanNames = beanFactory.getBeanDefinitionNames();
        for (String beanName : beanNames) {
            // 獲取已經(jīng)加載的BeanDefinition
            BeanDefinition beanDefinition = beanFactory.getBeanDefinition(beanName);
            // 獲取BeanDefinition中dubbo服務(wù)類注解的配置
            Map<String, Object> annotationAttributes = getServiceAnnotationAttributes(beanDefinition);
            // 如果存在dubbo服務(wù)類注解，
            if (annotationAttributes != null) {
                // process @DubboService at java-config @bean method
                processAnnotatedBeanDefinition(
                        beanName, (AnnotatedBeanDefinition) beanDefinition, annotationAttributes);
            }
        }

        if (!scanned) {
            //兼容Spring 3.0未調(diào)用postProcessBeanDefinitionRegistry方法進(jìn)行服務(wù)掃描的情況
            scanServiceBeans(resolvedPackagesToScan, registry);
        }
    }

    /**
     * Dubbo用于掃描和注冊(cè)服務(wù)Bean的核心邏輯。它通過指定包路徑掃描帶有Dubbo服務(wù)注解的類，并將這些類注冊(cè)為SpringBean
     */
    private void scanServiceBeans(Set<String> packagesToScan, BeanDefinitionRegistry registry) {

        // 標(biāo)識(shí)為已掃描
        scanned = true;
        // 檢查掃描包是否為空
        if (CollectionUtils.isEmpty(packagesToScan)) {
            if (logger.isWarnEnabled()) {
                logger.warn(
                        CONFIG_NO_BEANS_SCANNED,
                        "",
                        "",
                        "packagesToScan is empty , ServiceBean registry will be ignored!");
            }
            return;
        }

        // 創(chuàng)建自定義 BeanDefinitionScanner ，用于掃描 Dubbo 服務(wù)注解
        DubboClassPathBeanDefinitionScanner scanner =
                new DubboClassPathBeanDefinitionScanner(registry, environment, resourceLoader);

        // 設(shè)置 Bean 名稱生成器
        BeanNameGenerator beanNameGenerator = resolveBeanNameGenerator(registry);
        scanner.setBeanNameGenerator(beanNameGenerator);

        // 添加包含過濾器，只掃描帶有 Dubbo 服務(wù)注解的類
        for (Class<? extends Annotation> annotationType : serviceAnnotationTypes) {
            scanner.addIncludeFilter(new AnnotationTypeFilter(annotationType));
        }

        // 添加排除過濾器，排除不需要的類
        ScanExcludeFilter scanExcludeFilter = new ScanExcludeFilter();
        scanner.addExcludeFilter(scanExcludeFilter);

        // 遍歷每個(gè)掃描包
        for (String packageToScan : packagesToScan) {

            // 跳過已掃描的類
            if (servicePackagesHolder.isPackageScanned(packageToScan)) {
                if (logger.isInfoEnabled()) {
                    logger.info("Ignore package who has already bean scanned: " + packageToScan);
                }
                continue;
            }

            // AOT 模式下的特殊處理
            if (AotWithSpringDetector.useGeneratedArtifacts()) {
                scanner.setIncludeAnnotationConfig(false);
            }
            // 執(zhí)行包掃描
            scanner.scan(packageToScan);

            // 查找掃描到的 Bean 定義
            Set<BeanDefinitionHolder> beanDefinitionHolders =
                    findServiceBeanDefinitionHolders(scanner, packageToScan, registry, beanNameGenerator);

            // 處理掃描到的 Bean 定義
            if (!CollectionUtils.isEmpty(beanDefinitionHolders)) {
                if (logger.isInfoEnabled()) {
                    // 日志記錄找到的服務(wù)類
                    List<String> serviceClasses = new ArrayList<>(beanDefinitionHolders.size());
                    for (BeanDefinitionHolder beanDefinitionHolder : beanDefinitionHolders) {
                        serviceClasses.add(
                                beanDefinitionHolder.getBeanDefinition().getBeanClassName());
                    }
                    logger.info("Found " + beanDefinitionHolders.size()
                            + " classes annotated by Dubbo @Service under package [" + packageToScan + "]: "
                            + serviceClasses);
                }

                // 處理每個(gè)服務(wù) Bean 定義
                for (BeanDefinitionHolder beanDefinitionHolder : beanDefinitionHolders) {
                    processScannedBeanDefinition(beanDefinitionHolder);
                    servicePackagesHolder.addScannedClass(
                            beanDefinitionHolder.getBeanDefinition().getBeanClassName());
                }
            } else {
                // 未找到服務(wù)注解類是的警告
                if (logger.isWarnEnabled()) {
                    logger.warn(
                            CONFIG_NO_ANNOTATIONS_FOUND,
                            "No annotations were found on the class",
                            "",
                            "No class annotated by Dubbo @DubboService or @Service was found under package ["
                                    + packageToScan + "], ignore re-scanned classes: "
                                    + scanExcludeFilter.getExcludedCount());
                }
            }

            servicePackagesHolder.addScannedPackage(packageToScan);
        }
    }

    /**
     * 用于解析和獲取 Spring Bean 名稱生成器的邏輯。
     * 它的主要功能是從 Spring 容器中查找已注冊(cè)的BeanNameGenerator，如果找不到則創(chuàng)建一個(gè)默認(rèn)實(shí)例
     *
     */
    private BeanNameGenerator resolveBeanNameGenerator(BeanDefinitionRegistry registry) {

        BeanNameGenerator beanNameGenerator = null;

        // 嘗試從容器中獲取已注冊(cè)的BeanNameGenerator
        if (registry instanceof SingletonBeanRegistry) {
            SingletonBeanRegistry singletonBeanRegistry = SingletonBeanRegistry.class.cast(registry);
            beanNameGenerator =
                    (BeanNameGenerator) singletonBeanRegistry.getSingleton(CONFIGURATION_BEAN_NAME_GENERATOR);
        }

        // 如果未找到自定義生成器，則創(chuàng)建默認(rèn)實(shí)例
        if (beanNameGenerator == null) {
            if (logger.isInfoEnabled()) {
                logger.info("BeanNameGenerator bean can't be found in BeanFactory with name ["
                        + CONFIGURATION_BEAN_NAME_GENERATOR + "]");
                logger.info("BeanNameGenerator will be a instance of " + AnnotationBeanNameGenerator.class.getName()
                        + " , it maybe a potential problem on bean name generation.");
            }
            beanNameGenerator = new AnnotationBeanNameGenerator();
        }

        return beanNameGenerator;
    }

    /**
     * 用于查找和收集指定包路徑下服務(wù) Bean 定義的核心邏輯。
     * 它的主要功能是掃描包路徑，識(shí)別帶有服務(wù)注解的類，并將其轉(zhuǎn)換為BeanDefinitionHolder對(duì)象集合
     *
     */
    private Set<BeanDefinitionHolder> findServiceBeanDefinitionHolders(
            ClassPathBeanDefinitionScanner scanner,
            String packageToScan,
            BeanDefinitionRegistry registry,
            BeanNameGenerator beanNameGenerator) {

        // 1. 使用掃描器查找候選組件（帶有服務(wù)注解的類）
        Set<BeanDefinition> beanDefinitions = scanner.findCandidateComponents(packageToScan);

        // 2. 創(chuàng)建有序集合，用于存儲(chǔ)Bean定義持有者
        Set<BeanDefinitionHolder> beanDefinitionHolders = new LinkedHashSet<>(beanDefinitions.size());

        // 3. 遍歷所有候選組件，生成Bean名稱并封裝為持有者
        for (BeanDefinition beanDefinition : beanDefinitions) {

            // 生成唯一的Bean名稱
            String beanName = beanNameGenerator.generateBeanName(beanDefinition, registry);
            // 創(chuàng)建Bean定義持有者（包含Bean定義和名稱）
            BeanDefinitionHolder beanDefinitionHolder = new BeanDefinitionHolder(beanDefinition, beanName);
            // 添加到結(jié)果集合
            beanDefinitionHolders.add(beanDefinitionHolder);
        }

        return beanDefinitionHolders;
    }

    /**
     * 這個(gè)方法處理通過包掃描發(fā)現(xiàn)的服務(wù)類（帶有@DubboService或@Service注解的類），將其轉(zhuǎn)換為 Dubbo 服務(wù) Bean 并注冊(cè)到 Spring 容器中
     *
     * 1.解析服務(wù)類：
     *      從BeanDefinitionHolder中獲取并解析服務(wù)類的Class對(duì)象。
     * 2.查找服務(wù)注解：
     *      通過findServiceAnnotation方法查找類上的服務(wù)注解（如@DubboService或@Service）。
     * 3.提取注解屬性：
     *      使用 Spring 的AnnotationUtils提取注解中的配置屬性（如group、version、timeout等）。
     * 4.確定服務(wù)接口：
     *      通過resolveInterfaceName方法確定服務(wù)實(shí)現(xiàn)的接口名稱。優(yōu)先使用注解中顯式指定的interfaceClass或interfaceName，否則使用服務(wù)類實(shí)現(xiàn)的第一個(gè)接口。
     * 5.生成服務(wù) Bean 名稱：
     *      生成格式為ServiceBean:接口名:版本號(hào)的唯一名稱，確保同一接口的不同版本可以共存。
     * 6.構(gòu)建服務(wù) Bean 定義：
     *      創(chuàng)建ServiceBean的 Bean 定義，設(shè)置其屬性值為注解中的配置，并關(guān)聯(lián)到實(shí)際的服務(wù)實(shí)現(xiàn)類。
     * 7.注冊(cè)服務(wù) Bean：
     *      將構(gòu)建好的ServiceBean注冊(cè)到 Spring 容器中，使其成為一個(gè)可被管理的 Bean。
     */
    private void processScannedBeanDefinition(BeanDefinitionHolder beanDefinitionHolder) {

        // 解析服務(wù)類
        Class<?> beanClass = resolveClass(beanDefinitionHolder);

        // 查找服務(wù)注解（@DubboService或@Service）
        Annotation service = findServiceAnnotation(beanClass);

        // 獲取服務(wù)注解的屬性（如group、version等）
        Map<String, Object> serviceAnnotationAttributes = AnnotationUtils.getAttributes(service, true);

        // 解析服務(wù)接口名稱
        String serviceInterface = resolveInterfaceName(serviceAnnotationAttributes, beanClass);

        // 獲取Spring掃描生成的Bean名稱
        String annotatedServiceBeanName = beanDefinitionHolder.getBeanName();

        // 生成Dubbo服務(wù)Bean的名稱
        String beanName = generateServiceBeanName(serviceAnnotationAttributes, serviceInterface);

        // 構(gòu)建服務(wù)Bean定義
        AbstractBeanDefinition serviceBeanDefinition =
                buildServiceBeanDefinition(serviceAnnotationAttributes, serviceInterface, annotatedServiceBeanName);

        // 注冊(cè)服務(wù)Bean到Spring容器
        registerServiceBeanDefinition(beanName, serviceBeanDefinition, serviceInterface);
    }

    /**
     * 在給定的類上查找特定類型的注解，并支持 Spring 的合并注解機(jī)制。
     */
    private Annotation findServiceAnnotation(Class<?> beanClass) {
        return serviceAnnotationTypes.stream()
                .map(annotationType ->
                       // 檢查Spring的AnnotatedElementUtils類是否存在且包含findMergedAnnotation方法
                        ClassUtils.isPresent("org.springframework.core.annotation.AnnotatedElementUtils", Thread.currentThread()
                                .getContextClassLoader())
                                && ReflectUtils.hasMethod(org.springframework.core.annotation.AnnotatedElementUtils.class, "findMergedAnnotation")
                                // 如果Spring工具類可用，則使用Spring的合并注解查找
                                ? org.springframework.core.annotation.AnnotatedElementUtils.findMergedAnnotation(beanClass, annotationType)
                                // 否則使用Dubbo自定義的注解查找工具
                                : org.apache.dubbo.common.utils.AnnotationUtils.findAnnotation(beanClass, annotationType))
                .filter(Objects::nonNull)
                .findFirst()
                .orElse(null);
    }

    /**
     * 用于為 Dubbo 服務(wù)生成唯一的 Bean 名稱
     */
    private String generateServiceBeanName(Map<String, Object> serviceAnnotationAttributes, String serviceInterface) {
        ServiceBeanNameBuilder builder = create(serviceInterface, environment)
                .group((String) serviceAnnotationAttributes.get("group"))
                .version((String) serviceAnnotationAttributes.get("version"));
        return builder.build();
    }

    private Class<?> resolveClass(BeanDefinitionHolder beanDefinitionHolder) {

        BeanDefinition beanDefinition = beanDefinitionHolder.getBeanDefinition();

        return resolveClass(beanDefinition);
    }

    private Class<?> resolveClass(BeanDefinition beanDefinition) {

        String beanClassName = beanDefinition.getBeanClassName();

        return resolveClassName(beanClassName, classLoader);
    }

    /**
     * 處理用戶配置的包路徑，解析其中的占位符（如${dubbo.scan.base-packages}），并返回標(biāo)準(zhǔn)化的包路徑集合
     */
    private Set<String> resolvePackagesToScan(Set<String> packagesToScan) {
        // 創(chuàng)建有序集合，保持包路徑的順序并去重
        Set<String> resolvedPackagesToScan = new LinkedHashSet<>(packagesToScan.size());
        // 遍歷每個(gè)待掃描的包路徑
        for (String packageToScan : packagesToScan) {
            // 檢查路徑是否有內(nèi)容（非空且非空白字符）
            if (StringUtils.hasText(packageToScan)) {
                // 去除首尾空格并解析占位符（如 ${dubbo.scan.base-packages}）
                String resolvedPackageToScan = environment.resolvePlaceholders(packageToScan.trim());
                // 將解析后的路徑添加到結(jié)果集合
                resolvedPackagesToScan.add(resolvedPackageToScan);
            }
        }
        return resolvedPackagesToScan;
    }

    /**
     * 創(chuàng)建一個(gè)ServiceBean的定義，將其屬性值設(shè)置為注解中的配置（如group、version），并關(guān)聯(lián)到實(shí)際的服務(wù)實(shí)現(xiàn)類（通過refServiceBeanName引用）。
     */
    private AbstractBeanDefinition buildServiceBeanDefinition(
            Map<String, Object> serviceAnnotationAttributes, String serviceInterface, String refServiceBeanName) {

        BeanDefinitionBuilder builder = rootBeanDefinition(ServiceBean.class);

        AbstractBeanDefinition beanDefinition = builder.getBeanDefinition();
        beanDefinition.setAutowireMode(AbstractBeanDefinition.AUTOWIRE_CONSTRUCTOR);

        MutablePropertyValues propertyValues = beanDefinition.getPropertyValues();

        String[] ignoreAttributeNames = ObjectUtils.of(
                "provider",
                "monitor",
                "application",
                "module",
                "registry",
                "protocol",
                "methods",
                "interfaceName",
                "parameters",
                "executor");

        propertyValues.addPropertyValues(
                new AnnotationPropertyValuesAdapter(serviceAnnotationAttributes, environment, ignoreAttributeNames));

        // set config id, for ConfigManager cache key
        // builder.addPropertyValue("id", beanName);
        // References "ref" property to annotated-@Service Bean
        addPropertyReference(builder, "ref", refServiceBeanName);
        // Set interface
        builder.addPropertyValue("interface", serviceInterface);
        // Convert parameters into map
        builder.addPropertyValue("parameters", DubboAnnotationUtils.convertParameters((String[])
                serviceAnnotationAttributes.get("parameters")));
        // Add methods parameters
        List<MethodConfig> methodConfigs = convertMethodConfigs(serviceAnnotationAttributes.get("methods"));
        if (!methodConfigs.isEmpty()) {
            if (AotWithSpringDetector.isAotProcessing()) {
                List<String> methodsJson = new ArrayList<>();
                methodConfigs.forEach(methodConfig -> methodsJson.add(JsonUtils.toJson(methodConfig)));
                builder.addPropertyValue("methodsJson", methodsJson);
            } else {
                builder.addPropertyValue("methods", methodConfigs);
            }
        }

        // convert provider to providerIds
        String providerConfigId = (String) serviceAnnotationAttributes.get("provider");
        if (StringUtils.hasText(providerConfigId)) {
            addPropertyValue(builder, "providerIds", providerConfigId);
        }

        // Convert registry[] to registryIds
        String[] registryConfigIds = (String[]) serviceAnnotationAttributes.get("registry");
        if (registryConfigIds != null && registryConfigIds.length > 0) {
            resolveStringArray(registryConfigIds);
            builder.addPropertyValue("registryIds", StringUtils.join(registryConfigIds, ','));
        }

        // Convert protocol[] to protocolIds
        String[] protocolConfigIds = (String[]) serviceAnnotationAttributes.get("protocol");
        if (protocolConfigIds != null && protocolConfigIds.length > 0) {
            resolveStringArray(protocolConfigIds);
            builder.addPropertyValue("protocolIds", StringUtils.join(protocolConfigIds, ','));
        }

        // TODO Could we ignore these attributes: applicatin/monitor/module ? Use global config
        // monitor reference
        String monitorConfigId = (String) serviceAnnotationAttributes.get("monitor");
        if (StringUtils.hasText(monitorConfigId)) {
            addPropertyReference(builder, "monitor", monitorConfigId);
        }

        // module reference
        String moduleConfigId = (String) serviceAnnotationAttributes.get("module");
        if (StringUtils.hasText(moduleConfigId)) {
            addPropertyReference(builder, "module", moduleConfigId);
        }

        String executorBeanName = (String) serviceAnnotationAttributes.get("executor");
        if (StringUtils.hasText(executorBeanName)) {
            addPropertyReference(builder, "executor", executorBeanName);
        }

        // service bean definition should not be lazy
        builder.setLazyInit(false);

        return builder.getBeanDefinition();
    }

    private String[] resolveStringArray(String[] strs) {
        if (strs == null) {
            return null;
        }
        for (int i = 0; i < strs.length; i++) {
            strs[i] = environment.resolvePlaceholders(strs[i]);
        }
        return strs;
    }

    private List convertMethodConfigs(Object methodsAnnotation) {
        if (methodsAnnotation == null) {
            return Collections.EMPTY_LIST;
        }
        return MethodConfig.constructMethodConfig((Method[]) methodsAnnotation);
    }

    private void addPropertyReference(BeanDefinitionBuilder builder, String propertyName, String beanName) {
        String resolvedBeanName = environment.resolvePlaceholders(beanName);
        builder.addPropertyReference(propertyName, resolvedBeanName);
    }

    private void addPropertyValue(BeanDefinitionBuilder builder, String propertyName, String value) {
        String resolvedBeanName = environment.resolvePlaceholders(value);
        builder.addPropertyValue(propertyName, resolvedBeanName);
    }

    /**
     * 處理通過工廠方法創(chuàng)建的服務(wù) Bean，從中提取如@DubboService或@Service等注解的屬性值
     */
    private Map<String, Object> getServiceAnnotationAttributes(BeanDefinition beanDefinition) {
        // 檢查是否為注解類型的Bean定義
        if (beanDefinition instanceof AnnotatedBeanDefinition) {
            AnnotatedBeanDefinition annotatedBeanDefinition = (AnnotatedBeanDefinition) beanDefinition;
            // 獲取工廠方法元數(shù)據(jù)（如果是通過@Bean方法創(chuàng)建的Bean）
            MethodMetadata factoryMethodMetadata = SpringCompatUtils.getFactoryMethodMetadata(annotatedBeanDefinition);
            if (factoryMethodMetadata != null) {
                // 嘗試所有支持的服務(wù)注解類型
                for (Class<? extends Annotation> annotationType : serviceAnnotationTypes) {
                    // 檢查工廠方法是否帶有該類型的注解
                    if (factoryMethodMetadata.isAnnotated(annotationType.getName())) {
                        // 獲取注解屬性
                        Map<String, Object> annotationAttributes =
                                factoryMethodMetadata.getAnnotationAttributes(annotationType.getName());
                        // 過濾掉默認(rèn)值，只保留顯式設(shè)置的屬性
                        return filterDefaultValues(annotationType, annotationAttributes);
                    }
                }
            }
        }
        return null;
    }

    /**
     * 處理 Java 配置中帶有@DubboService注解的方法的過程。它從帶注解的方法中提取服務(wù)元數(shù)據(jù)，構(gòu)建服務(wù) Bean 定義，并將其注冊(cè)到 Spring 容器中。
     * 1.提取注解屬性
     *      從@DubboService注解中獲取配置屬性（如group、version等），存儲(chǔ)在serviceAnnotationAttributes
     * 2.解析服務(wù)接口類型
     *      2.1 通過SpringCompatUtils.getFactoryMethodReturnType獲取@Bean方法的返回類型名稱（即服務(wù)接口類型）。
     *      2.2 使用類加載器解析該類型名稱為Class對(duì)象。
     * 3.確定服務(wù)接口名稱
     *      調(diào)用resolveInterfaceName方法，優(yōu)先從注解屬性中獲取接口名，若未指定則使用方法返回類型
     * 4.生成服務(wù) Bean 名稱
     *      根據(jù)注解屬性和接口名生成唯一的ServiceBean名稱（例如ServiceBean:demoService:1.2.3）
     * 5.構(gòu)建服務(wù) Bean 定義
     *      調(diào)用buildServiceBeanDefinition創(chuàng)建一個(gè)ServiceBean的定義，將其屬性值設(shè)置為注解中的配置（如group、version），并關(guān)聯(lián)到實(shí)際的服務(wù)實(shí)現(xiàn)類（通過refServiceBeanName引用）。
     * 6.注冊(cè)服務(wù) Bean
     */
    private void processAnnotatedBeanDefinition(
            String refServiceBeanName,
            AnnotatedBeanDefinition refServiceBeanDefinition,
            Map<String, Object> attributes) {

        Map<String, Object> serviceAnnotationAttributes = new LinkedHashMap<>(attributes);

        // 通過 Spring 的反射工具獲取方法返回類型，確保正確識(shí)別服務(wù)接口。
        String returnTypeName = SpringCompatUtils.getFactoryMethodReturnType(refServiceBeanDefinition);
        Class<?> beanClass = resolveClassName(returnTypeName, classLoader);

        // 解析接口名
        String serviceInterface = resolveInterfaceName(serviceAnnotationAttributes, beanClass);

        // 獲取 Bean 名稱
        // 生成的名稱格式通常為 ServiceBean:接口名:版本號(hào)，確保唯一性
        String serviceBeanName = generateServiceBeanName(serviceAnnotationAttributes, serviceInterface);

        // 創(chuàng)建一個(gè)ServiceBean的定義，將其屬性值設(shè)置為注解中的配置（如group、version），并關(guān)聯(lián)到實(shí)際的服務(wù)實(shí)現(xiàn)類（通過refServiceBeanName引用）。
        AbstractBeanDefinition serviceBeanDefinition =
                buildServiceBeanDefinition(serviceAnnotationAttributes, serviceInterface, refServiceBeanName);

        // 設(shè)置ServiceBean的ID屬性
        serviceBeanDefinition.getPropertyValues().add(Constants.ID, serviceBeanName);
        // 將其注冊(cè)到Spring容器中，完成服務(wù)暴露
        registerServiceBeanDefinition(serviceBeanName, serviceBeanDefinition, serviceInterface);
    }

    /**
     * 將服務(wù)接口對(duì)應(yīng)的 Bean 定義注冊(cè)到 Spring 容器中，同時(shí)處理可能出現(xiàn)的重復(fù)注冊(cè)問題。
     */
    private void registerServiceBeanDefinition(
            String serviceBeanName, AbstractBeanDefinition serviceBeanDefinition, String serviceInterface) {
        // 檢查容器中是否已存在同名的Bean定義
        if (registry.containsBeanDefinition(serviceBeanName)) {
            BeanDefinition existingDefinition = registry.getBeanDefinition(serviceBeanName);
            // 如果已存在的Bean定義與當(dāng)前定義完全相同，則跳過注冊(cè)
            if (existingDefinition.equals(serviceBeanDefinition)) {
                // exist equipment bean definition
                return;
            }

            // 否則記錄錯(cuò)誤并拋出異常，避免沖突
            String msg = "Found duplicated BeanDefinition of service interface [" + serviceInterface
                    + "] with bean name [" + serviceBeanName + "], existing definition [ " + existingDefinition
                    + "], new definition [" + serviceBeanDefinition + "]";
            logger.error(CONFIG_DUPLICATED_BEAN_DEFINITION, "", "", msg);
            throw new BeanDefinitionStoreException(
                    serviceBeanDefinition.getResourceDescription(), serviceBeanName, msg);
        }

        // 將服務(wù)Bean定義注冊(cè)到Spring容器
        registry.registerBeanDefinition(serviceBeanName, serviceBeanDefinition);
        if (logger.isInfoEnabled()) {
            logger.info("Register ServiceBean[" + serviceBeanName + "]: " + serviceBeanDefinition);
        }
    }

    @Override
    public void setEnvironment(Environment environment) {
        this.environment = environment;
    }

    @Override
    public void setResourceLoader(ResourceLoader resourceLoader) {
        this.resourceLoader = resourceLoader;
    }

    @Override
    public void setBeanClassLoader(ClassLoader classLoader) {
        this.classLoader = classLoader;
    }

    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        this.servicePackagesHolder =
                applicationContext.getBean(ServicePackagesHolder.BEAN_NAME, ServicePackagesHolder.class);
    }

    private class ScanExcludeFilter implements TypeFilter {

        private int excludedCount;

        @Override
        public boolean match(MetadataReader metadataReader, MetadataReaderFactory metadataReaderFactory)
                throws IOException {
            String className = metadataReader.getClassMetadata().getClassName();
            boolean excluded = servicePackagesHolder.isClassScanned(className);
            if (excluded) {
                excludedCount++;
            }
            return excluded;
        }

        public int getExcludedCount() {
            return excludedCount;
        }
    }
}