Halo插件开发：java17旧项目迁移至java21项目记录

最近 Halo 2.21.0的更新将 java版本从 17 升级到 21 ，同时针对前端部分增加了代码分割方案，使得控制台的代码提及变得更小，用户体验更良好。于是几经折腾下，对于我一些还没有发布的插件进行了逐步改造，将项目的 jdk 从17升级到 21。

先说一下我之前失败的迁移经历吧，我直接是通过修改 halo 插件项目根目录下的 build.gradle 的配置以及增加 ui 部分的 build.gradle 并同时修改 ui 部分的打包配置文件 vite.config.ts 为 rsbuild.config.ts 。不知道为什么，总是在执行 pnpmSetup 命令的时候报错，试了各种办法都不行，索性直接使用新的 cli 来构建项目，然后把旧项目的文件迁移过去。

1、使用 cli 工具创建新的项目结构

pnpm create halo-plugin@latest

接着控制台会出现如下提示，输入插件名称的时候不要加 plugin- , 此 cli 工具会自动为插件名称加入此前缀。

🚀 Welcome to Halo Plugin Creator!

✔ Plugin name: › hello-world
✔ Domain (for group and package name): › com.example
✔ Author name: › Halo
✔ Choose UI build tool: › Rsbuild

📋 Project Configuration:
   Name: hello-world
   Domain: com.example
   Package: com.example.hello-world
   Author: Halo
   UI Tool: rsbuild
   Output Directory: /path/to/hello-world

✔ Create project? › yes

2、配置项目

halo 插件项目要求的开发环境如下：


- Java 21+
- Node.js 18+
- pnpm

按照下图所示设置 jdk版本

接着设置一下 nodejs 的环境

接着将自己之前的后端代码和前端代码粘贴至新的项目目录下，不过这块要注意下后端代码一些过时的API，这些API在 2.21.0版本下已经被移除，所有的破坏性更新如下：

破坏性更新
移除过时类 run.halo.app.extension.router.selector.FieldCriteriaPredicateConverter 和
run.halo.app.extension.router.selector.LabelCriteriaPredicateConverter，推荐用
run.halo.app.extension.router.selector.SelectorConverter 替代。
移除过时类 run.halo.app.search.SearchParam，推荐用 run.halo.app.search.SearchOption 替代。
移除过时类 run.halo.app.search.post.PostDoc 和 run.halo.app.search.post.PostHit，推荐用
run.halo.app.search.HaloDocument 替代。
移除 Plugin 过时字段 spec.pluginClass，推荐在插件定义文件中移除此字段。
移除 Plugin 过时字段 spec.website，推荐使用 spec.homepage 替代。
移除 Plugin 过时字段 spec.require，推荐使用 spec.requires 替代。
移除 SystemSetting.AuthProvider 过时字段 enabled，已经由 SystemSetting.AuthProvider 的 states 字段替代。
移除 run.halo.app.extension.ExtensionMatcher 过时方法 getGvk、getLabelSelector和 getFieldSelector。
移动方法 run.halo.app.extension.MetadataOperator#metadataDeepEquals 至
run.halo.app.extension.MetadataOperator#equals。
移除 run.halo.app.extension.router.QueryParamBuildUtil 过时方法 buildParametersFromType，推荐使用
org.springdoc.core.fn.builders.operation.Builder#parameter 替代。
移除 run.halo.app.extension.router.SortableRequest 过时方法 toPredicate，推荐使用
run.halo.app.extension.router.SortableRequest#toListOptions 替代。
移除 run.halo.app.extension.router.selector.SelectorUtil 过时方法 labelSelectorsToPredicate、
fieldSelectorToPredicate 和 labelAndFieldSelectorToPredicate，推荐使用
run.halo.app.extension.router.selector.SelectorUtil#labelAndFieldSelectorToListOptions 替代。
移除 run.halo.app.theme.finders.TagFinder 过时方法 list(Integer, Integer, Predicate, Predicate)，推荐使用
run.halo.app.theme.finders.TagFinder#list(Integer, Integer) 替代。
移除 run.halo.app.plugin.BasePlugin 过时构造函数 BasePlugin(PluginWrapper)，推荐使用 BasePlugin(PluginContext)
替代。
移除接口 GET&PUT /apis/api.console.halo.run/v1alpha1/plugins/{name}/config，推荐使用
GET&PUT /apis/api.console.halo.run/v1alpha1/plugins/{name}/json-config 替代。
移除接口 GET&PUT /apis/api.console.halo.run/v1alpha1/themes/{name}/config，推荐使用
GET&PUT /apis/api.console.halo.run/v1alpha1/themes/{name}/json-config 替代。
移除接口 POST /apis/api.halo.run/v1alpha1/indices/post，推荐使用 POST /apis/api.halo.run/v1alpha1/indices/-/search
替代。
移除接口 POST /apis/api.console.halo.run/v1alpha1/indices/post，推荐使用
POST /apis/api.console.halo.run/v1alpha1/indices/-/rebuild 替代。
最后，请确保更新 plugin.yaml 中的 requires 字段为 >=2.21.0-alpha.1。

3、运行项目

3.1、运行方案一

如果顺利的话，直接可以在halo提供的开发工具里边点击 haloServer 就可以运行，但是个人尝试后发现，时好时坏，因此建议命令行执行。

3.2、运行方案二

# 运行前先执行此命令，停止所有 gradle 进程
./gradlew --stop
# 接着运行如下命令
./gradlew --haloServer

如果后边在使用 generateApiCLient 和 reloadPlugin 工具时也出现报错，建议使用命令行执行。

3.3、运行方案三

如果上边两种方式都无法成功运行项目，可以使用终端去打开 Intelij idea后再去运行项目。

macos 系统下使用终端打开 idea

cd /Applications
./IntelliJ\ IDEA.app/Contents/MacOS/idea

其他操作系统请参考 Jetbrais 的官方文档查阅。

4、常见错误解决方案

1、测试包报错

最新的 halo 插件项目中官方加入了测试包，默认会有如下这样一个测试方法，用于启动关闭插件。

@ExtendWith(MockitoExtension.class)
class TimelinesPluginTest {

    @Mock
    PluginContext context;

    @InjectMocks
    TimelinesPlugin plugin;

    @Test
    void contextLoads() {
        plugin.start();
        plugin.stop();
    }

}

上边的测试方法在空项目可以运行起来，但是我将旧项目迁移过来之后，就会报错，具体信息如下所示。