任务图与执行顺序

3.1 任务图构建原理

Gradle 在执行任何任务之前，会先将所有声明的任务及其依赖关系构建为一个 有向无环图（DAG，Directed Acyclic Graph）。该图是任务调度的核心数据结构，决定了任务以何种顺序被执行、哪些任务可以并行、哪些必须串行等待。

当 Gradle 解析构建脚本时，每个通过 tasks.register() 或 tasks.create() 声明的任务都会在内部注册为一个 任务节点。节点间通过 dependsOn、mustRunAfter、shouldRunAfter 以及 task.finalizedBy 等声明形成 有向边。构建结束后，整个图必须是严格的 DAG——不允许存在任何环形依赖。

下面是 Gradle 任务图构建核心流程的示意：

3.2 任务排序规则

Gradle 的 TaskSorter 组件对 DAG 执行拓扑排序时，严格遵循以下优先级（从高到低）：

排序器在处理上述规则时，会首先消除所有 dependsOn 边，然后嵌入 mustRunAfter 边，再尝试嵌入 shouldRunAfter 边。如果 shouldRunAfter 导致环，排序器会 静默丢弃该约束 并回退到无约束顺序。

3.3 mustRunAfter 与 shouldRunAfter 深度对比

这两个 API 都用于在 不建立依赖关系 的前提下控制任务执行顺序，但语义强度完全不同。下表从多个维度进行对比：

3.4 具体配置语法与示例

在 Groovy 构建脚本中，mustRunAfter 和 shouldRunAfter 的典型用法如下：

// 单模块示例
task clean {
    doLast {
        println 'Cleaning...'
    }
}

task compile {
    doLast {
        println 'Compiling...'
    }
}

task test {
    doLast {
        println 'Testing...'
    }
}

// 必须关系：clean 必须在 compile 之前
compile.mustRunAfter clean

// 建议关系：test 尽量在 compile 之后
test.shouldRunAfter compile

多模块跨项目配置时，需要引用其他模块的任务路径：

// 在模块 B 的 build.gradle 中
tasks.named('test') {
    // 模块 B 的 test 必须晚于模块 A 的 assemble
    mustRunAfter project(':module-a').tasks.named('assemble')
}

// 在模块 C 的 build.gradle 中
tasks.named('integrationTest') {
    // 模块 C 的 integrationTest 尽量晚于模块 B 的 test
    shouldRunAfter project(':module-b').tasks.named('test')
}

使用 Kotlin DSL 时，语法略有不同：

// build.gradle.kts
tasks.register("validate") {
    doLast { println("Validating...") }
}

tasks.register("deploy") {
    doLast { println("Deploying...") }
}

// 必须关系
tasks.named("deploy") {
    mustRunAfter("validate")
}

// 建议关系
tasks.named("validate") {
    shouldRunAfter("lint")
}

3.5 任务排序的并行优化考量

shouldRunAfter 的核心价值在于 允许 Gradle 在不会引起副作用的情况下突破顺序约束，从而最大化并行度。考虑以下场景：

• 有硬件资源限制： 两台测试机共享同一个数据库，integrationTest 必须互斥运行——使用 mustRunAfter 强制串行。
• 无资源冲突： 单元测试 test 和代码检查 lint 可以完全并行，但希望 lint 在 test 之后执行以便日志更有序——使用 shouldRunAfter，并行度不会受损。
• 多模块聚合： 在根项目中，allprojects 或 subprojects 内声明的任务排序，推荐优先使用 shouldRunAfter，避免跨模块的强排序导致不必要的构建阻塞。

3.6 常见错误与诊断清单

下表列出了任务排序配置中最常遇到的 5 类错误及其修复策略：

3.7 综合实战：多模块任务调度配置

以下是一个真实的多模块 Kotlin 项目部分配置，展示如何组合使用 dependsOn、mustRunAfter 和 shouldRunAfter：

// root/build.gradle.kts
subprojects {
    tasks.register("qualityCheck") {
        dependsOn("lint", "detekt")
    }

    tasks.named("test") {
        mustRunAfter("compileKotlin")
    }

    tasks.named("integrationTest") {
        shouldRunAfter("test")
        mustRunAfter("compileKotlin")
    }
}

// 模块 A 额外配置
project(":module-a") {
    tasks.named("integrationTest") {
        // 跨模块：A 的集成测试必须晚于 B 的单元测试
        mustRunAfter(project(":module-b").tasks.named("test"))
    }
}

// 模块 C 额外配置
project(":module-c") {
    tasks.named("deploy") {
        // 软性提示：deploy 尽量在 qualityCheck 之后
        shouldRunAfter(project(":module-a").tasks.named("qualityCheck"))
    }
}

执行 gradle :module-c:deploy --dry-run 可以预览最终的任务排序顺序。从日志中可以看到 compileKotlin → test（mustRunAfter）→ qualityCheck（dependsOn 链）→ deploy（shouldRunAfter） 的完整轨迹。