# spring-template

**Repository Path**: Soullose/spring-template

## Basic Information

- **Project Name**: spring-template
- **Description**: springboot项目模版-ORM(JPA,QueryDSL)-JWT(redis)
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-11-05
- **Last Updated**: 2026-04-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Template

基于 Spring Boot 3.5 的企业级后端项目模板，采用 DDD（领域驱动设计）+ CQRS（命令查询职责分离）架构范式，集成 RBAC 权限管理、JWT 无状态鉴权、分布式缓存、工作流引擎等核心能力。

## ✨ 核心特性

- **DDD + CQRS 架构** — 严格的四层分层（接口层 / 应用层 / 领域层 / 基础设施层），Command/Query 职责分离
- **RBAC 权限体系** — 用户-角色-权限多对多模型，支持多租户、用户组、组织架构
- **JWT 无状态鉴权** — Apache Shiro 2.0 + JWT Token，禁用 Session，支持多种登录方式（账号密码/手机验证码/邮箱验证码）
- **国密加密** — 内置 SM4 对称加密（对象池优化）、Google Tink 加密引擎、BCrypt 密码哈希
- **分布式 ID 生成** — 基于 Snowflake 的 UID 生成器，支持 RingBuffer 缓冲预分配
- **工作流引擎** — 集成 Flowable，独立数据源配置
- **Netty 通信** — Modbus TCP 协议客户端/服务端实现
- **MQTT 集成** — Spring Integration MQTT 消息收发
- **API 文档** — Knife4j (OpenAPI 3) 自动生成

## 🛠 技术栈

| 类别 | 技术 | 版本 |
|------|------|------|
| 运行时 | Java | 17 |
| 框架 | Spring Boot | 3.5.0 |
| 安全框架 | Apache Shiro | 2.0.6 |
| ORM | Spring Data JPA + QueryDSL | 5.1.0 |
| 数据库 | MySQL | 8.3.0 |
| 缓存 | Redisson + Spring Data Redis | 3.44.0 |
| 工作流 | Flowable | 6.8.1 |
| 集成 | Apache Camel | 4.10.3 |
| 脚本引擎 | Groovy | 4.0.26 |
| API 文档 | Knife4j (OpenAPI 3) | 4.5.0 |
| Token | JJWT | 0.12.6 |
| 加密 | Google Tink / 国密 SM4 | - |
| 对象映射 | MapStruct | 1.5.5 |
| 工具库 | Hutool / Guava / Apache Commons | - |
| 文档处理 | Apache POI / PDFBox | 5.4.0 / 3.0.0 |
| 本地缓存 | Caffeine | - |
| 构建 | Maven | - |

## 📐 架构设计

### 分层架构

```mermaid
graph TB
    subgraph "接口层 interfaces / adapter"
        Controller["Controller<br/>参数校验 & DTO/VO 转换"]
        Facade["ServiceFacade<br/>用例编排门面"]
    end

    subgraph "应用层 app / command"
        AppService["ApplicationService<br/>用例编排 & 事务边界"]
        CommandHandler["CommandHandler<br/>命令处理器"]
    end

    subgraph "领域层 domain"
        DomainModel["Aggregate / Entity<br/>聚合根 & 实体"]
        DomainService["DomainService<br/>领域服务"]
        DomainEvent["DomainEvent<br/>领域事件"]
    end

    subgraph "基础设施层 infrastructure / framework"
        RepositoryImpl["Repository Impl<br/>数据持久化"]
        ExternalAPI["External API<br/>外部服务封装"]
        Framework["Framework<br/>通用技术组件"]
    end

    Controller --> Facade
    Facade --> AppService
    AppService --> CommandHandler
    CommandHandler --> DomainService
    DomainService --> DomainModel
    DomainModel --> DomainEvent
    DomainService --> RepositoryImpl
    RepositoryImpl --> ExternalAPI
    AppService --> Framework
```

### RBAC 权限模型

```mermaid
erDiagram
    SysUser ||--o{ SysUserRole : "用户-角色关联"
    SysRole ||--o{ SysUserRole : "角色-用户关联"
    SysRole ||--o{ SysPermission : "角色-权限关联"
    SysUser }|--|{ SysUserGroup : "用户组"
    SysUser }|--|{ SysOrg : "组织架构"
    SysUser }|--|{ SysTenant : "租户"
```

## 📁 目录结构

```
com.w2.springtemplate
├── adapter/                    # [接口层] 处理页面请求的 Controller
├── app/                        # [应用层] 处理 request，包括 command 和 query
├── client/                     # [对外接口] 对外暴露的接口或对象
├── command/                    # [CQRS] Command 定义及 Handler
│   └── user/
│       ├── RegisterSysUserCommand.java
│       ├── ChangePasswordCommand.java
│       └── handler/            # Command Handler 实现
├── common/
│   └── config/                 # 统一配置（JPA / Knife4j / Redis / Shiro）
├── domain/                     # [领域层] 领域模型 & 领域服务
│   ├── experimental/           # DDD 实验性基类（Entity / ValueObject）
│   ├── model/user/             # 用户聚合（实体 & DTO）
│   └── service/                # 领域服务
│       ├── role/
│       ├── user/
│       └── userGroup/
├── framework/                  # [框架层] 通用技术基础设施
│   ├── command/                # CQRS 框架（Handler 分发 & 运行环境）
│   ├── constants/              # 常量 & Redis Key 前缀
│   ├── encrypt/gm/sm4/         # 国密 SM4 加密（对象池优化）
│   ├── encrypt/tink/           # Google Tink 加密引擎
│   ├── event/guava/            # Guava EventBus 事件总线
│   ├── fsg/uid/                # 分布式 UID 生成器（Snowflake + RingBuffer）
│   ├── handlers/               # 通用 Handler & 登录事件处理
│   ├── io/                     # I/O 工具（PDF / 字体）
│   ├── jpa/                    # JPA 基础设施（BaseEntity / ID 生成器 / Auditor）
│   ├── logback/                # Logback 自定义配色
│   ├── netty/
│   │   ├── modjn/              # Modbus TCP 协议实现（客户端 & 服务端）
│   │   └── study/              # Netty 学习示例
│   ├── oos/client/             # 对象存储客户端（SangFor OOS）
│   ├── shiro/                  # Shiro 扩展
│   │   ├── authc/              # 多 Realm 认证策略
│   │   ├── bcrypt/             # BCrypt 密码服务
│   │   ├── cache/              # Shiro Redis 缓存
│   │   ├── filter/             # JWT Bearer & 账号登录过滤器
│   │   ├── jwt/                # JWT 工具类
│   │   ├── realm/              # 多登录方式 Realm（账号/手机/邮箱）
│   │   └── session/            # 无 Session Subject 工厂
│   ├── vfs/                    # Apache VFS 虚拟文件系统
│   └── workflow/               # Flowable 工作流配置
├── infrastructure/             # [基础设施层] Repository 实现 & Service 实现
│   ├── converters/             # 对象转换器
│   ├── repository/             # JPA Repository 接口
│   └── serviceImpl/            # 领域服务实现
├── interfaces/                 # [接口层] 对外用户交互及接口
│   ├── user/
│   │   ├── controller/         # 用户 Controller
│   │   ├── facade/             # 用户服务门面 & DTO
│   │   └── internal/           # 门面实现
│   └── web/                    # 通用 Web 控制器（登录 / 测试等）
├── model/                      # 模型 & 参数对象
└── utils/                      # 工具类（BCrypt / Redis）
```

## 🔧 核心模块说明

### 安全认证（Shiro + JWT）

- **无状态鉴权**：禁用 Session，采用 JWT Token 方式，Token 通过 Redis 管理
- **多 Realm 支持**：`UserAccountRealm`（账号密码）、`PhoneCodeRealm`（手机验证码）、`EmailCodeRealm`（邮箱验证码）
- **密码安全**：BCrypt 哈希 + 登录失败重试限制（`RetryPasswordCredentialsMatcher`）
- **过滤器链**：`BearerAuthenticFilter`（JWT Bearer 认证）、`UserAccountLoginFilter`（账号登录）

### 加密引擎

- **SM4 国密加密**：`SM4Cipher` + `SM4CipherPool`（基于 Apache Commons Pool 对象池），支持多种模式（`SM4Mode`）
- **Google Tink**：`TinkEncryptor` 提供通用加密能力

### 分布式 UID 生成

- **Snowflake 算法**：`DefaultUidGenerator`（默认）和 `CachedUidGenerator`（RingBuffer 缓冲预分配，高性能）
- **Worker ID 分配**：`DisposableWorkerIdAssigner` 基于数据库自动分配 Worker ID，支持 Docker 环境

### Netty Modbus 通信

- **Modbus TCP 协议**：完整的客户端/服务端实现，包含编解码器（`ModbusDecoder` / `ModbusEncoder`）
- **功能码支持**：WriteSingleCoil、WriteSingleRegister 等

### 工作流引擎

- **Flowable 集成**：独立数据源配置（`w2_flowable` 数据库），通过 `FlowableProcessor` 控制开关

### 事件总线

- **Guava EventBus**：`W2EventBusProvider` 提供进程内事件发布/订阅能力，支持 `W2Event` / `W2Listener` 自定义扩展

## 🚀 快速开始

### 环境要求

- **JDK** 17+
- **MySQL** 8.0+
- **Redis** 6.0+
- **Maven** 3.8+

### 数据库配置

1. 创建业务数据库：

```sql
CREATE DATABASE `w2-api` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

2. 如需工作流功能，创建工作流数据库：

```sql
CREATE DATABASE `w2_flowable` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

3. 修改 [`src/main/resources/application.yml`](src/main/resources/application.yml) 中的数据库连接信息：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/w2-api?allowPublicKeyRetrieval=true
    username: root
    password: your_password
```

### Redis 配置

修改 [`src/main/resources/application.yml`](src/main/resources/application.yml) 中的 Redis 连接信息：

```yaml
spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password: your_redis_password
```

### 构建与运行

```bash
# 编译打包
./mvnw clean package -DskipTests

# 运行
java -jar target/spring-template-0.0.1-SNAPSHOT.jar

# 或使用 Maven 直接运行
./mvnw spring-boot:run
```

服务默认启动端口：**19999**

### API 文档

启动后访问 Knife4j API 文档：

```
http://localhost:19999/doc.html
```

## 📄 许可证

本项目基于 [LICENSE](LICENSE) 文件中声明的许可证发布。