HNCore v3.4.3

• 发布日期：2024-04-28
• 发布提交：5ca4b5f
• 版本定位：内部重构优化，新增运行时能力探测工具，增强 API 实用性

版本概述

v3.4.3 是一个内部优化版本，主要目标是：

1. 统一运行时探测 - 新增 RuntimeCapability 工具类统一管理运行时 API 探测
2. 消除重复代码 - 重构多个模块使用统一探测机制，删除重复的反射工具方法
3. 增强工具类 - ColorUtil 新增 Component 转换方法，SmartFormulaParser 支持公式模式智能识别
4. 提升代码质量 - 完善单元测试覆盖，优化代码结构

新增功能

1. RuntimeCapability 运行时能力探测工具

提交：35d2a0c（2024-04-28，refactor: 统一运行时能力探测，新增 RuntimeCapability 工具类）

新增 RuntimeCapability 工具类，统一管理所有运行时 API 探测逻辑：

// 检测类是否存在
if (RuntimeCapability.hasClass("io.papermc.paper.event.player.AsyncChatEvent")) {
    // 使用 Paper 聊天事件
}

// 检测方法是否存在
if (RuntimeCapability.hasMethod(CommandSender.class, "sendMessage", Component.class)) {
    // 使用 Adventure Component 发送消息
}

// 查找方法（包括接口方法）
Method method = RuntimeCapability.findMethod(serviceClass, "getCurrency", String.class);

预定义探测方法：

• hasAdventureComponentSendMessage() - 检测是否支持 Adventure Component 消息
• hasPaperAsyncChat() - 检测是否支持 Paper AsyncChatEvent
• hasFoliaRegionScheduler() - 检测是否支持 Folia 区域化调度
• hasServerGetServerName() - 检测 Server 类是否有 getServerName() 方法

特性：

• 探测结果自动缓存，避免重复反射
• 支持跨接口查找方法
• 线程安全的并发缓存

2. ColorUtil 新增 Component 转换方法

提交：35d2a0c

新增三个实用方法：

// 字符串转 Component（支持颜色代码和十六进制）
Component component = ColorUtil.toComponent("&a绿色 &#FF5733橙色");

// Component 转字符串（保留颜色代码）
String text = ColorUtil.fromComponent(component);

// 提取纯文本（移除所有颜色代码）
String plain = ColorUtil.toPlainText("&a绿色文本");

3. SmartFormulaParser 公式模式智能识别

提交：b039d81（2024-04-28，[优化] 下沉公式模式解析工具到 Core）

新增 SmartFormulaParser 工具类，支持根据脚本内容自动识别公式模式：

// 自动识别模式
FormulaScriptMode mode = SmartFormulaParser.parseMode("return total * 2");
// 返回 GROOVY

mode = SmartFormulaParser.parseMode("total * 0.5");
// 返回 EXPRESSION

// 优先使用显式配置，无效时自动识别
mode = SmartFormulaParser.parseMode("groovy", "1 + 2");
// 返回 GROOVY（使用显式配置）

mode = SmartFormulaParser.parseMode("invalid-mode", "return total");
// 返回 GROOVY（配置无效，自动识别）

// 检测是否为纯数字常量
boolean isPure = SmartFormulaParser.isPureNumber("123.45");
// 返回 true

// 生成适合展示的描述
String desc = SmartFormulaParser.getDescription(FormulaScriptMode.EXPRESSION, "123");
// 返回 "常量: 123"

识别规则：

• 包含 Groovy 关键字（return/def/class/if/for 等）→ GROOVY
• 包含方法调用（obj.method()）或 lambda（->）→ GROOVY
• 其他情况 → EXPRESSION

内部优化

1. 重构运行时探测逻辑

提交：35d2a0c

重构以下模块使用统一的 RuntimeCapability：

DefaultEconomyBridge：

• 删除自定义的 findMethod() 和 getAllInterfaces() 方法（共 28 行）
• 统一使用 RuntimeCapability.findMethod()

FeatureScriptManager：

• 使用 RuntimeCapability.hasMethod() 和 findMethod() 替代手动反射
• 简化 hasInstanceHook() 和 hasStaticHook() 方法

BaikirutoItemLibraryProvider：

• 使用 RuntimeCapability.hasClass() 提前检测类存在性
• 简化 resolveApi() 方法

DefaultPlaceholderGateway：

• 使用 RuntimeCapability.hasClass() 和 findMethod() 替代手动反射
• 提高代码可读性

PluginScanner：

• 使用 RuntimeCapability.hasClass() 检测 PluginClassLoader 是否存在
• 增强兼容性检查

代码质量提升：

• 消除重复代码：删除多处自定义的反射工具方法
• 统一异常处理：所有运行时探测都通过 RuntimeCapability 统一处理
• 提高可维护性：未来新增运行时探测只需在 RuntimeCapability 中添加
• 性能优化：探测结果自动缓存，避免重复反射

2. 新增单元测试

提交：5ca4b5f（2024-04-28，test: 新增 ColorUtil 和 DefaultAudienceService 单元测试）

新增测试覆盖：

ColorUtilTest：

• 测试传统颜色代码转换（&a → §a）
• 测试十六进制颜色代码转换（&#FFAA00 → §x§F§F§A§A§0§0）

DefaultAudienceServiceTest：

• 测试 Adventure Component 消息发送
• 测试降级到传统字符串消息发送

SmartFormulaParserTest：

• 测试纯数字检测
• 测试模式自动识别
• 测试显式配置优先级
• 测试公式描述生成

兼容性说明

对下游的影响

完全兼容 - 所有改动都是内部实现优化，不影响公开 API：

1. RuntimeCapability 是全新工具类，不替换任何现有 API
2. ColorUtil 新增方法是纯增量，原有方法完全未动
3. 内部实现类修改（DefaultAudienceService、DefaultEconomyBridge 等）不在公开接口中
4. 下游插件无需任何修改即可升级

API 变更

新增 API（hncore-api）：

• RuntimeCapability - 运行时能力探测工具类
• ColorUtil.toComponent(String) - 字符串转 Component
• ColorUtil.fromComponent(Component) - Component 转字符串
• ColorUtil.toPlainText(String) - 提取纯文本
• SmartFormulaParser - 公式模式智能识别工具类

无破坏性变更

升级指南

从 v3.4.2 升级

直接替换 JAR 文件即可，无需修改配置或代码。

推荐使用新 API

如果你的插件需要运行时探测功能，推荐使用新的 RuntimeCapability：

// 旧方式（不推荐）
try {
    Class.forName("io.papermc.paper.event.player.AsyncChatEvent");
    // 使用 Paper API
} catch (ClassNotFoundException e) {
    // 降级处理
}

// 新方式（推荐）
if (RuntimeCapability.hasPaperAsyncChat()) {
    // 使用 Paper API
} else {
    // 降级处理
}

技术细节

改动统计

提交 35d2a0c：

• 19 个文件修改
• 新增 323 行
• 删除 108 行
• 新增 RuntimeCapability 工具类（150 行）

提交 b039d81：

• 新增 SmartFormulaParser 工具类（85 行）
• 新增完整单元测试（67 行）

提交 5ca4b5f：

• 新增 2 个测试类
• 新增 84 行测试代码

性能优化

1. 探测结果缓存 - RuntimeCapability 使用 ConcurrentHashMap 缓存探测结果，同一探测在整个 JVM 生命周期内只执行一次
2. 减少反射调用 - 统一探测机制避免了重复的反射查找
3. 线程安全 - 使用 computeIfAbsent 保证并发安全

相关链接

• GitHub Release
• 完整提交历史
• 开发者 API 文档