3. 版本声明方式：硬编码版本、变量引用、扩展属性、gradle.properties 统一管理

Gradle 构建脚本中依赖的版本号声明看似简单，但不同的声明方式直接影响项目的可维护性、团队协作效率以及构建的稳定性。本章将系统梳理四种主流版本声明方式，从原理出发，结合代码配置与调试建议，帮助你在实际项目中做出合理选择。

3.1 四种声明方式概述

根据版本号书写位置和复用策略，Gradle 支持由低到高四种抽象级别的版本声明方式：

3.2 硬编码版本

最直接的声明方式：在 dependencies 块中直接写入版本字符串。例如：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web:2.7.18'
    implementation 'com.google.guava:guava:32.1.2-jre'
}

3.3 变量引用

在脚本中使用 def 或 ext 定义变量，并在依赖声明中引用变量名：

def springBootVersion = '2.7.18'
def guavaVersion = '32.1.2-jre'

dependencies {
    implementation "org.springframework.boot:spring-boot-starter-web:$springBootVersion"
    implementation "com.google.guava:guava:$guavaVersion"
}

变量作用域取决于定义位置：

• 脚本局部变量（def）：仅在当前 build.gradle 文件内有效。
• 根项目 ext 属性：被所有子模块继承，适合多模块项目。

3.4 扩展属性（ext）

在 build.gradle 的 ext 块中集中声明所有依赖版本号，子模块通过 rootProject.ext 或直接使用属性名访问（若父项目已 apply false 则需全路径）：

// 根项目 build.gradle
ext {
    springBootVersion = '2.7.18'
    guavaVersion = '32.1.2-jre'
    lombokVersion = '1.18.30'
}

// 子模块 build.gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-web:${springBootVersion}"
    implementation "com.google.guava:guava:${guavaVersion}"
}

扩展属性天然支持跨模块共享，但根项目的 ext 块会随项目增大而膨胀，且改动后需重新加载脚本。

3.5 gradle.properties 统一管理

将版本号移至项目根目录的 gradle.properties 文件中，以键值对形式存放。构建脚本通过 project.properties['key'] 或直接在字符串中引用（Gradle 会自动将属性值作为项目属性注入）：

# gradle.properties
springBootVersion=2.7.18
guavaVersion=32.1.2-jre
lombokVersion=1.18.30

// build.gradle
dependencies {
    implementation "org.springframework.boot:spring-boot-starter-web:${springBootVersion}"
    implementation "com.google.guava:guava:${guavaVersion}"
}

此方式的优势：

• 完全解耦：版本配置与构建逻辑分离，版本清单一目了然。
• CI/CD 友好：可通过 Jenkins、GitHub Actions 等工具动态替换 gradle.properties 中的值，实现环境差异化版本。
• 团队协作：新人只需修改 gradle.properties 即可完成版本升级，无需深入理解构建脚本。

3.6 四种方式的决策流程

下面这张 SVG 框架图展示了从硬编码到 gradle.properties 的演进路径，以及在多模块/企业级场景中的推荐选择逻辑。

3.7 常见错误与调试

• 属性引用未解析：使用 ${propertyName} 时，Gradle 会按 项目属性 → ext → gradle.properties 的顺序查找。若属性名拼写错误，Gradle 会在运行时抛出 MissingPropertyException。建议启用 --info 或 --stacktrace 日志定位。
• gradle.properties 不生效：检查文件是否放置在项目根目录（与 build.gradle 同级），不要在 ~/.gradle/ 的全局配置文件中混淆。
• 变量作用域冲突：在子模块中同名的 def 变量会遮蔽父项目的 ext 属性，导致版本不一致。推荐统一使用 ext 或 gradle.properties 避免作用域问题。

3.8 性能与稳定性考量

从构建性能角度，四种方式对构建时长几乎没有差异，因为版本解析只在配置阶段完成。但从团队协作的稳定性看，推荐遵循以下演进路线：

1. 阶段一：单模块原型 → 使用变量引用。
2. 阶段二：模块拆分 → 迁移至根项目 ext 扩展属性。
3. 阶段三：团队规模 > 3 人/接入 CI → 统一迁移至 gradle.properties，配合 buildSrc 或 version-catalog（后续章节详述）实现版本平台化管理。