外观
快速入门
2026-04-01
nebula-boot是 Nebula 架构的框架核心能力层,为业务服务提供 Web、持久层、缓存、消息、安全、多租户、文件、Excel、任务等开箱即用的 Starter 集成。
读完本文,你将完成业务服务的接入配置,并了解各 Starter 的职责划分。
目录
一、nebula-boot 整体架构
nebula-boot 按职责分为两层:
nebula-boot-project/
├── nebula-framework-* 框架层(核心能力抽象,纯 Java,不依赖 Spring Boot)
│ ├── nebula-framework-core 通用工具:R<T> / PageParam / 异常体系 / JsonUtils 等
│ ├── nebula-framework-web Web 层:全局异常 / 响应包装 / 请求日志 / 脱敏 / 防重
│ ├── nebula-framework-mybatis 持久层基类:BaseEntity / BaseMapper / BaseService
│ ├── nebula-framework-tenant 多租户:上下文 / 隔离策略 / 数据源路由 / 切面
│ ├── nebula-framework-trace 链路追踪:TraceId 生成 / 传播 / MDC 注入
│ ├── nebula-framework-security 安全模型:Token / 权限注解 / SPI 契约
│ ├── nebula-framework-file 文件存储:多厂商抽象 / 分片上传 / 预览
│ ├── nebula-framework-excel Excel 导入导出引擎
│ └── nebula-framework-task 任务框架:调度 / 队列 / 线程池 / 通知
│
└── nebula-starters/ Starter 层(Spring Boot 自动配置,可依赖 Framework 层)
├── nebula-boot-starter-web
├── nebula-boot-starter-jdbc
├── nebula-boot-starter-mybatis
├── nebula-boot-starter-redis
├── nebula-boot-starter-mq
├── nebula-boot-starter-openfeign
├── nebula-boot-starter-tenant
├── nebula-boot-starter-trace
├── nebula-boot-starter-security
├── nebula-boot-starter-file
├── nebula-boot-starter-excel
├── nebula-boot-starter-task
├── nebula-boot-starter-swagger
├── nebula-boot-starter-flyway
└── nebula-boot-starter ← 聚合 Starter(包含所有常用 Starter)分层约束: Framework 层模块只能依赖同层或更底层,不允许反向依赖 Starter 层。
二、接入前提
业务服务需要先完成 nebula-support 的接入(BOM + Gradle 插件),具体参见 nebula-support 快速入门。
确保 gradle.properties 中已声明:
nebulaBootVersion=x.x.x三、引入聚合 Starter
推荐方式:在服务的 -starter 子模块中引入聚合 Starter,一次性获得所有常用能力:
// {服务}-starter/build.gradle
dependencies {
implementation "com.huida.nebula.boot:nebula-boot-starter:${nebulaBootVersion}"
}聚合 Starter 已包含:Web / MyBatis / Redis / Tenant / Trace / Security / Swagger / Flyway 等。
四、按需引入单个 Starter
若业务场景只需要部分能力,可单独引入对应 Starter,按需减少依赖体积:
dependencies {
// Web 层(全局异常 / 响应包装 / 请求日志 / 脱敏 / 防重)
implementation "com.huida.nebula.boot:nebula-boot-starter-web:${nebulaBootVersion}"
// 持久层(MyBatis-Plus + BaseEntity + 多租户 SQL 拦截)
implementation "com.huida.nebula.boot:nebula-boot-starter-mybatis:${nebulaBootVersion}"
// Redis(NebulaCacheHelper + NebulaLockHelper)
implementation "com.huida.nebula.boot:nebula-boot-starter-redis:${nebulaBootVersion}"
// 多租户(TenantContext + 数据源路由 + 切面)
implementation "com.huida.nebula.boot:nebula-boot-starter-tenant:${nebulaBootVersion}"
// 链路追踪(TraceId 自动注入 HTTP / 定时任务 / MQ)
implementation "com.huida.nebula.boot:nebula-boot-starter-trace:${nebulaBootVersion}"
// 文件存储(多厂商 / 分片上传)
implementation "com.huida.nebula.boot:nebula-boot-starter-file:${nebulaBootVersion}"
// Excel 导入导出
implementation "com.huida.nebula.boot:nebula-boot-starter-excel:${nebulaBootVersion}"
// 任务框架(Disruptor / RocketMQ 队列)
implementation "com.huida.nebula.boot:nebula-boot-starter-task:${nebulaBootVersion}"
// Swagger / OpenAPI 文档
implementation "com.huida.nebula.boot:nebula-boot-starter-swagger:${nebulaBootVersion}"
// Flyway 数据库版本管理
implementation "com.huida.nebula.boot:nebula-boot-starter-flyway:${nebulaBootVersion}"
}五、最小配置启动
引入 Starter 后,在 application.yaml(或 application-dev.yaml)中补充必要配置:
spring:
application:
name: nebula-your-service
datasource:
url: jdbc:mysql://localhost:3306/your_db?useUnicode=true&characterEncoding=utf-8
username: root
password: your_password
driver-class-name: com.mysql.cj.jdbc.Driver
# 多租户配置(启用后,所有 LambdaQueryWrapper 自动追加 tenant_id 过滤)
nebula:
tenant:
enabled: true
isolation-mode: FIELD # FIELD(行级隔离)/ DATABASE / SCHEMA
# 链路追踪
trace:
enabled: true
# 日志配置(指向对应环境的 Log4j2 配置)
logging:
config: classpath:log4j/log4j2-dev.xml六、Starter 功能一览
| Starter | 核心能力 | 详细文档 |
|---|---|---|
nebula-boot-starter-web | 全局异常处理、响应自动包装、请求日志、脱敏序列化、防重提交 | Web 层说明 |
nebula-boot-starter-mybatis | MyBatis-Plus 集成、BaseEntity/BaseMapper/BaseService 注入 | 持久层说明 |
nebula-boot-starter-redis | NebulaCacheHelper、NebulaLockHelper、@DistributedLock | 框架工具规范 |
nebula-boot-starter-tenant | TenantContextFilter、数据源路由、@TenantSwitch / @TenantIgnore | 多租户说明 |
nebula-boot-starter-trace | TraceId 自动注入(HTTP/定时/MQ/异步线程池)、Log4j2 MDC | 链路追踪说明 |
nebula-boot-starter-file | 多厂商文件存储(本地/Minio/OSS/COS 等)、分片上传 | 文件存储说明 |
nebula-boot-starter-excel | EasyExcel 导入导出、任务化大批量 Excel | Excel 说明 |
nebula-boot-starter-task | Disruptor / RocketMQ 任务队列、线程池管理、任务通知 | 任务框架说明 |
nebula-boot-starter-swagger | SpringDoc / OpenAPI 3 文档自动生成 | — |
nebula-boot-starter-flyway | Flyway 数据库版本化迁移、SQL 脚本扫描与审批 | — |
