版本约束与控制

源：Gradle 官方文档 - Dependency Constraints

依赖约束提供了一种推荐依赖版本的方式，而不强制覆盖，适合在不破坏依赖解析的前提下统一版本。

依赖约束概念

约束 vs 强制版本

强制版本：

configurations.all {
    resolutionStrategy {
        force("com.example:library:2.0")
    }
}

依赖约束：

dependencies {
    constraints {
        implementation("com.example:library:2.0")
    }
}

区别：

特性	force	constraints
优先级	强制覆盖	推荐版本
灵活性	低	高
冲突处理	覆盖所有	参与解析
推荐度	⭐	⭐⭐⭐

---

使用依赖约束

基本语法

dependencies {
    constraints {
        implementation("com.squareup.okhttp3:okhttp:4.12.0")
    }
}

带原因说明

dependencies {
    constraints {
        implementation("com.squareup.okhttp3:okhttp:4.12.0") {
            because("统一 OkHttp 版本到 4.12.0")
        }
    }
}

严格版本约束

dependencies {
    constraints {
        implementation("com.example:library") {
            version {
                strictly("2.0")
            }
            because("2.1+ 有兼容性问题")
        }
    }
}

---

版本选择器

推荐版本（prefer）

dependencies {
    constraints {
        implementation("com.example:library") {
            version {
                prefer("2.0")
            }
        }
    }
}

行为：推荐使用 2.0，但可以被更高版本覆盖

要求版本（require）

dependencies {
    constraints {
        implementation("com.example:library") {
            version {
                require("2.0")
            }
        }
    }
}

行为：要求至少是 2.0 版本

严格版本（strictly）

dependencies {
    constraints {
        implementation("com.example:library") {
            version {
                strictly("2.0")
            }
        }
    }
}

行为：必须是 2.0，不接受其他版本

拒绝版本（reject）

dependencies {
    constraints {
        implementation("com.example:library") {
            version {
                reject("1.0", "1.1")
            }
            because("1.0 和 1.1 有严重 bug")
        }
    }
}

---

版本范围

范围语法

dependencies {
    constraints {
        implementation("com.example:library") {
            version {
                require("[1.0, 2.0)")  // >= 1.0 且 < 2.0
            }
        }
    }
}

范围符号：

符号	说明	示例
[1.0, 2.0]	闭区间	>= 1.0 且 <= 2.0
[1.0, 2.0)	左闭右开	>= 1.0 且 < 2.0
(1.0, 2.0]	左开右闭	> 1.0 且 <= 2.0
(1.0, 2.0)	开区间	> 1.0 且 < 2.0

实用范围

dependencies {
    constraints {
        // 1.x 系列
        implementation("com.example:library") {
            version {
                require("[1.0, 2.0)")
            }
        }
        
        // 最低版本
        implementation("com.example:other") {
            version {
                require("1.5+")
             }
        }
    }
}

---

平台约束

使用平台定义约束

定义平台：

// platform/build.gradle.kts
plugins {
    `java-platform`
}

dependencies {
    constraints {
        api("com.squareup.okhttp3:okhttp:4.12.0")
        api("com.squareup.retrofit2:retrofit:2.11.0")
        api("com.google.code.gson:gson:2.10.1")
    }
}

使用平台：

dependencies {
    implementation(platform(project(":platform")))
    
    // 无需指定版本
    implementation("com.squareup.okhttp3:okhttp")
    implementation("com.squareup.retrofit2:retrofit")
}

外部平台（BOM）

dependencies {
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.9.22"))
    
    implementation("org.jetbrains.kotlin:kotlin-stdlib")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
}

---

实战案例

案例1：统一 Kotlin 版本

dependencies {
    constraints {
        implementation("org.jetbrains.kotlin:kotlin-stdlib") {
            version {
                strictly("1.9.22")
            }
            because("项目统一使用 Kotlin 1.9.22")
        }
    }
}

案例2：避免有问题的版本

dependencies {
    constraints {
        implementation("com.squareup.okhttp3:okhttp") {
            version {
                reject("4.10.0")
            }
            because("4.10.0 存在内存泄漏")
        }
    }
}

案例3：版本范围控制

dependencies {
    constraints {
        implementation("androidx.compose.ui:ui") {
            version {
                require("[1.5.0, 1.6.0)")
            }
            because("1.6.0+ 需要升级 compileSdk")
        }
    }
}

案例4：多模块版本对齐

根项目：

// build.gradle.kts (project)
subprojects {
    configurations.all {
        dependencies.constraints {
            implementation("androidx.core:core-ktx:1.15.0") {
                because("统一 AndroidX Core 版本")
            }
        }
    }
}

---

约束优先级

解析顺序

优先级从高到低：

• strictly 严格版本
• reject 拒绝版本
• require 要求版本
• prefer 推荐版本

冲突示例

dependencies {
    // 模块 A 要求 2.0
    implementation("com.example:A:1.0") {
        // A 依赖 library:2.0
    }
    
    // 约束推荐 1.5
    constraints {
        implementation("com.example:library") {
            version {
                prefer("1.5")
            }
        }
    }
}

结果：使用 2.0（require 优先级高）

---

最佳实践

优先使用约束而非强制：

• 更灵活
• 参与依赖解析
• 不破坏传递依赖

使用平台（BOM）：

• 集中管理版本
• 简化配置
• 保证一致性

文档化约束原因：

constraints {
    implementation("com.example:library:2.0") {
        because("2.1+ 与当前 API 不兼容")
    }
}

避免过度约束：

• 仅约束关键依赖
• 允许合理的版本范围
• 定期审查约束

测试约束效果：

• 检查依赖树
• 验证版本是否符合预期
• 测试所有模块

---

调试约束

查看约束生效情况

./gradlew :app:dependencyInsight --dependency <name>

输出示例：

com.example:library:2.0 (by constraint)
   variant "runtime" [
      org.gradle.status = release
   ]
   Selection reasons:
      - By constraint : 统一版本到 2.0

查看所有约束

./gradlew :app:dependencies --configuration implementation

---

与其他机制对比

机制	用途	优先级	灵活性
force	强制版本	最高	低
constraints	推荐版本	中	高
platform	版本集合	中	高
exclude	排除依赖	-	中

选择建议：

• 默认使用 constraints
• 需要 BOM 使用 platform
• 最后手段使用 force