外观
构建插件使用指南
2026-03-05
插件 ID:com.huida.nebula.plugin.boot
apply 后自动执行以下标准化配置,各功能均可通过 nebula {} 块开关或覆盖。
功能一:仓库配置
默认行为:按以下优先级自动配置 Maven 仓库:
| 优先级 | 仓库 | 说明 |
|---|---|---|
| 1 | mavenLocal() | 本地 ~/.m2,开发阶段优先用本地快照 |
| 2 | 公司私服 | 地址来自 nebula.private.url(支持 HTTP) |
| 3 | 阿里云公共镜像 | https://maven.aliyun.com/repository/public/ |
| 4 | 阿里云 Spring 镜像 | https://maven.aliyun.com/repository/spring/ |
| 5 | mavenCentral() | 兜底 |
常见定制场景:
私服无法访问
nebula {
enablePrivateRepo = false // 跳过私服,直接走阿里云镜像
}自定义私服地址
nebula {
// 覆盖内嵌默认地址(或在 gradle.properties 中写 nebula.private.url=...)
privateRepoUrl = 'http://my-nexus:8081/repository/public/'
}私服需要凭据
nebula {
privateRepoUsername = 'admin'
privateRepoPassword = 'password'
// 推荐:凭据写在 ~/.gradle/gradle.properties,此处省略
}关闭整个仓库配置
nebula {
enableRepositoryConfiguration = false // 完全由项目自行管理仓库
}URL 配置优先级:nebula { privateRepoUrl = '...' } > 项目 gradle.properties > 插件 JAR 内嵌默认值。
功能二:Java 编译配置
默认行为(始终生效,无开关):
| 配置项 | 值 |
|---|---|
| 源 / 目标兼容版本 | 读 javaVersion(gradle.properties),默认 17 |
| 编码 | UTF-8(编译 + Javadoc) |
| 编译参数 | -parameters(保留方法参数名)、-Xlint:deprecation、-Xlint:unchecked |
| Javadoc doclint | 已关闭(-Xdoclint:none),避免 Lombok 生成代码报错 |
修改 Java 版本只需在 gradle.properties 中设置:
# gradle.properties
javaVersion=21功能三:公共依赖自动注入
默认行为:enableCommonConfiguration = true 时自动注入以下依赖(版本来自 BOM,无需手动声明):
| 配置项 | 自动注入的依赖 |
|---|---|
annotationProcessor | lombok、spring-boot-configuration-processor、mapstruct-processor |
compileOnly | lombok、mapstruct |
testAnnotationProcessor | lombok |
testCompileOnly | lombok |
这意味着项目无需在 dependencies {} 中手动写 Lombok、MapStruct 相关配置。
关闭:
nebula {
enableCommonConfiguration = false // 关闭后须自行声明以上依赖
}功能四:全局依赖排除
默认排除(对所有 configuration 生效):
| 排除模块 | 原因 |
|---|---|
spring-boot-starter-tomcat | 使用 Undertow 作为 Web 容器 |
spring-boot-starter-logging | 使用 Log4j2 替换 Logback |
excludeModules 是覆盖,不是追加
配置 excludeModules 会替换默认列表,若还需要默认的排除,须把它们一并写上。
nebula {
// 追加排除时,须把默认排除也写进来
excludeModules = [
'spring-boot-starter-tomcat',
'spring-boot-starter-logging',
'netty-transport-native-epoll' // 新增排除
]
}功能五:依赖版本管理(BOM 导入)
默认行为:自动应用 io.spring.dependency-management 插件,并在 afterEvaluate 中导入 BOM:
com.huida.nebula.support:nebula-support-dependencies:{nebulaVersion}关闭:
nebula {
enableDependencyManagement = false // 需自行管理依赖版本
}功能六:测试配置
默认行为:自动为所有 Test 类型任务启用 JUnit Platform(JUnit 5),无需手动调用 useJUnitPlatform()。
关闭:
nebula {
enableTest = false
}功能七:Maven 发布
发布分三种场景,按实际需求选择:
场景 A:框架模块发布(最常见)
适用于:发布 JAR 到 Nexus 的框架或 starter 模块(如 nebula-framework-*、nebula-boot-starter-*)
// 根 build.gradle(allprojects 或 subprojects)
nebula {
enablePublish = true
// 默认规则已覆盖 nebula-framework-* / nebula-boot-starter-* / nebula-tools-* / *-api
// 若有不符合命名规则的模块,在精确名称列表中显式声明:
publishableModuleNames = ['nebula-boot-starter']
}发布策略:
| 版本类型 | 发布内容 | 说明 |
|---|---|---|
| SNAPSHOT | 字节码 JAR + sources JAR + javadoc JAR | 方便开发阶段查看源码与注释 |
| Release | 仅字节码 JAR | 保护框架源码,注释不对外 |
插件自动生成标准 POM(Apache 2.0 License、惠达普照 developer 信息),无需手动配置。
可发布模块识别规则:
| 规则类型 | 默认值 | 匹配示例 |
|---|---|---|
| 名称前缀 | nebula-framework-、nebula-boot-starter-、nebula-tools- | nebula-framework-mybatis ✅ |
| 名称后缀 | -api | nebula-auth-api ✅ |
| 精确名称 | 无(需手动配置) | publishableModuleNames = ['nebula-boot-starter'] |
聚合模块自动排除
nebula-framework、nebula-starters 等聚合目录,名称不符合任何规则,插件不会对其配置 maven-publish,无需额外处理。
场景 B:仅注入发布仓库(适合 BOM 模块)
适用于:模块已自行配置 publishing { publications { ... } },只需插件注入发布仓库地址,不干预发布内容。
典型场景:nebula-boot-dependencies 这类 BOM 模块,其 publication 逻辑特殊,需要完全自定义。
// nebula-boot-dependencies/build.gradle
nebula {
enablePublishRepository = true // 仅注入仓库,不接管 publications
}
apply plugin: 'maven-publish'
publishing {
publications {
nebulaBootBom(MavenPublication) {
// 自定义发布内容...
}
}
// 无需配置 repositories,插件已自动注入
}场景 C:不发布(默认)
两个开关均默认为 false,无需任何配置,插件不会 apply maven-publish。
发布凭据配置
# ~/.gradle/gradle.properties(本机全局,不提交版本库)
nebula.publish.username=your-nexus-username
nebula.publish.password=your-nexus-password也可在 nebula {} 中配置(不推荐,有泄漏风险):
nebula {
publishUsername = findProperty('nebula.publish.username') ?: ''
publishPassword = findProperty('nebula.publish.password') ?: ''
}多模块项目完整示例
参考 nebula-boot 项目的真实配置:
// 根 build.gradle
buildscript {
repositories {
mavenLocal()
maven { url "https://maven.aliyun.com/repository/public/" }
}
dependencies {
classpath "com.huida.nebula.support:nebula-boot-plugin-gradle:${nebulaPluginVersion}"
}
}
allprojects {
group = 'com.huida.nebula.boot'
version = projectVersion // 从 gradle.properties 读取
apply plugin: 'com.huida.nebula.plugin.boot'
nebula {
nebulaVersion = nebulaBootVersion // BOM 版本
enableDependencyManagement = true
enableRepositoryConfiguration = true
enablePrivateRepo = false // 框架项目源码本地可用,无需走私服
enablePublish = true // 开启发布
// nebula-boot-starter 不带默认前后缀,需显式声明
publishableModuleNames = ['nebula-boot-starter']
}
}
// 按模块层次覆盖 group
configure(subprojects.findAll { p ->
p.path.startsWith(':nebula-boot-project:nebula-framework')
}) {
group = 'com.huida.nebula'
}功能八:Spring Boot 应用自动识别
当模块满足以下任一条件时,插件自动 apply org.springframework.boot 插件并禁用普通 jar 任务(改用 bootJar):
| 识别条件 | 说明 |
|---|---|
已 apply org.springframework.boot 插件 | 明确声明 |
模块名以 -boot / -app / -web / -service 结尾 | 按命名约定自动识别 |
提示
框架模块通常不符合上述条件,不会被误识别为 Spring Boot 应用。业务项目(如 order-service、user-boot)会被自动识别。
内置 Gradle 任务
以下任务由插件在根项目注册(task group:nebula):
| 任务名 | 作用 |
|---|---|
nebulaPublishAll | 发布所有可发布模块到私服 Nexus(遍历子模块执行 publish) |
nebulaPublishLocal | 发布所有可发布模块到本地 ~/.m2(遍历子模块执行 publishToMavenLocal) |
nebulaBuildAll | 编译所有可发布模块(遍历子模块执行 build) |
# 发布所有框架模块到私服
./gradlew nebulaPublishAll
# 先发布到本地,供业务项目联调
./gradlew nebulaPublishLocal
# 全量编译验证
./gradlew nebulaBuildAll