构建、IDEA 与测试

模块与产物

模块	用途	是否放生产 `plugins/`
`sealattributes-api`	公共无平台 API	否，compileOnly
`sealattributes-core`	聚合、战斗、来源、资源核心	否，已合并主 JAR
`sealattributes-adapters:mythicmobs`	Mythic 适配	否，已合并主 JAR
`sealattributes-paper`	主运行插件	是
`sealattributes-douluo`	可选启动扩展	放 `extensions/`，不放根 plugins
performance/compatibility/verification probes	验证工具	否

根版本 1.0.9，Kotlin 2.3.21，Gradle Wrapper 8.14.3，Java toolchain/JVM target 21。

Windows 完整构建

powershell

cd D:\path\to\SealAttributes
java -version
.\gradlew.bat --version
.\gradlew.bat clean check --rerun-tasks

预期 BUILD SUCCESSFUL。主 JAR：

text

sealattributes-paper/build/libs/SealAttributes-1.0.9.jar

构建通过只证明当前自动化任务；不能替代本轮 MySQL、真实服务器或正式部署。

MySQL 条件测试

测试使用环境变量指向隔离 MySQL，不能用生产库：SEALATTRIBUTES_TEST_MYSQL_URL、SEALATTRIBUTES_TEST_MYSQL_USER（缺省 root）和 SEALATTRIBUTES_TEST_MYSQL_PASSWORD（缺省空）。先创建一次性数据库，再运行目标 test；结束后核对测试清理。Windows 与 WSL 的 127.0.0.1 属于不同网络命名空间，数据库和 Java 最好在同一环境运行。

如果 MySQL 条件未提供，测试会 skip；“总任务成功”不代表 MySQL 覆盖执行。检查 JUnit XML 的 skipped 数，而不是只看 Gradle 最后一行。

IDEA 导入

IDEA 使用 JDK 21；Gradle JVM 也选同一个真实 JDK，不选 Microsoft Store stub；
从根 settings.gradle.kts 打开项目；
使用 Gradle Wrapper，不改成本机未知 Gradle；
Reload All Gradle Projects；
检查 Kotlin/Java language level 与 Gradle toolchain；
若 API consumer 项目红字，先确认 mavenLocal()/私有仓库确实有 cn.seal:sealattributes-api:1.0.9。

“CLI 能过但 IDEA 红”排错

CLI build 和 IDEA 模型是两套证据。按顺序：

File > Sync Project with Gradle Files；
查看 Gradle Sync 日志中第一条依赖/verification 错误；
确认 IDE Gradle JVM=21、offline mode 未误开；
检查 dependency verification metadata 是否拒绝新 artifact；
在 Gradle 工具窗确认所有子模块存在；
必要时 File > Invalidate Caches，但先保存同步日志，不能把它当首选万能修复；
最终以编辑器 import 解析、Gradle model 和实际编译三者都正常为准。

测试层级必须分开

层级	能证明	不能证明
单元/契约测试	构造器、公式、状态、序列化、并发契约	Paper 事件、真实依赖、网络数据库
Gradle `check`	当前源码在当前 JDK 构建	服务器可启动、玩家可登录
条件 MySQL 测试	指定 MySQL 的 schema/CRUD	生产网络、权限与负载
隔离真实服	指定 Paper/Leaf 与依赖的生命周期	其他平台/版本或正式流量
正式部署复核	某一 JAR/配置在目标服启动	后续改动仍然有效

真实服最小流程：干净启动、doctor、玩家登录 READY、装备、战斗、治疗、重登、配置重载、数据库中断/恢复演练、正常停服端口释放。记录 JAR SHA、完整版本和日志。

兼容策略

API 以 baseline 比较语义版本，consumer 用 compileOnly 并做编译 fixture。升级前比较公开签名、重新编译第三方插件和扩展，再用目标平台实测。不要因为 api-version: 1.21 就推断所有未来 1.21.x 构建自动兼容。

构建、IDEA 与测试 ​

模块与产物 ​

Windows 完整构建 ​

MySQL 条件测试 ​

IDEA 导入 ​

“CLI 能过但 IDEA 红”排错 ​

测试层级必须分开 ​

兼容策略 ​