# nx-starter

**Repository Path**: umb/nx-starter

## Basic Information

- **Project Name**: nx-starter
- **Description**: NX 系列项目提供通用基础设施
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# nx-starter

基于 Spring Boot 3.5 的可复用 Starter 组件库，为 NX 系列项目提供通用基础设施。

## 项目简介

nx-starter 是一个 Maven 多模块项目，提供了一系列开箱即用的 Spring Boot Starter 组件。这些组件封装了常用的功能模块，可被多个业务项目通过 Maven 依赖复用。

### 技术栈

| 技术 | 版本 |
|------|------|
| Java | 21（启用虚拟线程） |
| Spring Boot | 3.5.9 |
| MyBatis-Plus | 3.5.16 |
| Sa-Token | 1.44.0 |
| Redisson | 3.52.0 |
| Hutool | 5.8.43 |
| FastExcel | 1.2.0 |
| AWS S3 SDK | 2.25.0 |

## 模块索引

### 基础层

| 模块 | 功能 | 依赖 | 文档 |
|------|------|------|------|
| **nx-starter-bom** | 依赖版本管理 | 无 | [文档](nx-starter-bom/README.md) |
| **nx-starter-core** | 核心工具类、统一返回结果 `R<T>`、常量、异常 | 无 | [文档](nx-starter-core/README.md) |

### 基础设施层

| 模块 | 功能 | 依赖 | 文档 |
|------|------|------|------|
| **nx-starter-web** | Web 工具、全局异常处理 | core | [文档](nx-starter-web/README.md) |
| **nx-starter-redis** | Redis 和 Redisson 集成、分布式锁 | core | [文档](nx-starter-redis/README.md) |
| **nx-starter-mybatis** | MyBatis-Plus 集成、分页、数据权限 | core, web | [文档](nx-starter-mybatis/README.md) |

### 业务层

| 模块 | 功能 | 依赖 | 文档 |
|------|------|------|------|
| **nx-starter-satoken** | Sa-Token 权限认证、JWT 支持 | core, redis | [文档](nx-starter-satoken/README.md) |
| **nx-starter-log** | 操作日志、登录日志 | core, web, satoken | [文档](nx-starter-log/README.md) |

### 工具层

| 模块 | 功能 | 依赖 | 文档 |
|------|------|------|------|
| **nx-starter-idempotent** | 幂等性、防重复提交 | core, redis | [文档](nx-starter-idempotent/README.md) |
| **nx-starter-sensitive** | 数据脱敏 | core | [文档](nx-starter-sensitive/README.md) |
| **nx-starter-ratelimiter** | 接口限流、熔断 | core, redis | [文档](nx-starter-ratelimiter/README.md) |
| **nx-starter-excel** | Excel 导入导出（FastExcel） | core | [文档](nx-starter-excel/README.md) |
| **nx-starter-oss** | 对象存储（S3 协议） | core | [文档](nx-starter-oss/README.md) |

### 模块依赖关系

```
                    ┌─────────────────┐
                    │   nx-starter    │
                    │   (parent)      │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌─────────┐    ┌─────────┐   ┌──────────┐
        │   bom   │    │  core   │   │   web    │
        └─────────┘    └────┬────┘   └────┬─────┘
                            │             │
              ┌─────────────┼──────┬──────┘
              ▼             ▼      ▼
        ┌─────────┐   ┌────────┐ ┌──────────┐
        │  redis  │   │ mybatis│ │   satoken│
        └────┬────┘   └────────┘ └────┬─────┘
             │                        │
        ┌────┴────┬───────────────────┘
        ▼         ▼
   ┌────────┐ ┌─────────┐
   │idempotent│ │   log   │
   └────────┘ └─────────┘
   ┌────────┐ ┌─────────┐ ┌─────────┐ ┌────────┐
   │ratelimiter│ │sensitive│ │  excel  │ │  oss   │
   └────────┘ └─────────┘ └─────────┘ └────────┘
```

## 快速开始

### 1. 添加 Maven 依赖

在业务项目中继承 parent POM：

```xml
<parent>
    <groupId>com.yunqi.starter</groupId>
    <artifactId>nx-starter</artifactId>
    <version>1.0.0</version>
</parent>
```

或导入 BOM：

```xml
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.yunqi.starter</groupId>
            <artifactId>nx-starter-bom</artifactId>
            <version>1.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
```

### 2. 添加所需模块

```xml
<dependencies>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-mybatis</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-satoken</artifactId>
    </dependency>
</dependencies>
```

### 3. 配置应用

在 `application.yml` 中配置：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/nexus
    username: root
    password: password
  redis:
    host: localhost
    port: 6379

sa-token:
  token-name: Authorization
  timeout: 2592000
```

### 4. 开始使用

```java
@RestController
@RequestMapping("/api/user")
public class UserController {

    @SaCheckPermission("user:list")
    @GetMapping("/list")
    public TableDataInfo<User> list(PageQuery pageQuery) {
        // 自动分页、权限校验、日志记录
        return userService.selectUserList(pageQuery);
    }
}
```

## 模块选择指南

### 最简项目（只需核心功能）

```xml
<dependencies>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-core</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-web</artifactId>
    </dependency>
</dependencies>
```

### Web 项目（数据库 + 权限）

```xml
<dependencies>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-mybatis</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-satoken</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-log</artifactId>
    </dependency>
</dependencies>
```

### 完整项目（全功能）

```xml
<dependencies>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-mybatis</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-satoken</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-log</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-redis</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-idempotent</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-ratelimiter</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-excel</artifactId>
    </dependency>
    <dependency>
        <groupId>com.yunqi.starter</groupId>
        <artifactId>nx-starter-oss</artifactId>
    </dependency>
</dependencies>
```

## 常用命令

```bash
# 编译所有模块
mvn clean compile

# 打包并安装到本地仓库
mvn clean install

# 打包（跳过测试，默认行为）
mvn clean package

# 运行测试（需显式启用）
mvn test -DskipTests=false

# 查看依赖树
mvn dependency:tree

# 发布到远程仓库
mvn clean deploy
```

## 版本管理

项目使用 `flatten-maven-plugin` 统一管理版本号：

- 根 `pom.xml` 中定义 `${revision}` 属性
- 子模块使用 `${revision}` 引用父版本
- 发布时自动解析为具体版本号

版本号规范遵循 [语义化版本](https://semver.org/lang/zh-CN/)：

- `MAJOR.MINOR.PATCH`
- 例如：`1.0.0`，`1.1.0`，`2.0.0`

## 相关项目

- **Nexus** - 业务管理系统（使用 nx-starter）
  - 位于 `E:/www/nexus/`
  - 依赖 nx-starter 组件库

## 贡献指南

欢迎提交 Issue 和 Pull Request。

## License

MIT License