4.6 KiB
架构与兼容测试
项目基线为 Java 21、Spigot API 1.21.1 和 api-version: '1.21'。插件通过 Bukkit 插件描述文件加载。编译产物与兼容性探针分开构建,探针只安装到测试服务端。
核心适配
CoreDetector读取可用的 Paper 构建元数据、核心报告名称、版本和 Bukkit API 版本。Folia 的运行时类作为额外信号。NativeSchedulerApi检查 Global、Region、Entity 和 Async 调度 API 的方法签名,并获取服务端调度器实例。调用通过反射桥隔离,通用 API 只使用 Bukkit 类型。- 完整原生 API 上按核心选择
PaperSchedulerAdapter或FoliaSchedulerAdapter。Folia 通过原生调度 API 执行,保留实体调度器的 retired 语义。 - 缺少原生调度能力时,只有 Bukkit 调度器可用且插件在主线程启用的核心才能进入 Bukkit 路径。识别到 Paper/Folia 或探测到不完整的原生调度接口时会停用插件并给出原因。
- 适配器关闭时拒绝新的任务,取消尚未运行的任务。已进入执行的回调由调用方负责正常结束。
发布状态取决于完整的集成、压力、故障与稳定性证据。阶段性 JAR 中包含测试服务端加载插件所需的 Folia 声明。
审核路径
同步过滤基于只读词库快照,保留标准化文本到原文的索引映射。聊天和书本分别在各自事件入口提取数据。书本异步审核后由实体调度器应用结果,并再次核对书本所在槽位和原稿。延迟公开聊天使用提交时的受众快照,并为每位接收者在各自实体调度器发送。延迟私聊从发送者的实体调度器执行已审核的消息命令。
HTTP、SMTP、SQLite 使用独立的有界执行机制。异步结果通过实体调度器应用到玩家。配置加载和词库编译先构建完整快照,验证后一次性交换,正在执行的任务持有提交时的配置。
重现兼容探针
需要 Java 21、Gradle Wrapper、Python 3.11 或更新版本、Node.js 24、Git、curl,以及服务端和客户端依赖下载权限。以下示例使用 Windows PowerShell。请在启动前阅读 Minecraft EULA。脚本会为本地测试实例写入 eula=true。
.\gradlew.bat build compatProbeJar
python scripts/fetch-servers.py --version 1.21.8 --download
npm --prefix .test-servers/client install --save-exact minecraft-protocol@1.68.0
$java = Join-Path $env:JAVA_HOME 'bin/java.exe'
python scripts/run-compat.py --java $java `
--plugin build/libs/ItxiaohuiContentGuard-0.2.0-dev.jar `
--probe build/libs/ItxiaohuiContentGuard-0.2.0-dev-compat-probe.jar `
--client .test-servers/client/node_modules/minecraft-protocol `
--features `
--target paper/1.21.8 --target purpur/1.21.8 --target folia/1.21.8 `
--target leaves/1.21.8 --target spigot/1.21.8
Spigot 用 python scripts/build-spigot.py --java $java --version 1.21.8 调用上游 BuildTools。兼容脚本为每次运行生成各自的配置、插件目录、世界和启动脚本。在同一个独立目录内正常重启一次。服务器在回环地址上运行,使用测试客户端协议登录。
复现压力与稳定性
python -m pip install -r scripts/requirements-test.txt
python scripts/run-stress.py --java $java `
--plugin build/libs/ItxiaohuiContentGuard-0.2.0-dev.jar `
--probe build/libs/ItxiaohuiContentGuard-0.2.0-dev-compat-probe.jar `
--client .test-servers/client/node_modules/minecraft-protocol `
--target folia/1.21.8 --spread
--players 1,10,50,100 是默认分组。--seconds 指定每组负载持续时间,--interval-ms 指定各轮发消息间隔。
稳定性测试使用 --name stability-30m、stability-2h 或 stability-8h,分别设置持续秒数 1800、7200 或 28800。
故障验证可使用 --name fault --players 1 --seconds 1 --interval-ms 1300 --faults --forced-restart。
额外实服场景可由 run-compat.py 的 --profile、--mode 和 --smtp-mode 指定。TLS 夹具需要 OpenSSL 和 Java 的 keytool。
完成后用 python scripts/summarize.py 更新汇总矩阵。