Realm Gradle插件实战从一行插件应用到多模块配置4个高频坑一次说清【免费下载链接】realm-javaRealm is a mobile database: a replacement for SQLite ORMs项目地址: https://gitcode.com/gh_mirrors/re/realm-javaRealm 是替代 SQLite 与 ORM 的移动数据库其 Gradle 插件realm-android会自动接管构建中的依赖注入、注解处理与字节码转换。读完你能在新项目 3 分钟跑通集成并掌握多模块、同步、Kotlin 三个场景的配置。Realm Gradle 插件在构建时到底干了什么插件源码入口就是Realm.kt这一个类但apply方法里连续做了四件事依赖自动注入给模块加realm-annotations注解、realm-annotations-processor代码生成器、realm-android-library运行时三组构件版本号统一跟随插件自身不用你手动对齐。编译期代码生成注解处理器为你的模型类生成代理类所以写模型时不需要碰任何 Proxy 代码。字节码转换注册 transformer 任务用 ClassPool 在构建期扫描全部类——多模块下能否找到模型全靠它。Kotlin 适配检测到kotlin-android插件后自动把代码生成器从annotationProcessor切到kapt含kaptAndroidTest。先看一眼被集成的库长什么样理解插件指向的运行时结构跑通它3步最小配置1. 加插件 classpath根目录build.gradle加一行即可版本号去仓库根目录的version.txt查buildscript { dependencies { classpath io.realm:realm-gradle-plugin:version } }2. 在 app 模块应用插件依赖就位后接下来是模块级配置。插件硬性要求com.android.application或com.android.library先于它生效否则直接抛异常所以 apply 顺序别写反apply plugin: com.android.application apply plugin: realm-android realm { syncEnabled false // 是否换成 object-server 同步版构件 }realm闭包只有syncEnabled和kotlinExtensionsEnabled两个开关。配置少不是遗漏——插件刻意把版本号和依赖坐标都收走了你只管这两个意图。3. 写一个模型类最小可运行的RealmObject没有任何手动注册步骤public class City extends RealmObject { PrimaryKey public String name; public int population; }然后执行./gradlew assembleDebug。构建产物里能找到处理器生成的代理类运行时Realm.getInstance即可直接查这个模型。三个场景化配置多模块下把模型放进 library模型放在 app 模块时处理器直接可见一旦挪进 library 模块字节码转换器就不一定能扫到现象是运行时查询该模型抛找不到对应 Proxy 类一类错误。解法是用RealmModule显式声明这也是我见过最高频的配置RealmModule(library true, classes {Cat.class, Dog.class}) public class DomesticAnimalsModule { }仓库里的examples/moduleExample就是这个形态library 模块放模型和 module 类app 模块正常应用插件即可。需要在线同步时接 Realm Object Server 的场景下运行时构件要从realm-android-library换成realm-android-library-object-server这个切换由插件读syncEnabled完成realm { syncEnabled true }依赖坐标不用自己改插件在构建前替换androidTest配置也会被同步处理——源码里专门留了注释解释为什么测试配置要手动再注入一遍。Kotlin 项目模块应用了kotlin-android时插件自动走 kaptkotlinExtensionsEnabled默认开启无需额外动作。纯 Java 模块走annotationProcessor两条路径对使用者透明。踩坑速查遇到下面四种现象按现象→原因→解法处理就行现象大概率原因解法构建报com.android.application or com.android.library plugin required模块没应用 Android 插件或 realm 插件 apply 在前先 applycom.android.*realm 插件只对 Android 模块生效报Android Gradle Plugin x is not supportedAGP 低于 7.4插件 apply 时硬校验版本升级 AGP或换用与该 AGP 匹配的旧版 Realm Java运行时查 library 里的模型报找不到类library 模块缺RealmModule(library true)声明加注解并显式列出全部模型类本地 JUnit 单测跑 Realm 代码崩出诡异错误运行配置缺验证与定位选项按下方截图配置 VM 选项和工作目录最后一条对应的配置在 Android Studio 的 Run/Debug Configuration 里给 JUnit 配置加 VM 选项-ea -noverify工作目录设为$MODULE_DIR$示例工程unitTestExample里附了这张配置截图如果io.realm构件真的出现版本冲突比如工程里混入了旧版运行时库强制拉平到插件版本configurations.all { resolutionStrategy { force io.realm:realm-android-library:version } }延伸入口gradle-plugin/src/main/kotlin/io/realm/gradle/Realm.kt插件唯一入口apply 的四步职责和构件切换逻辑都在这 160 行里读它比读文档快。realm-transformer/src/main/kotlin/io/realm/transformer/ByteCodeModifier.kt字节码转换任务实现多模块扫不到模型时从这里排查。realm/realm-annotations-processor/src/main/java/io/realm/processor/RealmProcessor.kt代理类生成主流程生成产物不符合预期时的第一站。examples/moduleExample官方多模块示例module 类按 Zoo / Domestic / AllAnimals 三种粒度的拆分方式值得直接抄。examples/unitTestExample对应上表单测配置README 里解释了-noverify为什么必须加。插件的价值在于把复杂度藏在了正确的位置你只写模型类依赖、代码生成、转换全部发生在构建期。把 classpath 和 apply 两行加进项目跑一次./gradlew assembleDebug构建目录里出现生成的代理类就说明集成成了。【免费下载链接】realm-javaRealm is a mobile database: a replacement for SQLite ORMs项目地址: https://gitcode.com/gh_mirrors/re/realm-java创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考