本文介绍 Nebula 多模块 Gradle 项目的结构规范、依赖管理方式和常用构建任务。
Nebula 项目统一使用 nebula-support 提供的 Gradle 插件和 BOM 管理依赖，理解这套机制是高效开发的前提。

---

目录

• 一、Nebula 多模块项目结构
• 二、关键配置文件说明
• 三、依赖管理机制
• 四、常用 Gradle 任务
• 五、本地调试技巧
• 六、常见问题处理

---

一、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 中声明版本）：

1. 在 nebula-support/gradle.properties 添加版本变量：

   someLibVersion=1.2.3

2. 在 nebula-support/nebula-support-dependencies/build.gradle 的 constraints 块声明：

   constraints {
       api "com.example:some-lib:${someLibVersion}"
   }

3. 业务项目中不写版本号：

   implementation 'com.example:some-lib'

详见 nebula-support 依赖版本管理（BOM） 和 框架工具使用规范。

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 implementation

Nebula 专属任务（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

依赖无法拉取，检查顺序：

1. 确认 VPN / 内网连接正常
2. 检查 gradle.properties 中 nebula.private.url 是否正确
3. 检查私服凭据（nebula.private.username / nebula.private.password）
4. 尝试清理 Gradle 缓存：删除 ~/.gradle/caches/modules-2/files-2.1/com.huida.nebula/ 目录，重新同步

Q2：Execution failed for task ':compileJava'，报 invalid source release 17

IDEA 或 Gradle 使用的 JDK 版本不对：

1. 检查 File → Project Structure → SDK 是否为 JDK 17
2. 检查 Settings → Gradle JVM 是否为 JDK 17
3. 检查 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