4. 增量编译原理与开启

增量编译是 Gradle 多模块项目提速的核心支柱之一，其本质是只重新编译实际发生变化的源文件及其直接依赖，而非全量重编。
本章从底层快照机制、编译回避（Compile Avoidance）到注解处理器优化，逐层拆解原理与实战配置。

4.1 增量编译的三层原理

4.2 开启增量编译的实现流程

1. 检查 Gradle 版本：增量编译自 Gradle 3.x 起实验性开启，4.10+ 默认启用。确认版本 ≥ 6.0 以获得稳定支持。
2. 确认 Java 编译任务已允许增量：默认 compileJava 任务已开启 options.incremental = true（早期版本需显式设置）。
3. 启用 Compile Avoidance：将依赖模块以 API / implementation 方式声明，Gradle 自动基于 ABI 快照判断。
4. 标记注解处理器为增量：在处理器 META-INF 中声明支持增量类型（isolating 或 aggregating）。
5. 验证生效：执行 gradle compileJava --info 查看日志中是否包含 “Incremental compilation” 及 “Compile avoidance” 关键字。

4.3 关键配置与 API

build.gradle 增量编译全局开关（通常不需要手动设置，但可强制开启）：

tasks.withType(JavaCompile).configureEach {
    options.incremental = true
    options.compilerArgs << "-Xlint:unchecked"   // 示例，不影响增量
}

依赖声明对 Compile Avoidance 的影响：

注解处理器增量元信息文件：
在处理器 Jar 的 META-INF/gradle/incremental.annotation.processors 中写入：

com.example.MyAnnotationProcessor,isolating
com.example.AnotherProcessor,aggregating,someOption

格式：全限定类名,类型[,选项键值对]。类型为 isolating 或 aggregating。

调试快照信息：

// 在 build.gradle 中临时打开快照日志
gradle.startParameter.setLogLevel(LogLevel.INFO)
// 或通过命令行
gradle compileJava --info 2>&1 | grep -E "(Snapshot|incremental|avoidance)"

4.4 调试增量编译行为

🔧 粒度调试方法：

• 使用 --rerun-tasks 强制全量重编作为对照组，对比耗时。
• 借助 build/classes/java/main/META-INF/gradle/ 下的 ABI 快照文件查看具体差异。
• 在 gradle.properties 中设置 org.gradle.internal.compile.incremental=true（强制开启，Gradle 5.0+）。

4.5 部署与多模块项目注意事项

1. CI/CD 环境中建议开启 --no-build-cache 时仍保留增量：增量编译在本地开发者环境下收益最大，CI 若使用 build cache 则增量作用较小，但不应禁用。
2. 避免将整个项目放在一个编译任务中：合理拆分模块，每个模块独立增量编译，利用并行执行。
3. 注解处理器增量必须由处理器开发者支持：若使用第三方处理器（如 Lombok、Dagger），需确认其是否支持 incremental processing。不支持时会在日志中警告。
4. Kotlin 项目注意：Kotlin 增量编译需额外开启 kotlin.incremental=true，且 KAPT 注解处理默认不支持增量（需手动配置）。

4.6 常见错误与解决

4.7 性能与稳定性优化建议

• 启用 Gradle 缓存并行快照：在 gradle.properties 中增加 org.gradle.parallel=true 和 org.gradle.caching=true，快照比对可并行执行。
• 减少不必要的文件监控：使用 exclude 过滤生成文件、测试资源等，避免快照内容膨胀。
• 针对注解处理器，使用隔离型（isolating）而非聚合型（aggregating）：隔离型只关注指定注解所在文件，聚合型需要扫描所有文件，增量粒度差。
• 定期清理过大的快照缓存：Gradle 会在 ~/.gradle/caches/transforms-* 中存储快照，长期运行后可能达到 GB 级，可配置 --max-workers 或定时脚本清理。
• 在 CI 上结合 Build Cache + 增量编译：虽然两者有重叠，但配合使用可在本地增量编译失败时仍能命中远程缓存。