最近 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();
}
}
上边的测试方法在空项目可以运行起来,但是我将旧项目迁移过来之后,就会报错,具体信息如下所示。
解决方法:删除上边的 contentLoads 测试方法即可
此教程只是针对我个人的情况以及成功案例进行一个记录,并不具有普适性,如果按照我的方案运行还有问题,欢迎评论区随时交流👏。