外观
Gradle 项目构建
2026-04-01
本文介绍 Nebula 多模块 Gradle 项目的结构规范、依赖管理方式和常用构建任务。
Nebula 项目统一使用nebula-support提供的 Gradle 插件和 BOM 管理依赖,理解这套机制是高效开发的前提。
目录
一、Nebula 多模块项目结构
Nebula 各子项目(以 nebula-system 为例)都是标准的 Gradle 多模块结构:
nebula-system/
├── settings.gradle # 根项目配置:项目名、子模块列表、插件仓库
├── build.gradle # 根项目构建:应用插件、通用配置(所有子模块共享)
├── gradle.properties # 版本变量、私服地址等全局属性
├── gradle/
│ └── wrapper/
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties # Gradle 版本固定在这里
│
├── nebula-system-api/ # 对外契约模块(Feign 接口、DTO、常量)
│ └── build.gradle
│
├── nebula-system-core/ # 业务实现模块(Controller、Service、Mapper)
│ └── build.gradle
│
├── nebula-system-server/ # 可运行服务(启动类、配置文件、Flyway 脚本)
│ └── build.gradle
│
└── nebula-system-starter/ # Spring Boot 自动装配入口
└── build.gradle各模块职责:
| 模块 | 对谁开放 | 包含内容 |
|---|---|---|
-api | 所有调用方 | Feign 接口、RPC DTO、Constants 常量 |
-core | 内部 | Controller、Service、Mapper、Entity、VO |
-server | 部署运行 | 启动类、application.yaml、Flyway 脚本 |
-starter | 聚合部署 | Spring Boot AutoConfiguration imports |
二、关键配置文件说明
2.1 settings.gradle
// 项目名称(也是 Gradle 根模块名)
rootProject.name = 'nebula-system'
// 声明所有子模块
include(
'nebula-system-api',
'nebula-system-core',
'nebula-system-server',
'nebula-system-starter'
)
// 插件仓库配置(nebula-support 构建插件从这里拉取)
pluginManagement {
repositories {
maven { url 'http://nexus.yourcompany.com/repository/public/' }
gradlePluginPortal()
}
}2.2 gradle.properties
# Nebula 框架版本(所有子项目统一)
nebulaBootVersion=1.2.3
nebulaAuthVersion=1.0.5
nebulaSystemVersion=1.1.0
# 私服地址(nebula-support 插件读取此属性)
nebula.private.url=http://nexus.yourcompany.com/repository/public/
nebula.private.username=deployer
nebula.private.password=your-password
# Gradle 并行构建(加速多模块构建)
org.gradle.parallel=true
org.gradle.caching=true
gradle.properties中的敏感信息(私服密码)不要提交到代码仓库,可以在 CI/CD 中通过环境变量注入,或在~/.gradle/gradle.properties(全局,不在项目目录)中配置。
2.3 根项目 build.gradle
// 应用 nebula-support 提供的标准化构建插件
plugins {
id 'com.huida.nebula.plugin.boot' version "${nebulaPluginVersion}" apply false
}
// 对所有子项目统一应用插件和配置
subprojects {
apply plugin: 'com.huida.nebula.plugin.boot'
// 指定 Java 版本
java {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
}2.4 子模块 build.gradle
子模块只声明自己的依赖,不写版本号(版本由 BOM 统一管理):
dependencies {
// 依赖框架层(不写版本,从 nebula-support BOM 继承)
implementation "com.huida.nebula.boot:nebula-boot-starter-web"
implementation "com.huida.nebula.boot:nebula-boot-starter-mybatis"
implementation "com.huida.nebula.boot:nebula-boot-starter-redis"
// 依赖同项目其他模块
implementation project(':nebula-system-api')
// 依赖其他 Nebula 子项目
implementation "com.huida.nebula.auth:nebula-auth-api:${nebulaAuthVersion}"
// 仅测试使用
testImplementation 'org.springframework.boot:spring-boot-starter-test'
}三、依赖管理机制
3.1 两层 BOM 管理
Nebula 使用两层 BOM 统一管理第三方依赖版本,禁止在 build.gradle 中硬编码版本号:
nebula-support-dependencies(第三方依赖 BOM)
└── 管理:Spring Boot、MyBatis-Plus、EasyExcel、Minio、Redisson 等的版本
nebula-boot-dependencies(框架内部 BOM)
└── 管理:nebula-framework-*、nebula-boot-starter-* 各自的版本这两个 BOM 通过 nebula-support 的 Gradle 插件自动引入,业务服务项目无需手动配置。
3.2 新增第三方依赖的正确方式
如果业务服务需要引入新的第三方库,应先检查是否已在 BOM 中管理:
已在 BOM 中管理(直接用,不写版本):
// BOM 已管理,直接引入即可
implementation 'com.alibaba:easyexcel'
implementation 'io.minio:minio'未在 BOM 中管理(需先在 nebula-support 中声明版本):
在
nebula-support/gradle.properties添加版本变量:someLibVersion=1.2.3在
nebula-support/nebula-support-dependencies/build.gradle的constraints块声明:constraints { api "com.example:some-lib:${someLibVersion}" }业务项目中不写版本号:
implementation 'com.example:some-lib'
3.3 依赖配置关键字
| 配置 | 说明 | 典型使用场景 |
|---|---|---|
implementation | 编译+运行时,不对外暴露 | 业务逻辑依赖 |
api | 编译+运行时,对外暴露(传递依赖) | -api 模块声明对外接口的依赖 |
compileOnly | 仅编译时,运行时由外部提供 | Framework 层声明可选的 Starter 依赖 |
runtimeOnly | 仅运行时 | JDBC 驱动等 |
testImplementation | 仅测试编译+运行时 | 测试框架 |
四、常用 Gradle 任务
在 IDEA 右侧 Gradle 面板或命令行中执行。
基础任务
# 编译(不执行测试)
./gradlew classes
# 全量构建(编译 + 测试 + 打包)
./gradlew build
# 仅打包(跳过测试,日常最常用)
./gradlew build -x test
# 清理构建产物
./gradlew clean
# 清理后重新构建
./gradlew clean build -x test子模块单独构建
# 只构建指定子模块(: 分隔模块路径)
./gradlew :nebula-system-server:build -x test
# 只编译 core 模块
./gradlew :nebula-system-core:compileJava依赖相关
# 查看所有依赖树(排查版本冲突时用)
./gradlew dependencies
# 查看某个子模块的依赖树
./gradlew :nebula-system-core:dependencies
# 只看 implementation 配置的依赖
./gradlew :nebula-system-core:dependencies --configuration implementationNebula 专属任务(nebula-support 插件提供)
# 生成 SmartDoc API 文档
./gradlew smartDoc
# 发布到本地 Maven 仓库(开发阶段调试用)
./gradlew publishToMavenLocal
# 发布到 Nexus 私服
./gradlew publish五、本地调试技巧
5.1 本地修改 nebula-boot 后,在业务服务中使用
当你需要修改 nebula-boot 框架本身并在业务服务中验证时,不需要每次都发版到私服:
方法 1:publishToMavenLocal(推荐)
# 在 nebula-boot 项目中发布到本地 Maven 仓库
cd nebula-boot
./gradlew publishToMavenLocal
# 在业务服务的 gradle.properties 中临时修改版本号为 SNAPSHOT
nebulaBootVersion=1.2.4-SNAPSHOT
# IDEA Gradle 面板刷新即可使用本地版本方法 2:Composite Builds(源码级依赖)
在业务服务的 settings.gradle 中引入 nebula-boot 的源码目录:
// 临时调试:将 nebula-boot 作为源码模块引入(不发布,直接编译)
includeBuild('../nebula-boot') {
dependencySubstitution {
substitute module('com.huida.nebula.boot:nebula-boot-starter-web') using project(':nebula-starters:nebula-boot-starter-web')
}
}调试完成后删除
includeBuild块,恢复版本号引用。
5.2 并行构建加速
在 gradle.properties 中开启并行构建,多核机器下显著加速:
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.daemon=true # 保持 Gradle Daemon 常驻,加速后续构建5.3 查看任务执行耗时(定位构建慢的原因)
./gradlew build --profile
# 构建完成后,在 build/reports/profile/ 目录生成 HTML 报告六、常见问题处理
Q1:Could not resolve com.huida.nebula.boot:xxx
依赖无法拉取,检查顺序:
- 确认 VPN / 内网连接正常
- 检查
gradle.properties中nebula.private.url是否正确 - 检查私服凭据(
nebula.private.username/nebula.private.password) - 尝试清理 Gradle 缓存:删除
~/.gradle/caches/modules-2/files-2.1/com.huida.nebula/目录,重新同步
Q2:Execution failed for task ':compileJava',报 invalid source release 17
IDEA 或 Gradle 使用的 JDK 版本不对:
- 检查
File → Project Structure → SDK是否为 JDK 17 - 检查
Settings → Gradle JVM是否为 JDK 17 - 检查
gradle.properties是否有org.gradle.java.home指向错误路径
Q3:Duplicate class 或版本冲突报错
同一个类被两个不同版本的 JAR 包含,需要排除低版本:
// 找出哪里引入了老版本
./gradlew dependencies | grep "冲突的包名"
// 在 build.gradle 中排除冲突版本
implementation('some:lib') {
exclude group: 'conflict.group', module: 'conflict-artifact'
}
// 或强制指定版本(BOM 中已管理的优先用 BOM,不要这样做)
configurations.all {
resolutionStrategy.force 'conflict.group:conflict-artifact:1.2.3'
}Q4:./gradlew 命令执行报 Permission denied
chmod +x gradlew