# quickstart

**Repository Path**: feizns/quickstart

## Basic Information

- **Project Name**: quickstart
- **Description**: 快速开发常用组件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: https://gitee.com/feizns/quickstart
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 2
- **Created**: 2022-09-19
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickStart 快速开发脚手架

## 项目简介

QuickStart 是一个基于 Spring Boot 2.7.18 的 Java 快速开发脚手架项目，采用 Maven 多模块架构，提供了一套完整的基础架构和常用工具模块，帮助开发者快速构建企业级应用。

## 技术栈

- **Java**: 1.8
- **Spring Boot**: 2.7.18
- **构建工具**: Maven
- **数据库**: MySQL (支持 MyBatis-Plus、MyBatis-Flex、Spring Data JPA)
- **权限认证**: Sa-Token 1.44.0
- **JSON处理**: Fastjson2 2.0.24、Jackson
- **其他**: 钉钉集成、MQTT、Excel处理、二维码生成、规则引擎等

---

## 项目结构

项目采用多模块架构，按功能分类如下：

### 核心基础模块

1. **quickstart-domain** - 通用领域模型
2. **quickstart-web** - Web 功能增强
3. **quickstart-spring** - Spring 容器工具封装
4. **quickstart-validation** - 数据校验增强

### 数据持久化模块

5. **quickstart-mybatis-plus** - MyBatis-Plus 增强
6. **quickstart-mybatis-flex** - MyBatis-Flex 增强
7. **quickstart-spring-data-jpa** - Spring Data JPA 增强

### 权限认证模块

8. **quickstart-sa-token** - Sa-Token 权限认证封装

### 工具类模块

9. **quickstart-jackson** - Jackson JSON 处理增强
10. **quickstart-easyexcel** - Excel 处理工具
11. **quickstart-zxing** - 二维码生成工具
12. **quickstart-caffeine** - Caffeine 本地缓存封装
13. **quickstart-expiring-map** - 过期 Map 封装
14. **quickstart-mapdb** - MapDB 持久化 KV 数据库
15. **quickstart-quickio** - QuickIO 文档数据库
16. **quickstart-ql-express** - 阿里规则引擎 QLExpress
17. **quickstart-mustache** - Mustache 字符串模板引擎
18. **quickstart-janino** - Janino 动态 Java 代码执行
19. **quickstart-liquor** - Liquor 动态 Java 代码执行
20. **quickstart-graalvm** - GraalVM 多语言支持
21. **quickstart-graalvm-js** - GraalVM JavaScript 引擎
22. **quickstart-modbus** - Modbus 工业通信协议
23. **quickstart-vertx** - Vert.x 异步编程框架
24. **quickstart-itext7** - iText7 PDF 操作
25. **quickstart-javacv** - JavaCV 音视频处理
26. **quickstart-easy-captcha** - EasyCaptcha 验证码生成
27. **quickstart-file-storage** - 自定义文件存储系统

### 第三方服务集成模块

28. **quickstart-alipay** - 支付宝 SDK 封装
29. **quickstart-aliyun-oss** - 阿里云 OSS 对象存储
30. **quickstart-qi-niu** - 七牛云对象存储
31. **quickstart-ding-talk** - 钉钉开放平台集成
32. **quickstart-mqtt** - MQTT 消息队列
33. **quickstart-td-engine** - TDengine 时序数据库

### 功能增强模块

34. **quickstart-dict** - 数据字典管理
35. **quickstart-log** - 日志增强（方法日志、操作日志）
36. **quickstart-code-generator** - 代码生成器
37. **quickstart-ddl-annotation** - DDL 注解支持

### Spring Boot Starter 模块

所有核心模块都提供了对应的 Spring Boot Starter：

- `quickstart-web-spring-boot-starter` - Web 功能自动配置
- `quickstart-mybatis-plus-spring-boot-starter` - MyBatis-Plus 自动配置
- `quickstart-mybatis-flex-spring-boot-starter` - MyBatis-Flex 自动配置
- `quickstart-validation-spring-boot-starter` - 数据校验自动配置
- `quickstart-sa-token-spring-boot-starter` - Sa-Token 自动配置
- `quickstart-dict-spring-boot-starter` - 数据字典自动配置
- `quickstart-log-spring-boot-starter` - 日志增强自动配置
- `quickstart-mqtt-spring-boot-starter` - MQTT 自动配置
- `quickstart-ding-talk-spring-boot-starter` - 钉钉集成自动配置
- `quickstart-spring-boot-starter` - 基础工具自动配置

---

## 模块详细说明

### 1. quickstart-domain - 通用领域模型

提供通用的领域模型和数据结构。

#### 核心类

- **`Id<T>`** - ID 接口，标识实体具有 ID 属性
- **`Ret<T>`** - 统一响应结果封装
  - `Ret.ok()` - 无数据成功响应
  - `Ret.ok(data)` - 成功响应（带数据）
  - `Ret.ok(supplier)` - 通过 Supplier 提供数据的成功响应
  - `Ret.ok(runnable)` - 执行 Runnable 后的成功响应
  - `Ret.badRequest(msg)` / `Ret.badRequest(msg, data)` - 请求错误响应（400）
  - `Ret.unauthorized(msg)` / `Ret.unauthorized(msg, data)` - 未授权响应（401）
  - `Ret.error(msg)` - 错误响应（500）
  - `Ret.error(code, msg)` - 错误响应（指定错误码）
  - `Ret.error(code, msg, data)` - 错误响应（指定错误码和数据）
  - `Ret.create(code, msg, data)` - 创建响应对象
  - `unpack()` - 如果 data 是单元素数组则解开数组
- **`PageAo`** - 分页请求对象
  - `DollarPageAo` - 支持 `$current`、`$size`、`$offset`、`$limit` 参数
  - `LimitAo` - 支持 `offset` 和 `limit` 参数
- **`PageVo<T>`** - 分页信息对象（当前页、每页条数、总数）
- **`PageRecordsVo<T>`** - 分页响应对象（包含分页信息和数据列表）
- **`QueryAo`** - 通用查询接口
- **`Relationship<T, M, S>`** - 关系映射接口（一对多、多对多）
- **`TreeNode<T, ID>`** - 树形节点接口
  - `getParentId()` - 获取父节点 ID
  - `children()` - 获取子节点列表
  - `descendants()` - 获取所有子孙节点
  - `root()` - 获取根节点
- **`TreeVo<T>`** - 树形结构视图对象
- **`Types`** - 数据库类型常量（JSON、TEXT、BIGINT 等）

#### 使用示例

```java
// 统一响应
return Ret.ok(user);  // 成功响应
return Ret.error("操作失败");  // 错误响应
return Ret.badRequest("参数错误");  // 请求错误响应
return Ret.unauthorized("未授权");  // 未授权响应

// 分页请求
PageAo pageAo = new DollarPageAo();
pageAo.setCurrent(1);
pageAo.setSize(10);

// 分页响应
PageRecordsVo<User> result = PageRecordsVo.of(page, users);

// 树形结构
public class Dept implements TreeNode<Dept, Long> {
    private Long id;
    private Long parentId;
    
    @Override
    public Long getId() { return id; }
    
    @Override
    public Long getParentId() { return parentId; }
    
    @Override
    public List<Dept> children() { 
        // 返回子部门列表
        return children;
    }
}
```

---

### 2. quickstart-web - Web 功能增强

提供 Web 开发相关的增强功能，包括异常处理、参数解析、数据加解密、限流等。

#### 核心功能

##### 2.1 统一异常处理

- **`ExceptionHandler<T>`** - 异常处理器接口，支持异常链中的匹配（原因优先匹配原则）
- **`GlobalRestfulExceptionAdvice`** - 全局 RESTful 异常处理
- **`ErrorCode`** - 错误码接口，包含 `getCode()` 和 `getMsg()` 方法
- **`@ErrorCodeMapper`** - 错误码映射注解
  - `value()` - 错误消息
  - `code()` - 错误码（默认 500）
  - `status()` - HTTP 响应码（默认 OK）

支持的异常类型：
- `ServiceException` - 业务异常（实现 `ErrorCode` 接口）
- `BadRequestException` - 请求错误（HTTP 400）
- `NotFoundException` - 资源不存在（HTTP 404）
- `UnauthorizedException` - 未授权（HTTP 401）
- `BindException` - 绑定异常
- `ConstraintViolationException` - 校验异常
- `MethodArgumentNotValidException` - 参数校验异常
- `HttpException` - HTTP 异常

```java
// 自定义异常
@ErrorCodeMapper(value = "用户不存在", code = 404)
public class UserNotFoundException extends NotFoundException {
    public UserNotFoundException(Long id) {
        super("用户不存在: " + id);
    }
}

// 抛出业务异常
throw new ServiceException("用户已存在");
```

##### 2.2 参数解析

- **`@Json`** - JSON 参数解析注解（支持 GET 请求中的 JSON 参数）
- **`JsonParameterResolver`** - JSON 参数解析器
- **`AbstractServletModelAttributeMethodProcessor`** - 增强的参数绑定处理器

```java
// GET 请求中使用 JSON 参数
@GetMapping("/user")
public Ret<List<User>> query(@Json UserQuery query) {
    // GET /user?username={"$contains":"admin"}
    return Ret.ok(userService.query(query));
}
```

##### 2.3 数据加解密

- **`@Decrypt`** - 自动解密注解
- **`DecryptParameterResolver`** - 参数解密解析器
- **`DecryptServletModelAttributeMethodProcessor`** - 表单参数解密处理器
- **`DecryptStdDeserializer`** - JSON 请求体解密反序列化器
- **`DecryptionAlgorithm`** - 解密算法接口
- **`DecryptionAlgorithmPrivateKeySupplier`** - 私钥提供者接口
- **`CryptoRequestResponseBodyAdvice`** - 请求响应加解密增强

```java
// 使用 @Decrypt 注解自动解密
@PostMapping("/secure")
public Ret<String> secure(@Decrypt @RequestBody SecureData data) {
    // data 已自动解密
    return Ret.ok("success");
}
```

##### 2.4 通用查询

支持 RESTful 风格的通用查询接口，提供 `QueryBodyAo`（用于请求体）和 `QueryParamsAo`（用于 GET 请求参数）两种方式。

**GET 请求示例：**
```
GET /api/v1/user?username={"$contains":"hhp"}
GET /api/v1/user?id={"$eq":1}
GET /api/v1/user?$current=1&$size=10
```

**POST/PUT 请求示例：**
```json
{
    "username": {"$contains": "hhp"},
    "$current": 1,
    "$size": 10
}
```

**支持的查询操作符：**

字段操作符：
- `$eq` - 等于（`id = 5`），可简写为 `{"id": 5}`
- `$ne` - 不等于（`id != 5`）
- `$gt` - 大于（`id > 5`）
- `$ge` - 大于等于（`id >= 5`）
- `$lt` - 小于（`id < 5`）
- `$le` - 小于等于（`id <= 5`）
- `$in` - IN 查询（`id IN (5, 6)`），示例：`{"id": {"$in": [5, 6]}}`
- `$contains` - 模糊匹配（`name LIKE '%hhp%'`），示例：`{"name": {"$contains": "hhp"}}`
- `$startWith` - 左匹配（`name LIKE 'hhp%'`），示例：`{"name": {"$startWith": "hhp"}}`
- `$endWith` - 右匹配（`name LIKE '%hhp'`），示例：`{"name": {"$endWith": "hhp"}}`
- `$between` - 范围查询（`id BETWEEN 5 AND 10`），示例：`{"id": {"$between": [5, 10]}}`
- `$regexp` - 正则匹配（`name REGEXP 'hhp$'`），示例：`{"name": {"$regexp": "hhp$"}}`
- `$jsonContains` - JSON 包含查询（`JSON_CONTAINS(user_list, '5')`）

其他设置：
- `$select` - 指定查询字段（`SELECT id, name`），示例：`{"$select": ["id", "name"]}`
- `$from` - 指定查询表（`FROM user`），示例：`{"$from": "user"}`
- `$and` - AND 条件（`id = 1 AND name = 'hhp'`），示例：`{"$and": [{"id": 1}, {"name": "hhp"}]}`
- `$or` - OR 条件（`id = 1 OR name = 'hhp'`），示例：`{"$or": [{"id": 1}, {"name": "hhp"}]}`
- `$not` - NOT 条件（`NOT (id = 1 AND name = 'hhp')`），示例：`{"$not": [{"id": 1}, {"name": "hhp"}]}`
- `$order` - 排序（`ORDER BY createTime ASC, name DESC`），示例：`{"$order": [{"column": "createTime", "asc": true}, {"column": "name"}]}`
- `$asc` - 多字段升序（`ORDER BY id ASC, name ASC`），示例：`{"$asc": ["id", "name"]}`
- `$desc` - 多字段降序（`ORDER BY id DESC, name DESC`），示例：`{"$desc": ["id", "name"]}`
- `$group` - 分组（`GROUP BY id, name`），示例：`{"$group": ["id", "name"]}`
- `$null` - 是否为 NULL（`id IS NULL AND name IS NULL`），示例：`{"$null": ["id", "name"]}`
- `$offset` / `$limit` - 偏移查询（`LIMIT 10, 10`），示例：`{"$offset": 10, "$limit": 10}`
- `$keyword` - 多字段关键字查询（`CONCAT_WS('', id, name) LIKE '%hhp%'`），示例：`{"$keyword": {"columns": ["id", "name"], "operator": "$likeLeft", "value": "hhp"}}`

分页参数：
- `$current` - 当前页码（默认 1）
- `$size` - 每页条数（默认 10）
- `$limit` - 数据上限（-1 表示查询全部数据）

JsonPath 语法：
- 支持 JSON 字段深度筛选，示例：`{"user$.id": {"$eq": 1}}`（使用 MySQL JsonPath 语法）

**通用分页响应格式：**
```json
{
    "page": {
        "current": 1,
        "size": 10,
        "total": 100
    },
    "records": [
        // 数据项
    ]
}
```

##### 2.5 RESTful API 工具

- **`Rests`** - RESTful API 工具类
  - `Rests.create(recordClass, ao)` - 创建资源
  - `Rests.putById(record, id)` - 更新资源
  - `Rests.patchById(record, id)` - 部分更新资源
  - `Rests.deleteById(recordClass, id)` - 删除资源
  - `Rests.getById(recordClass, id)` - 获取资源
  - `Rests.page(recordClass, pageAo, ...)` - 分页查询
  - `Rests.crud(recordClass)` - 通用 CRUD（根据 HTTP 方法自动判断）
  - `Rests.crudById(recordClass, id)` - 根据 ID 的 CRUD

- **`RestExecutor`** - RESTful API 执行器接口
- **`@RestType`** - RESTful 类型注解（可指定资源名称和 ID 字段名）
- **`RestListener`** - RESTful 操作监听器

```java
// 使用 Rests 工具类
@RestController
@RequestMapping("/api/users")
public class UserController {
    
    @GetMapping
    public Ret<PageRecordsVo<User>> page(PageAo pageAo, QueryBodyAo query) {
        return Ret.ok(Rests.page(User.class, pageAo, query));
    }
    
    @PostMapping
    public Ret<User> create(@RequestBody UserAo ao) {
        return Ret.ok(Rests.create(User.class, ao));
    }
    
    @PutMapping("/{id}")
    public Ret<User> update(@PathVariable Long id, @RequestBody UserAo ao) {
        return Ret.ok(Rests.putById(User.class, ao, id));
    }
    
    @DeleteMapping("/{id}")
    public Ret<Void> delete(@PathVariable Long id) {
        Rests.deleteById(User.class, id);
        return Ret.ok();
    }
    
    // 通用 CRUD（自动根据 HTTP 方法判断操作）
    @RequestMapping("/crud")
    public Object crud() {
        return Rests.crud(User.class);
    }
}
```

##### 2.6 限流功能

- **`@RateLimit`** - 限流注解
- **`@Qps` / `@Qps1` / `@Qps5` / `@Qps10` / `@Qps30` / `@Qps60` / `@Qps90` / `@Qps120`** - 不同 QPS 限制的注解
- **`@NoRepeat`** - 防重复提交注解
- **`CaffeineRateLimitInterceptor`** - 基于 Caffeine 的限流拦截器
- **`RateLimitHandler`** - 限流处理器接口

```java
@RestController
public class ApiController {
    
    @GetMapping("/api/public")
    @Qps60  // 限制每秒60次请求
    public Ret<String> publicApi() {
        return Ret.ok("public data");
    }
    
    @PostMapping("/api/submit")
    @NoRepeat  // 防重复提交
    public Ret<String> submit(@RequestBody SubmitData data) {
        return Ret.ok("success");
    }
}
```

##### 2.7 HMAC 签名验证

- **`@HMAC`** - HMAC 签名验证注解
- **`HMACInterceptor`** - HMAC 拦截器
- **`CaffeineHMACInterceptor`** - 基于 Caffeine 的 HMAC 拦截器

##### 2.8 日期类型支持

支持 Java8 各日期类型的自动转换（Year、YearMonth、LocalDate、LocalDateTime 等）：
- **`ToDateConverterFactory`** - 日期转换器工厂
- **`ToTemporalAccessorConverterFactory`** - 时间类型转换器工厂

##### 2.9 枚举转换

- **`@EnumValue`** - 枚举值注解
- **`EnumValueConverterFactory`** - 枚举转换器工厂
- **`StringToEnumConverter`** - 字符串转枚举转换器
- **`StringToEnumsIgnoreCaseConverterFactory`** - 忽略大小写的枚举转换器工厂

##### 2.10 Web 工具类

- **`WebUtils`** - Web 环境工具类
  - `getIpAddress()` - 获取客户端真实 IP
  - `getReqHeader(name)` - 获取请求头
  - `getUserAgent()` - 获取 User-Agent
  - `getRequestBodyAsString()` - 获取请求体字符串
  - `getRequestURL()` - 获取完整请求 URL
  - `getRequestURI()` - 获取请求 URI
  - `getServerName()` - 获取服务器地址
  - `setFileHeaderToResp(filename)` - 设置文件下载响应头
  - `requestParamsBindTo(targetClass)` - 将请求参数绑定到对象

```java
// 获取客户端 IP
String ip = WebUtils.getIpAddress();

// 获取请求头
String userAgent = WebUtils.getUserAgent();

// 获取请求体
String body = WebUtils.getRequestBodyAsString();

// 设置文件下载
WebUtils.setFileHeaderToResp("report.xlsx");
```

##### 2.11 跨域支持

- **`@Cross`** - 跨域注解

##### 2.12 请求体缓存

- **`CachingRequestBodyFilter`** - 请求体缓存过滤器

##### 2.13 JSONPath 过滤

- **`JsonPathFilterResponseBodyAdvice`** - JSONPath 过滤响应体增强

---

### 3. quickstart-mybatis-plus - MyBatis-Plus 增强

对 MyBatis-Plus 进行功能增强，提供更便捷的数据库操作。

#### 核心功能

##### 3.1 通用查询构建器

- **`Query`** - 通用查询工具类
  - `Query.of(conditional)` - 从条件对象构建 QueryWrapper
  - `Query.of(queryWrapper, conditional)` - 在现有 QueryWrapper 上添加条件
  - `Query.page(pageAo)` - 创建分页对象

支持的查询操作符（与 quickstart-web 保持一致）：
- 字段内操作符：`$eq`、`$ne`、`$in`、`$gt`、`$ge`、`$lt`、`$le`、`$contains`、`$startWith`、`$endWith`、`$between`、`$regexp`、`$jsonContains`
- 字段外操作符：`$keyword`、`$and`、`$or`、`$not`
- 配置操作符：`$select`、`$group`、`$order`、`$asc`、`$desc`、`$null`、`$limit`、`$offset`

```java
// 构建查询条件
Map<String, Object> conditions = new HashMap<>();
conditions.put("username", Map.of("$contains", "admin"));
conditions.put("status", Map.of("$eq", 1));

QueryWrapper<User> wrapper = Query.of(User.class, conditions);
List<User> users = userMapper.selectList(wrapper);

// 分页查询
PageAo pageAo = new DollarPageAo(1, 10);
Page<User> page = Query.page(pageAo);
IPage<User> result = userMapper.selectPage(page, wrapper);
PageRecordsVo<User> pageVo = Query.pageRecordsVo(page);
```

##### 3.2 SQL 注入器增强

- **`QuickstartMybatisPlusSqlInjector`** - 增强的 SQL 注入器
  - 自动添加批量插入方法
  - 自动添加分页查询方法
  - 自动添加部分更新方法

##### 3.3 自动填充

- **`@AutoFill`** - 自动填充注解
- **`AutoFillAnnotationInnerInterceptor`** - 自动填充拦截器
- **`AutoFillStrategy`** - 自动填充策略接口
- **`AutoFillNowStrategy`** - 当前时间自动填充策略

```java
public class User {
    @AutoFill(AutoFillType.INSERT)
    private LocalDateTime createTime;
    
    @AutoFill(AutoFillType.INSERT_UPDATE)
    private LocalDateTime updateTime;
}
```

##### 3.4 JSON 类型处理器

- **`JsonTypeHandler<T>`** - JSON 类型处理器接口
- **`JacksonGenericTypeHandler<T>`** - 基于 Jackson 的通用 JSON 处理器
- **`Fastjson2GenericTypeHandler<T>`** - 基于 Fastjson2 的通用 JSON 处理器
- **`MapJsonTypeHandler`** - Map 类型 JSON 处理器
- **`ListJsonTypeHandler`** - List 类型 JSON 处理器
- **`SetJsonTypeHandler`** - Set 类型 JSON 处理器

```java
// 使用 JSON 类型字段
@TableField(typeHandler = JacksonGenericTypeHandler.class)
private Map<String, Object> metadata;
```

##### 3.5 分页对象

- **`Page<T>`** - 增强的分页对象（继承自 MyBatis-Plus 的 Page）
- **`MybatisPlusPageRecordsVoImpl<T>`** - MyBatis-Plus 分页响应实现

##### 3.6 数据库工具

- **`Mysql`** - MySQL 数据库工具类
  - `Mysql.truncate(type)` - 清空表
  - `Mysql.select(sql)` - 执行查询
  - `Mysql.database()` - 获取当前数据库名
  - `Mysql.tables()` - 获取所有表名
  - `Mysql.columns(type)` - 获取表的列信息

##### 3.7 列信息

- **`Column`** - 数据库列信息对象

##### 3.8 工具类

- **`WrapperUtils`** - Wrapper 工具类
- **`Mappers`** - Mapper 工具类

##### 3.9 数据校验

- **`@Exist`** - 存在性校验注解
- **`@NotExist`** - 不存在校验注解
- **`@ExistId`** - ID 存在性校验注解
- **`@NotExistsId`** - ID 不存在校验注解

```java
public class UserAo {
    @NotExistsId(message = "用户已存在")
    private Long id;
    
    @NotExist(table = "user", column = "username", message = "用户名已存在")
    private String username;
}
```

---

### 4. quickstart-mybatis-flex - MyBatis-Flex 增强

对 MyBatis-Flex 进行功能增强，提供类似 MyBatis-Plus 的增强功能。

#### 核心功能

类似 `quickstart-mybatis-plus`，但基于 MyBatis-Flex 实现：
- 通用查询构建器
- JSON 类型处理器
- 分页对象
- 数据校验
- 关系映射（`Relationships`）

---

### 5. quickstart-validation - 数据校验增强

扩展 Java Bean Validation，提供更多自定义校验注解和功能。

#### 核心功能

##### 5.1 验证工具

- **`ValidationUtils`** - 验证工具类
  - `validate(bean, groups)` - 验证并返回结果
  - `validateIfFailsThenThrow(bean, groups)` - 验证失败则抛出异常
  - `setValidator(validator)` - 设置自定义验证器

##### 5.2 可验证对象

- **`Verifiable`** - 可验证对象接口
- **`Validator`** - 动态验证器接口

##### 5.3 自定义校验注解

- **`@DynamicValidate`** - 动态验证注解，可指定多个 `Validator` 实现类
  - 如果对象实现了 `Verifiable` 接口，会自动调用 `validate()` 方法
- **`@Account`** - 账号格式校验（支持中文、字母、数字、下划线、连字符）
  - `min()` - 最小长度（默认 1）
  - `max()` - 最大长度（默认 Integer.MAX_VALUE）
  - `regexp()` - 正则表达式（默认：`[\\u4e00-\\u9fa5a-zA-Z\\d-_]*`）
- **`@Phone`** - 手机号格式校验
- **`@Words`** - 字符限制校验，验证字符、数组或集合中的数据是否都在指定的字符序列中
  - `value()` - 允许的字符序列数组
- **`@Enums`** - 枚举值校验，验证值、数组或集合中的数据是否都在指定的枚举序列中
  - `value()` - 枚举类型数组（`Class<? extends Enum>[]`）

```java
public class UserAo implements Verifiable {
    @NotBlank(message = "用户名不能为空")
    @Account(min = 3, max = 20, message = "用户名格式不正确")
    private String username;
    
    @Phone(message = "手机号格式不正确")
    private String phone;
    
    @Enums(value = {UserStatus.class}, message = "状态值不正确")
    private UserStatus status;
    
    @Words(value = {"ACTIVE", "INACTIVE"}, message = "状态值不正确")
    private String statusStr;
    
    @DynamicValidate({CustomValidator.class})
    private String customField;
    
    @Override
    public boolean validate() {
        // 自定义验证逻辑，实现 Verifiable 接口后会自动调用
        return username != null && username.length() >= 3;
    }
}

// 手动验证
ValidationUtils.validateIfFailsThenThrow(userAo);
```

##### 5.4 正则表达式工具

- **`Regexps`** - 常用正则表达式常量

---

### 6. quickstart-sa-token - Sa-Token 权限认证封装

对 Sa-Token 权限认证框架进行封装，简化用户会话管理。

#### 核心功能

##### 6.1 用户接口

- **`User<T>`** - 用户接口（标识用户具有 ID 属性）

##### 6.2 会话工具

- **`UserStpLogic<ID, T>`** - 用户会话工具类
  - `current()` - 获取当前登录用户（未登录抛出异常）
  - `currentDefaultNull()` - 获取当前登录用户（未登录返回 null）
  - `current(defaultVal)` - 获取当前登录用户（不存在返回默认值）
  - `current(id)` - 获取指定 ID 的用户
  - `current(mapper)` - 获取当前用户的某个属性
  - `onlineUsers()` - 获取所有在线用户列表
  - `login(user)` - 用户登录（返回 token）
  - `logout()` - 当前用户登出
  - `logout(id)` - 指定用户登出
  - `getSessionOrNull()` - 获取会话（不存在返回 null）

```java
// 定义用户实体
public class User implements User<Long> {
    private Long id;
    private String username;
    
    @Override
    public Long getId() {
        return id;
    }
}

// 使用会话工具
@Service
public class AuthService {
    private final UserStpLogic<Long, User> userStpLogic;
    
    public AuthService() {
        this.userStpLogic = new UserStpLogic<>(User.class);
    }
    
    // 登录
    public String login(User user) {
        return userStpLogic.login(user);
    }
    
    // 获取当前用户
    public User getCurrentUser() {
        return userStpLogic.current();
    }
    
    // 获取在线用户
    public List<User> getOnlineUsers() {
        return userStpLogic.onlineUsers();
    }
    
    // 登出
    public void logout() {
        userStpLogic.logout();
    }
}
```

---

### 7. quickstart-jackson - Jackson JSON 处理增强

提供 Jackson JSON 处理的增强功能。

#### 核心功能

- **`QuickstartObjectMapper`** - 增强的 ObjectMapper
- **`JsonUtils`** - JSON 工具类
- **`Val`** - JSON 值封装（类似 Gson 的 JsonElement）
- **`JPath`** - JSONPath 支持

##### 注解

- **`@JsonArrayAsObject`** - 数组作为对象处理
- **`@JsonDeduplicate`** - JSON 去重
- **`@JsonIgnorePrimitive`** - 忽略原始类型
- **`@JsonToSingletonArray`** - 转换为单元素数组

##### 序列化器/反序列化器

- **`Java8TimeSerializer`** / **`Java8TimeDeserializer`** - Java8 时间类型支持
- **`DeduplicatingListSerializer`** / **`DeduplicatingListDeserializer`** - 列表去重
- **`JsonArrayAsObjectSerializer`** - 数组作为对象序列化
- **`ToSingletonArraySerializer`** - 单元素数组序列化

##### 过滤器

- **`IgnorePrimitiveSimpleBeanPropertyFilter`** - 忽略原始类型属性过滤器

---

### 8. quickstart-easyexcel - Excel 处理工具

基于 EasyExcel 封装的 Excel 读写工具。

#### 核心功能

- **`EasyExcels`** - Excel 工具类
  - `read(InputStream)` - 读取 Excel 为 Sheet 对象
  - `read(InputStream, Class<T>)` - 读取 Excel 为对象列表
  - `write(OutputStream, Class<T>)` - 写入 Excel

- **`Sheet`** - 工作表封装
- **`SheetReaderListener`** - 工作表读取监听器
- **`Styles`** - 样式工具类
- **`StringUrlImageConverter`** - URL 图片转换器

```java
// 读取 Excel
InputStream is = new FileInputStream("data.xlsx");
Sheet sheet = EasyExcels.read(is);
List<Map<Object, Object>> data = sheet.getData();

// 读取到对象
List<User> users = EasyExcels.read(is, User.class);

// 写入 Excel
OutputStream os = new FileOutputStream("output.xlsx");
EasyExcels.write(os, User.class).sheet("用户列表").doWrite(users);
```

---

### 9. quickstart-zxing - 二维码生成工具

基于 ZXing 封装的二维码和条形码生成工具。

#### 核心功能

- **`Qrcode`** - 二维码工具类
  - `generateBytes(content, width, height)` - 生成二维码字节数组
  - `generateStream(content, width, height)` - 生成二维码输入流
  - `generateImage(content, width, height)` - 生成二维码图片

- **`Barcode`** - 条形码工具类
- **`Images`** - 图片工具类

```java
// 生成二维码
String content = "https://www.example.com";
byte[] qrcodeBytes = Qrcode.generateBytes(content, 400, 400);
InputStream qrcodeStream = Qrcode.generateStream(content, 400, 400);

// 生成条形码
byte[] barcodeBytes = Barcode.generateBytes("123456789012");
```

---

### 10. quickstart-dict - 数据字典管理

提供数据字典的管理功能。

#### 核心功能

- **`Dict`** - 字典接口
- **`Entry`** - 字典条目接口
- **`DictDepositor`** - 字典存储接口
  - `CaffeineDictDepositor` - 基于 Caffeine 的字典存储
  - `ConcurrentHashMapDictDepositor` - 基于 ConcurrentHashMap 的字典存储
  - `NothingToDoDictDepositor` - 空实现

- **`@Values`** - 字典值校验注解

```java
// 使用字典
Dict dict = ...;
Entry entry = dict.get("user_status", "1");
String label = entry.getLabel();

// 字典值校验
public class UserAo {
    @Values(dict = "user_status", message = "状态值不正确")
    private String status;
}
```

---

### 11. quickstart-log - 日志增强

提供日志相关的增强功能。

#### 核心功能

- **`@Log`** - 日志注解
- **`@MethodLog`** - 方法日志注解
- **`LogAroundAspect`** - 日志切面
- **`LogAroundAspectListener`** - 日志切面监听器
- **`LogUserIdSupplier`** - 日志用户 ID 提供者接口
- **`QkLogErrorType`** - 日志错误类型枚举

```java
@Log("用户操作")
@MethodLog
public void createUser(UserAo ao) {
    // 方法执行前后会自动记录日志
    userService.create(ao);
}
```

---

### 12. quickstart-mqtt - MQTT 消息队列

提供 MQTT 消息队列的封装。

#### 核心功能

- **`MqttConnection`** - MQTT 连接封装
  - `pub(topic, msg)` - 发布消息
  - `pub(topic, msg, qos)` - 发布消息（指定 QoS）
  - `sub(topic)` - 订阅主题
  - `sub(topic, qos)` - 订阅主题（指定 QoS）
  - `register(callback)` - 注册回调处理器

```java
// 创建连接
MqttConnection connection = new MqttConnection(
    "tcp://mqtt.example.com:1883",
    "username",
    "password"
);

// 订阅主题
connection.sub("topic/test", 1);

// 注册回调
connection.register((topic, message) -> {
    System.out.println("收到消息: " + new String(message.getPayload()));
});

// 发布消息
connection.pub("topic/test", "Hello MQTT", 1);

// 关闭连接
connection.close();
```

---

### 13. quickstart-ding-talk - 钉钉集成

提供钉钉开放平台的集成功能。

#### 核心功能

- 钉钉 API 封装
- 事件监听器
  - `UserAddOrgListener` - 用户加入组织监听器
  - `UserLeaveOrgListener` - 用户离开组织监听器
  - `UserModifyOrgListener` - 用户修改组织监听器
  - `OrgDeptCreateListener` - 部门创建监听器
  - `OrgDeptModifyListener` - 部门修改监听器
  - `OrgDeptRemoveListener` - 部门删除监听器
- `Utils` - 钉钉工具类

---

### 14. quickstart-spring - Spring 容器工具

提供 Spring 容器相关的工具类。

#### 核心功能

- **`AppUtils`** - 应用工具类
- **`StopWatches`** - 秒表工具类

---

### 15. 其他工具模块

- **quickstart-caffeine** - Caffeine 本地缓存封装
  - `QkCaffeine` - Caffeine 工具类
  - `CacheSet<T>` - 缓存集合

- **quickstart-ql-express** - 阿里规则引擎 QLExpress 封装
  - `QlExpress` - QLExpress 工具类

- **quickstart-code-generator** - 代码生成器
  - `CodeGenerator` - 代码生成器

- **quickstart-aliyun-oss** - 阿里云 OSS 对象存储封装
- **quickstart-alipay** - 支付宝 SDK 封装
- **quickstart-qi-niu** - 七牛云对象存储封装
- **quickstart-graalvm** - GraalVM 多语言支持
- **quickstart-graalvm-js** - GraalVM JavaScript 引擎
- **quickstart-modbus** - Modbus 工业通信协议
- **quickstart-vertx** - Vert.x 异步编程框架
- **quickstart-itext7** - iText7 PDF 操作
- **quickstart-javacv** - JavaCV 音视频处理
- **quickstart-easy-captcha** - EasyCaptcha 验证码生成
- **quickstart-file-storage** - 自定义文件存储系统
- **quickstart-expiring-map** - 过期 Map 封装
- **quickstart-mapdb** - MapDB 持久化 KV 数据库
- **quickstart-quickio** - QuickIO 文档数据库
- **quickstart-mustache** - Mustache 字符串模板引擎
- **quickstart-janino** - Janino 动态 Java 代码执行
- **quickstart-liquor** - Liquor 动态 Java 代码执行
- **quickstart-td-engine** - TDengine 时序数据库

---

## 快速开始

### 1. 环境要求

- JDK 1.8+
- Maven 3.6+
- MySQL 5.7+ (可选)

### 2. 克隆项目

```bash
git clone https://gitee.com/feizns/quickstart.git
cd quickstart
```

### 3. 构建项目

```bash
mvn clean install
```

### 4. 引入依赖

在您的项目中引入需要的 Starter 依赖：

```xml
<dependency>
    <groupId>com.gitee.feizns</groupId>
    <artifactId>quickstart-web-spring-boot-starter</artifactId>
    <version>1.0.1-RELEASE</version>
</dependency>

<dependency>
    <groupId>com.gitee.feizns</groupId>
    <artifactId>quickstart-mybatis-plus-spring-boot-starter</artifactId>
    <version>1.0.1-RELEASE</version>
</dependency>

<dependency>
    <groupId>com.gitee.feizns</groupId>
    <artifactId>quickstart-validation-spring-boot-starter</artifactId>
    <version>1.0.1-RELEASE</version>
</dependency>
```

### 5. 配置文件

在 `application.yml` 中配置相关属性：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/test
    username: root
    password: password
    driver-class-name: com.mysql.cj.jdbc.Driver

# MyBatis-Plus 配置
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      id-type: auto
      logic-delete-field: deleted
      logic-delete-value: 1
      logic-not-delete-value: 0

# Sa-Token 配置
sa-token:
  token-name: token
  timeout: 7200
  token-prefix: Bearer
```

### 6. 使用示例

#### 创建实体类

```java
@Data
@TableName("user")
public class User {
    @TableId(type = IdType.AUTO)
    private Long id;
    
    private String username;
    private String email;
    
    @AutoFill(AutoFillType.INSERT)
    private LocalDateTime createTime;
    
    @AutoFill(AutoFillType.INSERT_UPDATE)
    private LocalDateTime updateTime;
}
```

#### 创建 Mapper

```java
@Mapper
public interface UserMapper extends BaseMapper<User> {
}
```

#### 创建 Service

```java
@Service
public class UserService {
    @Autowired
    private UserMapper userMapper;
    
    public PageRecordsVo<User> page(PageAo pageAo, QueryAo queryAo) {
        Page<User> page = Query.page(pageAo);
        QueryWrapper<User> wrapper = Query.of(User.class, queryAo);
        IPage<User> result = userMapper.selectPage(page, wrapper);
        return Query.pageRecordsVo(page);
    }
}
```

#### 创建 Controller

```java
@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserService userService;
    
    @PostMapping
    public Ret<User> create(@RequestBody @Valid UserAo ao) {
        User user = BeanUtils.copyProperties(ao, User.class);
        userMapper.insert(user);
        return Ret.ok(user);
    }
    
    @GetMapping
    public Ret<PageRecordsVo<User>> page(PageAo pageAo, QueryBodyAo queryAo) {
        return Ret.ok(userService.page(pageAo, queryAo));
    }
}
```

---

## 许可证

本项目采用 MIT 许可证。

---

## 联系方式

如有问题或建议，请通过以下方式联系：

- 项目地址: https://gitee.com/feizns/quickstart
- Issue: https://gitee.com/feizns/quickstart/issues