Gradle 配置文件详解

🎯 核心概念

在 Gradle 构建系统中，这三个文件各司其职，共同完成项目的构建管理：

📊 三大配置文件对比

快速对比表

🏗️ settings.gradle 详解

核心作用

定位：项目的"组织架构图"，告诉 Gradle 这个项目包含哪些子模块。

执行时机：Gradle 构建的第一步，在任何其他脚本之前执行。

本项目实例分析

// 定义根项目名称rootProject.name='plat_index'// 包含子模块 - 扁平化声明include'ymt-generator'include'ymt-deploy'// ymt平台 - 三层架构include'ymt-platform'include'ymt-platform:ymt-common'// 通用层include'ymt-platform:ymt-common:ymt-common-core'// 核心工具include'ymt-platform:ymt-common:ymt-common-redis'// Redis组件// ... 更多通用模块include'ymt-platform:ymt-modules'// 业务层include'ymt-platform:ymt-modules:ymt-metadata'// 元数据模块include'ymt-platform:ymt-modules:ymt-quality'// 质量模块// ... 更多业务模块include'ymt-platform:ymt-application'// 应用层include'ymt-platform:ymt-application:ymt-admin-app'// 管理后台include'ymt-platform:ymt-application:ymt-monitor-app'// 监控应用// ... 更多应用模块

关键知识点

1. 模块路径语法

// 语法格式：父模块:子模块include'ymt-platform:ymt-common:ymt-common-core'// 等价于目录结构：// ymt-platform/// └─ ymt-common/// └─ ymt-common-core/

2. 项目名称的重要性

rootProject.name='plat_index'

影响：

• 生成的 JAR/WAR 文件名前缀
• IDEA/Eclipse 项目显示名称
• Maven 仓库发布的 artifactId（如未单独指定）

3. 本项目的模块架构

plat_index (根项目) ├─ ymt-generator # 代码生成器（独立模块） ├─ ymt-deploy # 部署工具（独立模块） ├─ ymt-jpom # 运维管理（独立模块） └─ ymt-platform # 核心平台（多层架构） ├─ ymt-common # 🔹 通用层（17个组件模块） │ ├─ ymt-common-core # 核心工具 │ ├─ ymt-common-redis # Redis封装 │ ├─ ymt-common-mybatis # MyBatis增强 │ └─ ... # 其他14个通用组件 ├─ ymt-modules # 🔹 业务层（7个业务模块） │ ├─ ymt-metadata # 元数据管理 │ ├─ ymt-quality # 质量管理 │ ├─ ymt-datasync # 数据同步 │ └─ ... # 其他4个业务模块 └─ ymt-application # 🔹 应用层（3个启动应用） ├─ ymt-admin-app # 管理后台 :8086 ├─ ymt-monitor-app # 监控服务 :8087 └─ ymt-snailjob-app # 定时任务 :8088

常见操作

添加新模块

// 在 settings.gradle 中添加include'ymt-platform:ymt-modules:ymt-new-module'

动态包含模块（高级用法）

// 根据条件包含模块if(System.getenv('INCLUDE_DEMO')=='true'){include'ymt-platform:ymt-modules:ymt-demo'}

⚙️ gradle.properties 详解

核心作用

定位：项目的"配置中心"，存储键值对形式的配置参数。

执行时机：在 settings.gradle 之后、build.gradle 之前加载。

特点：

• ✅ 简单的key=value格式
• ✅ 可被 build.gradle 中的变量引用
• ✅ 支持环境变量和系统属性
• ✅ 便于版本控制和团队协作

本项目实例分析

1. Gradle 性能优化配置

# JVM 参数 - 构建时的内存配置 org.gradle.jvmargs=-Xmx4g -Xms2g -XX:MaxMetaspaceSize=2g # 并行构建 - 多模块项目必开 org.gradle.parallel=true # 按需配置 - 只配置需要的模块 org.gradle.configureondemand=true # 构建缓存 - 避免重复构建 org.gradle.caching=true

解读：

• Xmx4g：最大堆内存 4GB（大型项目建议 4-8GB）
• parallel=true：并行构建，充分利用多核 CPU
• caching=true：启用增量构建，只编译改动的部分

2. 插件版本管理

# Spring Boot 插件版本 springBootPluginVersion=3.4.7 # 依赖管理插件版本 dependencyManagementPluginVersion=1.1.4

为什么放在这里？

// ❌ 错误：在 build.gradle 的 ext 块中定义ext{springBootPluginVersion='3.4.7'}// ❌ 问题：plugins 块执行时，ext 块还未初始化plugins{id'org.springframework.boot'version"$springBootPluginVersion"// 报错！}// ✅ 正确：在 gradle.properties 中定义// gradle.properties: springBootPluginVersion=3.4.7// ✅ build.gradle 中直接引用plugins{id'org.springframework.boot'version"$springBootPluginVersion"// 成功！}

3. 系统属性配置

# 系统级编码设置 systemProp.file.encoding=UTF-8 systemProp.console.encoding=UTF-8 systemProp.user.language=zh systemProp.user.country=CN

作用：这些配置会作为 JVM 系统属性传递，等价于：

java -Dfile.encoding=UTF-8 -Duser.language=zh -jar app.jar

4. 应用配置占位符

# 日志级别 logging.level=info # Spring 环境配置 profiles.active=dev # 监控服务账号 monitor.username=ymt monitor.password=ymt123

用途：这些值会在构建时替换到application.yml中的@...@占位符。

# application.ymllogging:level:org.dromara:@logging.level@# 构建后变成 infospring:profiles:active:@profiles.active@# 构建后变成 dev

配置层级

Gradle 会按优先级加载多个gradle.properties文件：

优先级从高到低： 1. 命令行参数 -Pprofiles.active=prod 2. ~/.gradle/ 用户主目录（全局配置） 3. 项目根目录 当前项目专属配置 ⭐ 4. GRADLE_USER_HOME Gradle 安装目录

常见使用场景

场景1：切换环境配置

# 开发环境 profiles.active=dev # 测试环境（注释当前，启用下面） # profiles.active=test # 生产环境 # profiles.active=prod

场景2：敏感信息管理

# ❌ 不要这样做（会提交到 Git） database.password=123456 # ✅ 正确做法：使用环境变量 database.password=${DB_PASSWORD}

配合.gitignore：

# 本地配置文件（不提交） gradle-local.properties

# gradle.properties（提交到 Git） database.password=placeholder # gradle-local.properties（本地覆盖，不提交） database.password=real_password_here

🔧 build.gradle 详解

核心作用

定位：项目的"构建脚本"，定义如何编译、测试、打包项目。

执行时机：在 settings.gradle 和 gradle.properties 之后执行。

特点：

• 🔹 使用 Groovy DSL（领域特定语言）
• 🔹 支持插件、依赖、任务定义
• 🔹 可编写自定义构建逻辑

本项目实例分析

1. 插件配置块

plugins{id'java-platform'// Java 平台插件id'org.springframework.boot'version"$springBootPluginVersion"// Spring Boot 插件applyfalse// 不应用到根项目id'io.spring.dependency-management'version"$dependencyManagementPluginVersion"applyfalse}

关键点：

• apply false：声明插件但不应用，让子模块自行决定是否应用
• $springBootPluginVersion：引用gradle.properties中的变量

2. ext 扩展属性块

ext{// 项目基本信息projectGroup='com.ymt'projectVersion='1.0.0-SNAPSHOT'// Java 版本javaVersion='17'// 框架版本（100+ 个依赖版本）springBootVersion=springBootPluginVersion springFrameworkVersion='6.2.7'mybatisPlusVersion='3.5.12'hutoolVersion='5.8.38'// ... 省略 90+ 个版本定义}

作用：

• 统一管理所有依赖版本
• 子模块通过rootProject.ext.hutoolVersion引用
• 避免版本冲突

3. java-platform 依赖约束

javaPlatform{allowDependencies()// 允许平台项目声明依赖}dependencies{// 导入 Spring Boot BOMapiplatform("org.springframework.boot:spring-boot-dependencies:${springBootVersion}")constraints{// 约束所有依赖的版本api"cn.hutool:hutool-core:${hutoolVersion}"api"com.baomidou:mybatis-plus-boot-starter:${mybatisPlusVersion}"// ... 200+ 个版本约束}}

工作原理：

根项目 build.gradle (java-platform) ↓ 定义版本约束 子模块 build.gradle ↓ 只声明依赖，不指定版本 dependencies { implementation 'cn.hutool:hutool-core' // 自动使用 5.8.38 }

优势：

• ✅ 版本集中管理，避免冲突
• ✅ 子模块简洁，无需指定版本号
• ✅ 升级方便，只改根项目

4. allprojects 全局配置

allprojects{group=rootProject.ext.projectGroup// 统一 groupIdversion=rootProject.ext.projectVersion// 统一版本号// 统一编码配置tasks.withType(JavaCompile){options.encoding='UTF-8'}// Maven 占位符替换afterEvaluate{tasks.withType(ProcessResources).configureEach{task->// 替换 @...@ 占位符task.filesMatching(['**/*.yml','**/*.yaml']){filter(ReplaceTokens,tokens:['profiles.active':project.findProperty('profiles.active'),'projectVersion':rootProject.ext.projectVersion])}}}}

解读：

• allprojects {}：应用到所有项目（包括根项目和子模块）
• afterEvaluate {}：在项目评估完成后执行
• ProcessResources：资源文件处理任务

5. subprojects 子模块配置

subprojects{repositories{// 使用阿里云镜像maven{url'https://maven.aliyun.com/repository/public'}maven{url'https://maven.aliyun.com/repository/central'}mavenCentral()}}

解读：

• subprojects {}：只应用到子模块，不包括根项目
• 配置 Maven 仓库地址

6. 自定义任务

// 打印版本号任务task printVersion{doLast{println projectVersion}}

使用：

./gradlew printVersion# 输出：1.0.0-SNAPSHOT

本项目架构特色

🏛️ java-platform 架构模式

根项目 (java-platform) - 只定义版本约束 - 不包含业务代码 - 作为 BOM (Bill of Materials) 子模块 - 引用根项目平台 - 声明依赖时不写版本 - 自动继承版本约束

示例：

// 子模块的 build.gradledependencies{// ✅ 继承根项目的版本管理implementationplatform(project(':'))// ✅ 不需要写版本号implementation'cn.hutool:hutool-core'implementation'com.baomidou:mybatis-plus-boot-starter'}

🔄 三层架构映射

// settings.gradle 中的模块组织ymt-platform ├─ ymt-common → 通用层（基础设施） ├─ ymt-modules → 业务层（领域逻辑） └─ ymt-application → 应用层（启动入口）

对应到 Spring Boot 分层架构：

ymt-common → Infrastructure Layer (基础设施层) ymt-modules → Domain Layer (领域层) ymt-application → Application Layer (应用层)

🔄 三者协作流程

Gradle 构建生命周期

详细执行流程

阶段 1：初始化（Initialization）

1. Gradle 启动 ↓ 2. 查找 settings.gradle ↓ 3. 执行 settings.gradle - 设置 rootProject.name = 'plat_index' - include 所有子模块 ↓ 4. 构建项目树结构

输出示例：

Root project 'plat_index' +--- Project ':ymt-platform' | +--- Project ':ymt-platform:ymt-common' | | +--- Project ':ymt-platform:ymt-common:ymt-common-core' | | +--- Project ':ymt-platform:ymt-common:ymt-common-redis' | +--- Project ':ymt-platform:ymt-modules' | | +--- Project ':ymt-platform:ymt-modules:ymt-metadata'

阶段 2：配置（Configuration）

1. 加载 gradle.properties - 读取所有 key=value 配置 - 设置系统属性（systemProp.*） - 配置 Gradle 守护进程参数 ↓ 2. 执行根项目的 build.gradle - 应用插件 - 定义 ext 属性 - 配置 dependencies 约束 ↓ 3. 执行子模块的 build.gradle - 引用根项目的版本管理 - 声明模块依赖 - 配置特定任务 ↓ 4. 创建任务依赖关系图（DAG）

阶段 3：执行（Execution）

1. 根据命令行参数确定要执行的任务 例如：./gradlew build ↓ 2. 解析任务依赖 build → classes → compileJava → ... ↓ 3. 按依赖顺序执行任务 - 并行执行独立任务（如果开启 parallel） - 增量编译（只编译改动的文件） - 利用缓存（如果开启 caching） ↓ 4. 生成构建产物

实际案例：执行./gradlew build时

# 1. settings.gradle 执行>Configure project:Root project'plat_index'includes50+ subprojects# 2. gradle.properties 生效>Using Gradle properties:parallel=true,caching=true>JVM arguments: -Xmx4g -Xms2g# 3. build.gradle 配置>Configuring root project'plat_index'>Applying plugin: java-platform>Configuring50+ subprojects...# 4. 任务执行>Task :ymt-platform:ymt-common:ymt-common-core:compileJava>Task :ymt-platform:ymt-modules:ymt-metadata:compileJava>Task :ymt-platform:ymt-application:ymt-admin-app:bootJar BUILD SUCCESSFULin2m 15s

💡 最佳实践

1. settings.gradle 最佳实践

✅ 推荐做法

// 使用描述性的项目名称rootProject.name='ymt-platform'// 模块分组，便于维护// 通用组件include'ymt-common:ymt-common-core'include'ymt-common:ymt-common-redis'// 业务模块include'ymt-modules:ymt-metadata'include'ymt-modules:ymt-quality'// 应用模块include'ymt-application:ymt-admin-app'

❌ 避免做法

// ❌ 不要在 settings.gradle 中写业务逻辑include'module1'println"Building module1..."// 不要这样// ❌ 不要动态修改模块路径project(':module1').projectDir=newFile('other-location')// 不推荐

2. gradle.properties 最佳实践

✅ 推荐做法

# 分类组织配置 # =================== # Gradle 性能配置 # =================== org.gradle.parallel=true org.gradle.caching=true # =================== # 插件版本 # =================== springBootPluginVersion=3.4.7 # =================== # 应用配置 # =================== profiles.active=dev

❌ 避免做法

# ❌ 不要存储敏感信息 database.password=real_password # 危险！ # ❌ 不要使用特殊字符 app.name=My App # 空格可能导致问题 # ✅ 应该这样 app.name=MyApp

3. build.gradle 最佳实践

✅ 推荐做法

// 清晰的结构组织plugins{// 插件声明}ext{// 扩展属性}dependencies{// 依赖声明}tasks{// 任务配置}

❌ 避免做法

// ❌ 硬编码版本号dependencies{implementation'cn.hutool:hutool-core:5.8.38'// 不好}// ✅ 使用变量dependencies{implementation"cn.hutool:hutool-core:${hutoolVersion}"// 好}

4. 版本管理策略

本项目采用的策略：BOM + Platform

根项目 (java-platform) ├─ ext { 定义版本变量 } └─ dependencies.constraints { 约束版本 } 子模块 └─ dependencies { 声明依赖（不写版本） }

优势：

• ✅ 单点维护，统一升级
• ✅ 避免版本冲突
• ✅ 子模块配置简洁

5. 多环境配置

推荐方案：Profile + Properties

# gradle.properties (默认) profiles.active=dev # gradle-test.properties (测试环境) profiles.active=test # gradle-prod.properties (生产环境) profiles.active=prod

使用：

# 开发环境./gradlew build# 测试环境./gradlew build -Pprofiles.active=test# 生产环境./gradlew build -Pprofiles.active=prod