Solon 热加载与插件热插拔：从 Debug 模式到生产级 H-Spi 实战

# application.yml
solon.debug: true

@Controller
public class PageController {

    @Mapping("/hello")
    public ModelAndView hello(Context ctx) {
        ModelAndView mv = new ModelAndView("hello.ftl");
        mv.put("title", "Solon 热加载演示");
        mv.put("items", List.of("插件", "热插拔", "Debug"));
        return mv;
    }
}

<h1>${title}</h1>
<ul>
  <#list items as item>
    <li>${item}</li>
  </#list>
</ul>

// 主应用定义接口契约（在公共模块中）
public interface ReportPlugin {
    String name();
    byte[] generate(ReportRequest request);
}

// 插件实现（在独立 jar 模块中）
@SolonMain
public class PdfReportPlugin implements ReportPlugin {

    @Override
    public String name() {
        return "pdf-report";
    }

    @Override
    public byte[] generate(ReportRequest request) {
        // 插件内部可以使用自己的 PDF 库版本
        // 不会和主应用的依赖冲突
        PdfDocument doc = new PdfDocument();
        doc.addContent(request.getTitle());
        doc.addTable(request.getData());
        return doc.toBytes();
    }
}

@Component
public class ReportService {

    // 通过 E-Spi 机制注入插件实例
    @Spi("pdf-report")
    private ReportPlugin pdfPlugin;

    @Spi("excel-report")
    private ReportPlugin excelPlugin;

    public byte[] generateReport(String type, ReportRequest request) {
        ReportPlugin plugin = switch (type) {
            case "pdf" -> pdfPlugin;
            case "excel" -> excelPlugin;
            default -> throw new IllegalArgumentException("未知报表类型: " + type);
        };
        return plugin.generate(request);
    }
}

my-app/
├── lib/
│   └── my-app-main.jar
├── ext/
│   ├── pdf-report-plugin.jar
│   └── excel-report-plugin.jar
└── application.yml

// 契约接口（公共模块）
public interface HotFeature {
    String name();
    void init(Context ctx);
    Object execute(Map<String, Object> params);
    void stop();
}

// 插件实现（独立 jar）
@SolonMain
public class AiSummaryFeature implements HotFeature {

    private AiClient aiClient;

    @Override
    public String name() {
        return "ai-summary";
    }

    @Override
    public void init(Context ctx) {
        // 初始化插件自己的资源
        String apiKey = Solon.cfg().get("plugin.ai-summary.api-key");
        aiClient = new AiClient(apiKey);
    }

    @Override
    public Object execute(Map<String, Object> params) {
        String text = (String) params.get("text");
        return aiClient.summarize(text);
    }

    @Override
    public void stop() {
        // 释放资源，断开连接
        if (aiClient != null) {
            aiClient.close();
            aiClient = null;
        }
    }
}

@Component
public class FeatureManager {

    private final Map<String, HotFeature> features = new ConcurrentHashMap<>();

    /** 加载并启动一个 H-Spi 插件 */
    public void install(String pluginJarPath) {
        // Solon H-Spi 加载机制：创建独立类加载器，实例化插件
        HotFeature feature = SpiHotLoader.load(HotFeature.class, pluginJarPath);
        feature.init(Solon.context());
        features.put(feature.name(), feature);
        System.out.println("插件已安装并启动: " + feature.name());
    }

    /** 卸载一个 H-Spi 插件 */
    public void uninstall(String featureName) {
        HotFeature feature = features.remove(featureName);
        if (feature != null) {
            feature.stop();
            // SpiHotLoader 会释放该插件的类加载器
            SpiHotLoader.release(featureName);
            System.out.println("插件已卸载: " + featureName);
        }
    }

    /** 热替换：卸载旧版本，加载新版本 */
    public void replace(String featureName, String newPluginJarPath) {
        uninstall(featureName);
        install(newPluginJarPath);
    }

    /** 使用插件 */
    public Object use(String featureName, Map<String, Object> params) {
        HotFeature feature = features.get(featureName);
        if (feature == null) {
            throw new IllegalStateException("插件未安装: " + featureName);
        }
        return feature.execute(params);
    }
}

@Controller
@Mapping("/feature")
public class FeatureController {

    @Inject
    private FeatureManager manager;

    @Mapping("/install")
    public String install(@Param String jarPath) {
        manager.install(jarPath);
        return "ok";
    }

    @Mapping("/uninstall")
    public String uninstall(@Param String name) {
        manager.uninstall(name);
        return "ok";
    }

    @Mapping("/use")
    public Object use(@Param String name, @Body Map<String, Object> params) {
        return manager.use(name, params);
    }
}

# 安装插件
curl "http://localhost:8080/feature/install?jarPath=/opt/plugins/ai-summary-v1.jar"

# 使用插件
curl -X POST "http://localhost:8080/feature/use?name=ai-summary" \
  -H "Content-Type: application/json" \
  -d '{"text": "Solon 是一个轻量级 Java 框架..."}'

# 热替换为新版本（先卸载再安装）
curl "http://localhost:8080/feature/uninstall?name=ai-summary"
curl "http://localhost:8080/feature/install?jarPath=/opt/plugins/ai-summary-v2.jar"