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

webjing
2025-07-01
点 赞
1
热 度
21
评 论
1

文章摘要

智阅GPT

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

先说一下我之前失败的迁移经历吧,我直接是通过修改 halo 插件项目根目录下的 build.gradle 的配置以及增加 ui 部分的 build.gradle 并同时修改 ui 部分的打包配置文件 vite.config.tsrsbuild.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版本

jdk21-seting.png

接着设置 一下 nodejs 的环境

pnpm-version.png

接着将自己之前的后端代码和前端代码粘贴至新的项目目录下,不过这块要注意下后端代码一些过时的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 过时方法 getGvkgetLabelSelector和 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 就可以运行,但是个人尝试后发现,时好时坏,因此建议命令行执行。

halo-server.png

3.2、运行方案二

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

如果后边在使用 generateApiCLientreloadPlugin 工具时也出现报错,建议使用命令行执行。

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();
    }

}

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

halo-project-test-err.webp

解决方法:删除上边的 contentLoads 测试方法即可


此教程只是针对我个人的情况以及成功案例进行一个记录,并不具有普适性,如果按照我的方案运行还有问题,欢迎评论区随时交流👏。


webjing,一个来自黄河之滨的无产阶级打工人,怀揣着对技术的热爱与对生活的感悟,致力于用文字记录点滴思考与成长。希望我的文章能够给你带来帮助和思考,如同晨曦微光,照亮你前行的道路。

webjing

infp 调停者

站长

具有版权性

请您在转载、复制时注明本文 作者、链接及内容来源信息。 若涉及转载第三方内容,还需一同注明。

具有时效性

文章目录

欢迎来到webjing的站点,为您导航全站动态

52 文章数
6 分类数
114 评论数
51标签数
最近评论
webjing

webjing


已添加

webjing

webjing


哈哈哈 好像还真是

访问统计