更新Bitbucket镜像钩子插件时如何免重启解决类转换异常？

问题背景 #

我基于开源的 Bitbucket Server 镜像仓库钩子插件源码做功能定制，完成开发后先卸载了环境中原有的旧版本插件，再安装编译好的新版本包。操作完成后 Bitbucket 持续抛出如下类转换异常：

java.lang.ClassCastException: com.englishtown.bitbucket.hook.MirrorRequest cannot be cast to com.englishtown.bitbucket.hook.MirrorRequest
        at com.atlassian.stash.internal.concurrent.HazelcastBucketedExecutor.schedule(HazelcastBucketedExecutor.java:63)
        at com.atlassian.stash.internal.concurrent.DelegatingInternalBucketedExecutor.schedule(DelegatingInternalBucketedExecutor.java:24)
        at com.englishtown.bitbucket.hook.MirrorRepositoryHook.lambda$schedulePushes$0(MirrorRepositoryHook.java:177)
        at java.util.ArrayList.forEach(ArrayList.java:1259)
        at com.englishtown.bitbucket.hook.MirrorRepositoryHook.schedulePushes(MirrorRepositoryHook.java:177)
        at com.englishtown.bitbucket.hook.MirrorRepositoryHook.validate(MirrorRepositoryHook.java:138)
        at com.atlassian.stash.internal.hook.repository.DefaultRepositoryHookService.validateSettings(DefaultRepositoryHookService.java:896)
        at com.atlassian.stash.internal.hook.repository.DefaultRepositoryHookService.lambda$enable$0(DefaultRepositoryHookService.java:203)
        at java.util.Optional.ifPresent(Optional.java:159)

这类错误是 Bitbucket Server 插件热更新场景下的经典类加载冲突问题：Bitbucket 底层依赖 Hazelcast 分布式执行器完成跨节点的任务调度，插件提交的镜像同步任务会被序列化后存入共享缓存。卸载旧插件时，对应的类加载器会被销毁，但缓存中残留的、由旧类加载器加载的任务对象没有被同步清理；新插件启动后，会用全新的类加载器加载和旧版本同包同名的 MirrorRequest 类，在 JVM 的类加载规则中，不同类加载器加载的全限定名完全相同的类属于两种完全独立的类型，最终就会触发“同一个类无法强转为自身”的奇怪报错。
社区目前能查到的临时解决思路有两种：一是重启整个 Bitbucket 实例清空全部缓存，二是给所有业务类加版本后缀（比如把 MirrorRepositoryHook.java 重命名为 MirrorRepositoryHookV331.java），避开旧类名的缓存匹配。但两种方案的代价都不低：重启会中断所有线上代码托管服务，加版本后缀会侵入业务代码，后续迭代还要持续维护特殊命名规则。

更优雅的可落地方案 #

• 正式上线新版本时，跳过“卸载原插件再安装”的操作流程，直接在 Bitbucket 插件管理页上传新插件包做覆盖式升级。覆盖升级过程中 Bitbucket 会复用插件原有的类加载器上下文，不会出现旧类加载器销毁、残留缓存对象引用悬空的问题。
• 给插件绑定 Bitbucket 提供的插件生命周期接口，实现关联缓存的主动清理逻辑：插件被停用、重新激活时，自动遍历清理 Hazelcast 容器中属于当前插件的所有调度任务、缓存条目，不需要重启整个 Bitbucket 实例就能清除残留脏数据。
• 给所有需要被 Hazelcast 序列化、缓存的插件业务类，显式指定独立的序列化版本号，不要依赖类名自动匹配序列化对象。只要类结构发生变更，就同步更新对应的版本号，Hazelcast 反序列化时遇到版本不匹配的残留旧对象会自动淘汰，从机制上避免类加载冲突。
• 日常开发调试阶段，使用 Bitbucket 官方插件开发工具的热加载模式测试功能，热加载流程会自动同步清理插件关联的所有缓存上下文，从开发流程上避免旧数据残留。

内容的提问来源于stack exchange，提问作者Basil