---

Pre

插件 - 通过SPI方式实现插件管理

插件 - 一份配置，离插件机制只有一步之遥

插件 - 插件机制触手可及

Plugin - 插件开发01_SPI的基本使用

Plugin - 插件开发02_使用反射机制和自定义配置实现插件化开发

Plugin - 插件开发03_Spring Boot动态插件化与热加载

Plugin - 插件开发04_Spring Boot中的SPI机制与Spring Factories实现

---

概述

https://solon.noear.org/article/441

本系列在内核知识的基础上做进一步延申。主要涉及：

1. 插件
2. 插件扩展体系（Spi）
3. 插件体外扩展体系（E-Spi）
4. 插件热插拔管理机制（H-Spi）

这些知识，为构建大的项目架构会有重要帮助。

本系列演示可参考：

https://gitee.com/noear/solon-examples/tree/main/2.Solon_Advanced

---

插件

Solon Plugin 是框架的核心接口，简称“插件”。其本质是一个参与应用“生命周期”的接口。它可以代表一个模块参与应用的生命周期过程

public interface Plugin {
    //启动
    void start(AppContext context) throws Throwable;
    //预停止
    default void prestop() throws Throwable{}
    //停止
    default void stop() throws Throwable{}
}

---

插件扩展机制（Spi）

Solon框架实现的插件扩展机制，基于“插件”+“配置声明”的方式，提供了一种轻量、解耦、灵活的扩展方式，类似于Spring的Factories和Java的SPI（Service Provider Interface）。本文将详细介绍Solon插件扩展机制的实现及使用。

插件扩展机制概述

Solon的插件扩展机制简化了模块化的开发和插件的管理，允许开发者将可复用的功能封装成插件，并通过配置文件进行管理和加载。插件的核心作用是在应用启动时提供初始化和生命周期管理的功能，使得模块化的能力可以灵活地集成到系统中。

插件的类型非常多样，例如像@Tran、@Cache等注解功能，通常希望在多个项目中复用，因此它们的实现会被封装为插件。

插件扩展机制的优势

• 解耦：插件的引入和管理通过配置声明，使得核心业务与插件逻辑解耦。
• 灵活：插件可以根据需求进行启用、配置和排除。
• 扩展性强：用户可以方便地通过插件实现功能扩展，并可以根据优先级排序加载插件。

插件扩展机制实现步骤

第一步：定制插件实现类

插件实现类负责处理插件的生命周期，通常包括启动、停止、预停止等方法。在Solon中，插件实现类需要实现Plugin接口，并重写start、prestop和stop等方法。

示例代码：插件实现类

public class XPluginImpl implements Plugin {
    @Override
    public void start(AppContext context) {
        // 插件启动时，进行初始化工作
    }
    
    @Override
    public void prestop() throws Throwable {
        // 插件预停止时的操作
        // 注意：预停止后，插件将等待几秒后才会停止，适用于需要安全停止的插件
    }
    
    @Override
    public void stop() {
        // 插件停止时的清理工作
    }
}

第二步：通过插件配置文件声明插件

插件需要通过配置文件来声明自己，配置文件通常放置在META-INF/solon/目录下，并且文件名需保证全局唯一，通常使用包名作为文件名，以避免冲突。

示例插件配置文件：META-INF/solon/solon.data.properties

# 插件实现类配置
solon.plugin=org.noear.solon.data.integration.XPluginImp  
# 插件优先级配置，值越大优先级越高，默认为0
solon.plugin.priority=1

第三步：扫描并发现插件

在应用启动时，Solon框架会扫描META-INF/solon/目录下的所有配置文件，加载并按照配置文件中的优先级排序插件。

插件的排除

有时，在项目中可能引入了多个插件包，但我们希望排除某些插件。Solon提供了solon.plugin.exclude配置项来排除不需要的插件。

示例：排除插件

solon.plugin.exclude:
  - "org.noear.solon.data.integration.XPluginImp"

插件包的命名规范

Solon框架对插件包有一定的命名规范，以便于区分不同类型的插件：

插件命名规则	说明
solon-*	表示内部架构插件
*-solon-plugin	表示外部适配插件
*-solon-cloud-plugin	表示云接口外部适配插件

示例：Solon Data 插件

Solon Data插件提供了事务管理的能力，使用@Tran注解可以自动管理事务。下面我们以Solon Data插件为例，演示如何实现一个插件。

插件实现类：XPluginImp.java

public class XPluginImp implements Plugin {
    @Override
    public void start(AppContext context) {
        // 如果启用事务管理，则添加事务拦截器
        if (Solon.app().enableTransaction()) {
            context.beanInterceptorAdd(Tran.class, new TranInterceptor(), 120);
        }
    }
}

插件配置文件：META-INF/solon/solon.data.properties

# 配置插件实现类
solon.plugin=org.noear.solon.data.integration.XPluginImp
# 配置插件优先级
solon.plugin.priority=3

插件应用示例

在应用中，我们可以通过@Tran注解来使用插件提供的事务管理能力。

@Component
public class AppService {
    @Inject
    AppMapper appMapper;

    @Tran
    public void addApp(App app) {
        // 事务管理：如果方法执行失败，将回滚事务
        appMapper.add(app);
    }
}

插件引入

在pom.xml中引入solon-data插件依赖：

<dependency>
    <groupId>org.noear</groupId>
    <artifactId>solon-data</artifactId>
    <version>最新版本</version>
</dependency>

小结

Solon框架的插件扩展机制为我们提供了一种非常灵活、解耦且可扩展的方式来实现应用的功能扩展。通过插件机制，我们可以将通用的功能封装成插件，并且在应用中按需引入。插件的生命周期由Solon自动管理，而通过配置文件，我们可以灵活地管理插件的优先级、排除插件等。

---

插件体外扩展机制（E-Spi）

很多时候我们需要解决如何在 fatjar 模式部署时实现插件化扩展的问题。Solon框架提供了一个名为 E-Spi 的插件体外扩展机制，旨在解决将业务模块、配置文件等放在应用外部的问题。通过 E-Spi，我们能够将插件和配置与主程序解耦，从而使得后期的插件更新、配置修改等更加灵活。

E-Spi 插件体外扩展机制概述

E-Spi 机制的设计主要是为了应对以下场景：

• 将某些业务模块（如用户模块、订单模块等）打包成插件包放在外部。
• 将配置信息（如数据源配置、缓存配置等）单独放在外部，便于后期修改。

E-Spi 使得插件和配置文件可以在应用外部部署，且支持后续的灵活修改和热更新。这种机制具有高效的插件管理功能，并且能够与现有的 fatjar 部署模式无缝集成。

E-Spi 机制特点

1. 共享资源

所有插件包共享同一个 ClassLoader、AppContext 和配置。也就是说，所有的插件都能访问相同的资源，保证插件之间的协作和互操作。

2. 灵活的打包方式

• 体外插件包：插件可以作为独立的包（如 .jar 文件）放到体外，供主应用加载。
• 内嵌插件包：插件也可以与主程序一起打包成一个 fatjar，支持两种方式的灵活切换。

3. 更新机制

• 更新体外插件包或配置文件时，需要重启主服务才能生效。
• 不同于直接打包在一起的插件，体外插件需要借助指定的扩展目录来加载。

4. 内核支持

E-Spi 是由 Solon 内核直接提供支持的，不需要额外的依赖，极大简化了扩展机制的使用。

E-Spi 插件扩展操作说明

配置扩展目录

为了让 Solon 知道从哪里加载外部插件和配置文件，我们需要在应用的配置文件中指定扩展目录。该目录可以手动创建，也可以通过配置让 Solon 自动创建。

示例配置：手动指定扩展目录

solon.extend: "demo_ext"

此时，demo_ext 目录需要手动创建，并且 Solon 会从这个目录加载插件和配置文件。

示例配置：自动创建扩展目录

solon.extend: "!demo_ext"

当使用 ! 前缀时，Solon 会在启动时自动创建该扩展目录。

插件包和配置文件加载

插件体外扩展机制支持将不同类型的文件放置在扩展目录中，并进行加载。

1. 数据源配置文件

假设我们有一个数据库配置文件 _db.properties，我们可以将它放置在扩展目录中，后续可以方便地进行修改而无需重新打包应用。

demo.jar
demo_ext/_db.properties

2. 插件包

除了配置文件外，我们还可以将业务模块做成插件包（如 .jar 文件），并将其放到扩展目录中。Solon会自动扫描并加载这些插件。

demo.jar
demo_ext/_db.properties
demo_ext/demo_user.jar
demo_ext/demo_order.jar

插件包的打包注意事项

插件包的管理是 E-Spi 机制中的关键部分。插件包可以选择以下两种打包方式：

1. 打成 FatJar

将插件包打成 fatjar（使用 maven-assembly-plugin 插件）是一种常见的方式。Fatjar 是包含所有依赖的单一 JAR 文件，这种方式方便部署，但文件较大。

2. 与主应用共享依赖

更推荐的方式是将插件包的公共依赖放入主应用中，而在插件包的 pom.xml 中将这些依赖标记为可选。这样可以避免重复依赖，提高应用的整体性能。

示例演示：E-Spi 扩展机制使用示例

目录结构

假设我们有如下的目录结构：

demo.jar
demo_ext/
  ├── _db.properties
  ├── demo_user.jar
  └── demo_order.jar

其中：

• demo.jar 是主应用的 JAR 包。
• demo_ext/ 目录包含了外部扩展的插件包和配置文件。

配置文件示例：_db.properties

# 数据源配置文件
db.url=jdbc:mysql://localhost:3306/demo
db.username=root
db.password=secret

插件包示例：demo_user.jar

demo_user.jar 可能包含了用户模块的相关功能，实现了业务逻辑或数据处理。

插件包示例：demo_order.jar

demo_order.jar 可能包含了订单模块的相关功能，同样是一个独立的插件包。

主应用代码示例

在主应用中，我们通过 @Inject 注解加载外部插件，并在应用中使用它们的功能。

@Component
public class AppService {
    @Inject
    AppMapper appMapper;

    @Tran
    public void addApp(App app) {
        appMapper.add(app);
    }
}

小结

Solon的插件体外扩展机制（E-Spi）为我们提供了一种非常灵活的方式来管理插件和配置文件。通过将插件和配置文件体外化，我们可以实现以下目标：

• 模块化：不同的业务模块可以作为独立的插件进行管理和部署。
• 灵活性：配置文件可以单独存放在外部，便于修改和热更新。
• 简化依赖管理：公共依赖可以由主应用来统一管理，避免重复。

E-Spi 机制不仅能支持传统的 fatjar 模式，也能够满足更高效的插件管理需求，是构建高可扩展性微服务系统的理想选择。

---

插件热插拔管理机制（H-Spi）

插件化和模块化管理已经成为了开发的重要方向。Solon框架提供了一个名为 H-Spi 的插件热插拔管理机制，它专注于提供隔离性、热插拔性和管理性。与 E-Spi 机制不同，H-Spi 更强调在生产环境下的灵活性，尤其是在支持插件热更新和模块隔离方面的优势。

H-Spi 插件热插拔管理机制概述

H-Spi 是一种为生产环境设计的扩展方案。它的核心目标是通过热插拔机制管理插件，并确保插件间的隔离性。通过 H-Spi，应用能够在运行时动态加载、卸载插件，而无需重启主服务。每个插件在运行时都拥有独立的资源和上下文，避免了插件间的相互干扰。

1. 特点说明

1.1 完全隔离

H-Spi 机制下，每个插件包都会拥有独立的 ClassLoader、AppContext 和配置。插件之间的资源和环境完全隔离，可以避免不同插件之间的冲突或干扰。

• ClassLoader 隔离：插件包独享自己的 ClassLoader，确保插件间不会互相访问或修改其他插件的资源。
• AppContext 隔离：每个插件可以访问自己的上下文，但也可以通过 Solon.app()、Solon.cfg() 和 Solon.context() 等方式手动获取主程序或全局资源。

1.2 动态热插拔

H-Spi 机制支持热插拔，即可以在不重启主服务的情况下进行插件的动态加载和卸载。这大大提高了应用的灵活性，特别是在生产环境下进行插件更新时无需影响整个系统的稳定性。

1.3 资源独立管理

在插件开发过程中，开发者需要保证插件资源的独立性。如果插件启动时向系统添加了某些资源或对象，则在插件停止时必须移除这些资源，以支持热更新。

1.4 事件总线交互

为了保证插件之间的松耦合，插件之间的交互尽量通过事件总线（EventBus）进行。事件数据通常采用弱类型（如 Map 或 JSON 字符串）形式传递，以减少插件之间的依赖关系。推荐与 DamiBus 等工具结合使用，进一步解耦。

2. 关于 ClassLoader 隔离

H-Spi 的 ClassLoader 隔离 是其关键特性之一。在这种隔离下，插件只能访问自己的资源和类，无法直接访问其他插件的资源。这意味着，插件之间的交互需要更加小心，并避免直接通过类进行互相访问。

2.1 父子级 ClassLoader

• 父级 ClassLoader：通常用于存放公共资源，子级插件可以访问父级 ClassLoader 中的资源。
• 子级 ClassLoader：插件会使用自己的 ClassLoader，它无法直接访问同级插件的类或资源。

2.2 同级 ClassLoader

• 同级插件之间无法直接交互。如果需要交互，建议通过事件总线进行，避免显式的类交互。
• 交互的数据：可以使用父级 ClassLoader 的实体类，或者使用弱类型的数据，如 JSON 字符串等。

2.3 插件之间的独立性

建议尽量减少插件之间的交互，使每个插件都能独立运行。如果确实需要交互，最好通过事件总线（EventBus）来进行，且使用弱类型数据格式（如 Map 或 JSON）。

3. 插件开发注意事项

在 H-Spi 模式下，插件开发需要特别注意资源的添加与移除。特别是在插件停止时，必须清理所有为插件注册的资源，确保插件的热插拔能力得以保持。

3.1 插件资源的管理

例如，当插件启动时，可能会向系统添加配置文件、扫描 Bean 或注册静态文件等操作。这些资源在插件停止时需要被移除。

public class Plugin1Impl implements Plugin {
    private AppContext context;
    private StaticRepository staticRepository;

    @Override
    public void start(AppContext context) {
        this.context = context;

        // 添加配置文件
        context.cfg().loadAdd("demo1011.plugin1.yml");

        // 扫描插件的 Bean
        context.beanScan(Plugin1Impl.class);

        // 注册静态文件仓库
        staticRepository = new ClassPathStaticRepository(context.getClassLoader(), "plugin1_static");
        StaticMappings.add("/html/", staticRepository);
    }

    @Override
    public void stop() throws Throwable {
        // 移除 HTTP 路由
        Solon.app().router().remove("/user");

        // 移除定时任务（如果有）
        JobManager.remove("job1");

        // 移除事件订阅
        context.beanForeach(bw -> {
            if (bw.raw() instanceof EventListener) {
                EventBus.unsubscribe(bw.raw());
            }
        });

        // 移除静态文件仓库
        StaticMappings.remove(staticRepository);
    }
}

3.2 资源清理

在插件停止时，务必执行清理工作，确保不会留下不必要的资源。这是 H-Spi 热插拔机制的关键。

3.3 模板渲染的 ClassLoader 问题

当涉及到模板渲染时，可能会遇到 ClassLoader 的问题。例如，如果使用 Freemarker 渲染模板时，必须确保模板加载的 ClassLoader 是正确的：

public class BaseController implements Render {
    // 要考虑模板所在的 classloader
    static final FreemarkerRender viewRender = new FreemarkerRender(BaseController.class.getClassLoader());

    @Override
    public void render(Object data, Context ctx) throws Throwable {
        if (data instanceof Throwable) {
            throw (Throwable) data;
        }

        if (data instanceof ModelAndView) {
            viewRender.render(data, ctx);
        } else {
            ctx.render(data);
        }
    }
}

4. 插件管理

在 H-Spi 中，插件不只是通过独立 ClassLoader 进行管理，还可以通过 solon-hotplug 插件来实现插件的仓库化和平台化。这样，插件可以通过中央仓库进行管理，并在平台上动态更新、卸载，进一步提升应用的灵活性和可扩展性。

通过插件管理工具，平台可以更好地控制插件的生命周期，支持对插件的版本管理、更新和回滚。

小结

H-Spi 插件热插拔管理机制是为生产环境设计的高效扩展方案，具有以下几个核心特点：

1. 插件隔离性：每个插件包独享 ClassLoader、AppContext 和配置，避免了插件间的冲突。
2. 热插拔：支持插件的动态加载和卸载，无需重启主服务，提升了系统的灵活性。
3. 资源清理：插件在停止时必须移除自己注册的所有资源，以支持热更新。
4. 事件总线交互：插件之间通过事件总线进行松耦合的交互，减少了插件之间的依赖。

H-Spi 提供了一个非常灵活的插件化架构，适用于需要高可扩展性和模块化管理的生产环境。通过 H-Spi，可以实现插件的热插拔和灵活更新，极大地提高了系统的可维护性和扩展能力。

---

Code

import org.noear.solon.Utils;
import org.noear.solon.core.PluginEntity;

import java.net.URL;
import java.util.Collection;
import java.util.Properties;
import java.util.function.Consumer;

/**
 * 插件工具
 *
 * @author noear
 * @since 1.7
 */
public class PluginUtil {
    /**
     * 扫描插件
     *
     * @param classLoader 类加载器
     * @param excludeList 排除列表
     */
    public static void scanPlugins(ClassLoader classLoader, Collection<String> excludeList, Consumer<PluginEntity> consumer) {
        //3.查找插件配置（如果出错，让它抛出异常）
        Collection<String> nameList = ScanUtil.scan(classLoader, "META-INF/solon", n -> n.endsWith(".properties"));

        for (String name : nameList) {
            URL res = ResourceUtil.getResource(classLoader, name);

            if (res == null) {
                // native 时，扫描出来的resource可能是不存在的（这种情况就是bug），需要给于用户提示，反馈给社区
                LogUtil.global().warn("Solon plugin: name=" + name + ", resource is null");
            } else {
                Properties props = Utils.loadProperties(res);
                findPlugins(classLoader, props, excludeList, consumer);
            }
        }
    }

    /**
     * 查找插件
     */
    public static void findPlugins(ClassLoader classLoader, Properties props, Collection<String> excludeList,Consumer<PluginEntity> consumer) {
        String pluginStr = props.getProperty("solon.plugin");

        if (Utils.isNotEmpty(pluginStr)) {
            String priorityStr = props.getProperty("solon.plugin.priority");
            int priority = 0;
            if (Utils.isNotEmpty(priorityStr)) {
                priority = Integer.parseInt(priorityStr);
            }

            String[] plugins = pluginStr.trim().split(",");

            for (String clzName : plugins) {
                if (clzName.length() > 0) {
                    if(excludeList.contains(clzName)) {
                        continue;
                    }

                    PluginEntity ent = new PluginEntity(classLoader, clzName.trim(), props);
                    ent.setPriority(priority);
                    consumer.accept(ent);
                }
            }
        }
    }
}

import org.noear.solon.core.AppClassLoader;
import org.noear.solon.core.exception.ConstructionException;
import org.noear.solon.core.wrap.ClassWrap;

import java.lang.reflect.*;
import java.util.Collection;
import java.util.Properties;

/**
 * 类操作工具
 *
 * @author noear
 * @since 2.2
 */
public class ClassUtil {

    /**
     * 是否存在某个类
     *
     * <pre><code>
     * if(ClassUtil.hasClass(()->DemoTestClass.class)){
     *     ...
     * }
     * </code></pre>
     *
     * @param test 检测函数
     */
    public static boolean hasClass(SupplierEx<Class<?>> test) {
        try {
            test.get();
            return true;
        } catch (ClassNotFoundException | NoClassDefFoundError e) {
            return false;
        } catch (Throwable e) {
            throw new IllegalStateException(e);
        }
    }

    /**
     * 根据字符串加载为一个类（如果类不存在返回 null）
     *
     * @param className 类名称
     */
    public static Class<?> loadClass(String className) {
        return loadClass(null, className);
    }

    /**
     * 根据字符串加载为一个类（如果类不存在返回 null）
     *
     * @param classLoader 类加载器
     * @param className   类名称
     */
    public static Class<?> loadClass(ClassLoader classLoader, String className) {
        try {
            if (classLoader == null) {
                return Class.forName(className);
            } else {
                return classLoader.loadClass(className);
            }
        } catch (ClassNotFoundException | NoClassDefFoundError e) {
            return null;
        }
    }

    /**
     * 尝试根据类名实例化一个对象（如果类不存在返回 null）
     *
     * @param className 类名称
     */
    public static <T> T tryInstance(String className) {
        return tryInstance(className, null);
    }


    /**
     * 尝试根据类名实例化一个对象（如果类不存在返回 null）
     *
     * @param className 类名称
     * @param prop      属性
     */
    public static <T> T tryInstance(String className, Properties prop) {
        return tryInstance(AppClassLoader.global(), className, prop);
    }


    /**
     * 尝试根据类名实例化一个对象（如果类不存在返回 null）
     *
     * @param classLoader 类加载器
     * @param className   类名称
     */
    public static <T> T tryInstance(ClassLoader classLoader, String className) {
        return tryInstance(classLoader, className, null);
    }


    /**
     * 尝试根据类名实例化一个对象（如果类不存在返回 null）
     *
     * @param classLoader 类加载器
     * @param className   类名称
     * @param prop        属性
     */
    public static <T> T tryInstance(ClassLoader classLoader, String className, Properties prop) {
        Class<?> clz = loadClass(classLoader, className);

        return tryInstance(clz, prop);
    }

    public static <T> T tryInstance(Class<?> clz, Properties prop) {
        if (clz == null) {
            return null;
        } else {
            try {
                return newInstance(clz, prop);
            } catch (Exception e) {
                throw new IllegalStateException(e);
            }
        }
    }

    /**
     * 根据类名实例化一个对象
     *
     * @param clz 类
     */
    public static <T> T newInstance(Class<?> clz) throws ConstructionException {
        return newInstance(clz, null);
    }


    /**
     * 根据类名实例化一个对象
     *
     * @param clz  类
     * @param prop 属性
     */
    public static <T> T newInstance(Class<?> clz, Properties prop) throws ConstructionException {
        try {
            if (prop == null) {
                return (T) clz.getDeclaredConstructor().newInstance();
            } else {
                return (T) clz.getConstructor(Properties.class).newInstance(prop);
            }
        } catch (Exception e) {
            throw new ConstructionException(e);
        }
    }

    /**
     * 根据类名和参数类型实例化一个对象
     *
     * @param clz   类
     * @param types 构建参数类型
     * @param args  参数
     */
    public static Object newInstance(Class<?> clz, Class<?>[] types, Object[] args) {
        try {
            Constructor<?> constructor = clz.getDeclaredConstructor(types);
            return constructor.newInstance(args);
        } catch (Exception e) {
            throw new ConstructionException(e);
        }
    }

    /**
     * 根据构造函数实例化一个对象
     *
     * @param constructor 构造器
     * @param args        参数
     */
    public static Object newInstance(Constructor constructor, Object[] args) {
        try {
            return constructor.newInstance(args);
        } catch (Exception e) {
            throw new ConstructionException(e);
        }
    }


    /

    private static final ClassLoader systemClassLoader = ClassLoader.getSystemClassLoader();

    /**
     * 分析类加载器
     */
    public static ClassLoader resolveClassLoader(Type type) {
        ClassLoader loader = AppClassLoader.global();

        if (type != null) {
            Class<?> clz = getTypeClass(type);

            if (clz != Object.class) {
                ClassLoader cl = clz.getClassLoader();
                if (cl != systemClassLoader) {
                    loader = cl;
                }
            }
        }

        return loader;
    }

    /**
     * 获取类
     */
    public static Class<?> getTypeClass(Type type) {
        if (type instanceof Class) {
            return (Class<?>) type;
        } else if (type instanceof ParameterizedType) {
            //ParameterizedType
            return getTypeClass(((ParameterizedType) type).getRawType());
        } else {
            //TypeVariable
            return Object.class;
        }
    }

    /**
     * 比较参数类型
     */
    public static boolean equalParamTypes(Class<?>[] params1, Class<?>[] params2) {
        if (params1.length == params2.length) {
            for (int i = 0; i < params1.length; i++) {
                if (params1[i] != params2[i])
                    return false;
            }
            return true;
        }
        return false;
    }

    /**
     * 查找 method
     */
    public static Collection<Method> findPublicMethods(Class<?> clz) {
        return ClassWrap.get(clz).findPublicMethods();
    }
}