nebula-boot 是 Nebula 架构的框架核心能力层，为业务服务提供 Web、持久层、缓存、消息、安全、多租户、文件、Excel、任务等开箱即用的 Starter 集成。
读完本文，你将完成业务服务的接入配置，并了解各 Starter 的职责划分。

---

目录

• 一、nebula-boot 整体架构
• 二、接入前提
• 三、引入聚合 Starter
• 四、按需引入单个 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 脚本扫描与审批	—