# 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**: 2026-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QuickStart

<div align="center">

**基于 Spring Boot 3.5.15 的 Java 17 快速开发脚手架**

[![Java](https://img.shields.io/badge/Java-17-blue.svg)](https://www.java.com)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.15-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Modules](https://img.shields.io/badge/Modules-35-orange.svg)]()

</div>

---

QuickStart 是一套采用 Maven 多模块架构的 Java 脚手架，提供 Bean 操作、类型转换、声明式连表、通用查询 DSL、Web 增强、数据校验等基础能力，以及支付宝、钉钉、阿里云 OSS、宝塔面板等第三方集成。

### 适用场景

- 中后台管理系统（ERP、CRM、OA 等）
- RESTful API 服务开发
- 需要统一查询协议的前后端分离项目
- 需要快速集成支付宝、钉钉、OSS 等第三方服务的项目
- 基于 MyBatis-Flex 的数据密集型应用

---

## 核心模块

### quickstart-core — 核心工具

提供 Bean 元数据框架、类型转换系统、反射工具、缓存 Map、加解密等基础能力，是所有其他模块的底座。

#### Bean 操作

Bean 元数据框架，双层架构（元数据层 `BeanAccessor`/`PropAccessor` + 实例层 `Bean`/`Prop`），支持 Lambda 类型安全、泛型保留、Map 互转、运行时动态操作。

```java
// Lambda 方式（类型安全）
Bean<User> bean = Bean.of(user);
bean.set(User::getName, "张三");
String name = bean.get(User::getName);

// 对象复制（保留泛型）
UserDTO dto = Beans.copy(source, UserDTO.class);

// Map 与 Bean 互转
Map<String, Object> map = Beans.asMap(user);
User user = Beans.from(map, User.class);

// 带选项复制（忽略字段、自定义映射）
Options options = Options.defaults()
    .ignoreProperties("id")
    .fieldMapping("userName", "name");
Beans.copy(source, target, options);
```

**与其他 Bean 工具对比：**

| 特性 | Apache BeanUtils | Spring BeanUtils | Hutool BeanUtil | MapStruct | **QuickStart Beans** |
|------|:---:|:---:|:---:|:---:|:---:|
| Lambda 类型安全 | ❌ | ❌ | ❌ | ✅ | ✅ |
| 泛型类型保留 | ❌ | ❌ | ❌ | ❌ | ✅ |
| 元数据缓存 | ❌ | ❌ | ❌ | 编译时 | ✅ |
| 字段映射 | ❌ | ❌ | ✅ | ✅ | ✅ |
| Map 互转 | ❌ | ❌ | ✅ | ❌ | ✅ |
| 运行时动态 | ✅ | ✅ | ✅ | ❌ | ✅ |
| 链式 API | ❌ | ❌ | ❌ | ❌ | ✅ |

#### 类型转换系统

`Converters` 转换器注册表支持多层查找（精确匹配 → 继承链 → 工厂 → 类型转换器 → 委托），`TypeRef<T>` 保留泛型信息。

```java
// 注册自定义转换器
Converters.register(String.class, Integer.class, Integer::parseInt);

// 类型转换
Integer value = Converts.to("123", Integer.class);

// 泛型转换（保留泛型信息）
List<String> list = Converts.to(jsonArray, new TypeRef<List<String>>() {});
```

#### 其他工具

| 工具 | 说明 |
|------|------|
| `Reflects` | 基于 MethodHandle 的高性能反射 |
| `Fields` / `Methods` / `Types` | 字段、方法、类型工具（继承链查找、泛型解析） |
| `Hashes` / `AES` / `RSA` / `Base64s` | 加解密工具 |
| `Lists` / `Maps` | 集合工具（分区、转换、过滤） |
| `CacheMap` | 带过期时间的缓存 Map |
| `RefreshableCacheMap` | 可定时刷新的原子缓存 |
| `WriteBehindCacheMap` | Write-Behind 缓存（异步双写） |
| `Strings` / `Numbers` / `Dates` / `Times` | 字符串、数字、日期工具 |

详见 [quickstart-core/README.md](quickstart-core/README.md)

---

### quickstart-mybatis-flex — MyBatis-Flex 增强

对 MyBatis-Flex 进行功能增强，提供声明式连表方案、关系表操作抽象、通用查询 DSL。

#### @Join 声明式连表

在 VO 字段上标注 `@Join`，自动通过子查询 + JSON_ARRAYAGG 生成连表 SQL，支持一对一、一对多（直接/中间表）。

> **注意：** 依赖 MySQL 的 JSON 函数（JSON_ARRAYAGG、JSON_CONTAINS），目前仅支持 MySQL。

```java
public class AdminVo {
    private Long id;
    private String username;

    // 一对一：查询创建者
    @Join(selfKey = "creatorId", target = QkAdmin.class)
    private QkAdmin creator;

    // 一对多（直接）：角色 ID 列表 → 角色对象列表
    @Join(selfKey = "roleIds", target = QkRole.class, targetSelect = {"id", "name"})
    private List<QkRole> roleList;

    // 一对多（中间表）：通过 admin_role 关联表查角色
    @Join(through = QkAdminRole.class, throughSelfKey = "adminId",
          throughTargetKey = "roleId", target = QkRole.class,
          targetSelect = {"id", "name"})
    private List<QkRole> roles;
}

// Service 层
JoinVoQuery.of(QkAdmin.class, AdminVo.class).page(queryAo);
```

#### Relation — 关系表操作

对多对多关系表的统一抽象，支持 add（自动去重）、reset（差异对比智能同步）、clear、copy 等操作。

```java
// 定义关系（Lambda 类型安全）
Relation<AdminRole> relation = Relations.of(AdminRole::getAdminId, AdminRole::getRoleId);

// 正向操作（管理员 → 角色）
relation.add(adminId, List.of(roleId1, roleId2));  // 添加（自动去重）
relation.reset(adminId, newRoleIds);                // 智能同步（差异对比）
relation.clear(adminId);                            // 清空
relation.querySubTable(Role.class, adminId);       // 查询角色列表

// 反向操作（角色 → 管理员）
Relation<AdminRole> reverse = relation.reverse();
reverse.querySubTable(Admin.class, roleId);

// 树形自关联
TreeSelfRelation<Dept> tree = Relations.tree(Dept::getId, Dept::getParentId);
tree.children(deptId);
tree.parent(deptId);
tree.hasChildren(deptId);
```

#### 通用查询 DSL

提供 30+ 查询操作符，GET 和 POST 使用统一的查询语法。GET 请求支持扁平化 URL 参数，前端友好。

```java
// 查询链方式
Query.of(User.class)
    .eq("status", 1)
    .like("name", "admin")
    .orderBy("createTime", false)
    .list();

// 从 Map 构建（前端 JSON 直传）
Map<String, Object> conditions = Map.of(
    "status", Map.of("$eq", 1),
    "name", Map.of("$ct", "admin"),
    "age", Map.of("$bt", List.of(18, 60)),
    "$sort", List.of("name", "-age")
);
Query.of(User.class, conditions).list();

// VO 关联查询（使用 @Join 自动连表）
Query.vo(User.class, UserVo.class).page(queryAo);
```

**常用操作符：**

| 分类 | 操作符 | 示例 |
|------|--------|------|
| 比较 | `$eq` `$ne` `$gt` `$ge` `$lt` `$le` | `{"age": {"$ge": 18}}` |
| 集合 | `$in` | `{"status": {"$in": [1,2]}}` |
| 范围 | `$bt` | `{"age": {"$bt": [18,60]}}` |
| 字符串 | `$ct` `$sw` `$ew` `$regex` | `{"name": {"$ct": "admin"}}` |
| 日期 | `$year` `$month` `$day` 等 | `{"createTime[$year]": 2026}` |
| 逻辑 | `$and` `$or` `$not` | `{"$or": [{"age":18},{"age":20}]}` |
| 配置 | `$sort` `$limit` `$offset` `$f` | `{"$sort": ["name", "-age"]}` |

**GET 请求扁平化语法：**

| URL 参数 | 解析结果 |
|---------|---------|
| `?name=foo` | `{"name": "foo"}` |
| `?tags=a,b,c` | `{"tags": ["a", "b", "c"]}` |
| `?ids=[1,2,3]` | `{"ids": [1, 2, 3]}` |
| `?createTime[$year]=2026` | `{"createTime": {"$year": 2026}}` |
| `?roles[ids][$in]=[1,2]` | `{"roles": {"ids": {"$in": [1, 2]}}}` |

详见 [quickstart-mybatis-flex/README.md](quickstart-mybatis-flex/README.md)

---

### quickstart-web — Web 功能增强

提供统一响应、全局异常处理、参数解析、限流防重、HMAC 签名、数据加解密等 Web 开发常用功能。

#### 统一响应 Ret&lt;T&gt;

```java
return Ret.ok(data);
return Ret.ok(() -> userService.findAll()); // 延迟加载
return Ret.ok().code(10001).msg("操作成功").data(result);

Ret.badRequest("参数错误");         // 400
Ret.unauthorized("未认证");         // 401
Ret.notFound("资源不存在");         // 404
Ret.tooManyRequests("请求过于频繁"); // 429
Ret.error("系统异常");              // 500
```

#### 全局异常处理

异常链匹配（递归遍历 cause）+ 继承体系查找，而非仅匹配表面异常。支持注册自定义处理器。

```java
throw new BadRequestException("参数错误");     // 400
throw new UnauthorizedException("未认证");     // 401
throw new NotFoundException("不存在");         // 404
throw new BusinessException("业务异常");       // 可自定义状态码

// 注册自定义异常处理器
handler.registry(CustomException.class, ex -> Ret.error(ex.getMessage()));
```

#### 参数解析 & 限流 & 签名

```java
// @Json：GET 请求中接收 JSON 参数
@GetMapping("/user")
public Ret<List<User>> query(@Json UserQuery query) { ... }

// @Decrypt：自动解密请求参数
@PostMapping("/secure")
public Ret<String> secure(@Decrypt @RequestBody SecureData data) { ... }

// 限流 & 防重 & 签名
@RateLimit(count = 60, period = 1)   // 每秒 60 次
@NoRepeat                             // 防重复提交
@HMAC                                 // HMAC 签名验证
```

详见 [quickstart-web/README.md](quickstart-web/README.md)

---

### quickstart-validation — 数据校验增强

扩展 Jakarta Bean Validation，提供 10+ 自定义校验注解和 Verifiable 编程式校验。

```java
// 自定义注解
@Phone        // 手机号
@IdCard       // 身份证号
@EnumValue    // 枚举值
@DictValue    // 字典值
@DateRange    // 日期范围（支持字段级和类级）
@Identifier   // 标识符格式

// Verifiable 编程式校验
@Data
@CustomValid
public class UserCreateAo implements Verifiable {
    private String name;
    private Integer age;

    @Override
    public void validate(Rejects rejects) {
        rejects.when(this.age < 0, "年龄不能为负数");
        rejects.ifNull(this.name, "name", "用户名不能为空");
    }
}
```

---

### quickstart-log — 日志增强

```java
// 方法调用日志（自动记录入参、返回值、耗时）
@Log
public User getUser(Long id) { ... }

@Log(excludeParams = {"password"})  // 排除敏感参数
public void updateUser(User user) { ... }

// 操作日志（记录谁在什么时候做了什么）
@OperateLog(type = "CREATE", description = "创建用户")
public Ret<Void> createUser(@RequestBody UserCreateAo ao) { ... }

// 日志上下文（traceId 链路追踪）
LogContext.setTraceId("abc-123-def");
```

详见 [quickstart-log/README.md](quickstart-log/README.md)

---

## 功能一览

| 分类 | 模块 | 功能 |
|------|------|------|
| **核心** | [quickstart-core](quickstart-core/) | Bean 元数据框架、类型转换、反射工具、缓存 Map、加解密 |
| | [quickstart-domain](quickstart-domain/) | Ret、Page、Tree、QueryAo 等通用领域模型 |
| | [quickstart-spring](quickstart-spring/) | Spring 容器工具封装 |
| | [quickstart-spring-expression](quickstart-spring-expression/) | Spring 表达式增强 |
| **数据** | [quickstart-mybatis-flex](quickstart-mybatis-flex/) | @Join 声明式连表、Relation、Query DSL（30+ 操作符） |
| | [quickstart-redis](quickstart-redis/) | Redis 封装（分布式锁、Hash/Set/SortedSet/LinkedList） |
| **Web** | [quickstart-web](quickstart-web/) | 统一响应、异常处理、@Json、@Decrypt、@RateLimit、@HMAC |
| | [quickstart-validation](quickstart-validation/) | 10+ 自定义校验注解、Verifiable 编程式校验 |
| | [quickstart-log](quickstart-log/) | @Log 方法日志、@OperateLog 操作日志、LogContext |
| **JSON** | [quickstart-jackson](quickstart-jackson/) | @JsonArrayAsObject、@JsonDeduplicate、JPath |
| **工具** | [quickstart-easyexcel](quickstart-easyexcel/) | Excel 处理（支持 LocalDate/LocalDateTime） |
| | [quickstart-zxing](quickstart-zxing/) | 二维码/条形码生成 |
| | [quickstart-ql-express](quickstart-ql-express/) | 阿里规则引擎 QLExpress |
| | [quickstart-mustache](quickstart-mustache/) | Mustache 模板引擎 |
| | [quickstart-graalvm](quickstart-graalvm/) / [quickstart-graalvm-js](quickstart-graalvm-js/) | GraalVM 多语言 / JavaScript 引擎 |
| | [quickstart-javacv](quickstart-javacv/) | JavaCV 音视频处理 |
| | [quickstart-easy-captcha](quickstart-easy-captcha/) | 验证码生成 |
| | [quickstart-file-storage](quickstart-file-storage/) | 自定义文件存储 |
| | [quickstart-code-generator](quickstart-code-generator/) | 代码生成器（基于 Mustache） |
| | [quickstart-ddl-annotation](quickstart-ddl-annotation/) | DDL 注解支持 |
| **第三方** | [quickstart-alipay](quickstart-alipay/) | 支付宝 SDK 封装 |
| | [quickstart-aliyun-oss](quickstart-aliyun-oss/) | 阿里云 OSS 对象存储 |
| | [quickstart-ding-talk](quickstart-ding-talk/) | 钉钉开放平台集成 |
| | [quickstart-mqtt](quickstart-mqtt/) | MQTT 消息队列 |
| | [quickstart-bt](quickstart-bt/) | 宝塔面板 Java SDK |
| **Starter** | quickstart-web-spring-boot-starter | Web 功能自动配置 |
| | quickstart-mybatis-flex-spring-boot-starter | MyBatis-Flex 自动配置 |
| | quickstart-redis-spring-boot-starter | Redis 自动配置 |
| | quickstart-validation-spring-boot-starter | 数据校验自动配置 |
| | quickstart-log-spring-boot-starter | 日志增强自动配置 |
| | quickstart-mqtt-spring-boot-starter | MQTT 自动配置 |

---

## 模块详解

<details>
<summary><b>quickstart-core — 核心工具</b></summary>

### Bean 元数据框架

双层架构：元数据层（`BeanAccessor`/`PropAccessor`）+ 实例层（`Bean`/`Prop`），元数据级缓存避免重复反射。

```java
// Lambda 方式
Bean<User> bean = Bean.of(user);
bean.set(User::getName, "张三");
String name = bean.get(User::getName);

// 对象复制
UserDTO dto = Beans.copy(source, UserDTO.class);

// 带选项复制
Options options = Options.defaults()
    .ignoreProperties("id")
    .fieldMapping("userName", "name");
Beans.copy(source, target, options);

// Map 与 Bean 互转
Map<String, Object> map = Beans.asMap(user);
User user = Beans.from(map, User.class);

// 批量复制
List<UserDTO> dtos = Beans.copy(userList, UserDTO.class);
```

### 类型转换系统

`Converters` 转换器注册表支持多层查找（精确匹配 → 继承链 → 工厂 → 类型转换器 → 委托）。`TypeRef<T>` 保留泛型信息。

```java
// 注册自定义转换器
Converters.register(String.class, Integer.class, Integer::parseInt);

// 类型转换
Integer value = Converts.to("123", Integer.class);

// 泛型转换
List<String> list = Converts.to(jsonArray, new TypeRef<List<String>>() {});
```

### 其他工具

| 工具 | 说明 |
|------|------|
| `Reflects` | 基于 MethodHandle 的高性能反射 |
| `Fields` / `Methods` / `Types` | 字段、方法、类型工具 |
| `Hashes` / `AES` / `RSA` / `Base64s` | 加解密工具 |
| `Lists` / `Maps` | 集合工具（分区、转换、过滤） |
| `CacheMap` | 带过期时间的缓存 Map |
| `RefreshableCacheMap` | 可定时刷新的原子缓存 |
| `WriteBehindCacheMap` | Write-Behind 缓存（异步双写） |
| `Strings` / `Numbers` / `Dates` / `Times` | 字符串、数字、日期工具 |

详见 [quickstart-core/README.md](quickstart-core/README.md)

</details>

<details>
<summary><b>quickstart-mybatis-flex — MyBatis-Flex 增强</b></summary>

### @Join 声明式连表

在 VO 字段上标注 `@Join`，自动通过子查询 + JSON_ARRAYAGG 生成连表 SQL。

> **注意：** 仅支持 MySQL（依赖 JSON_ARRAYAGG、JSON_CONTAINS 函数）。

**支持的连表模式：**
- 一对一：`selfKey → target.id`
- 一对多（直接）：`selfKey JSON_CONTAINS target.id`（如 JSON 数组字段）
- 一对多（中间表）：通过 `through` 中间表关联

```java
public class AdminVo {
    private Long id;

    // 一对一
    @Join(selfKey = "creatorId", target = QkAdmin.class)
    private QkAdmin creator;

    // 一对多（直接）：角色 ID 列表 → 角色对象列表
    @Join(selfKey = "roleIds", target = QkRole.class, targetSelect = {"id", "name"})
    private List<QkRole> roleList;

    // 一对多（中间表）
    @Join(through = QkAdminRole.class, throughSelfKey = "adminId",
          throughTargetKey = "roleId", target = QkRole.class)
    private List<QkRole> roles;
}

JoinVoQuery.of(QkAdmin.class, AdminVo.class).page(queryAo);
```

### Relation — 关系表操作

```java
Relation<AdminRole> relation = Relations.of(AdminRole::getAdminId, AdminRole::getRoleId);

relation.add(adminId, List.of(roleId1, roleId2));  // 添加（自动去重）
relation.reset(adminId, newRoleIds);                // 智能同步（差异对比）
relation.clear(adminId);                            // 清空
relation.delete(adminId, List.of(roleId1));         // 删除指定
relation.querySubTable(Role.class, adminId);       // 查询子表
relation.copy(srcAdminId, tgtAdminId);             // 复制关系

// 反向
Relation<AdminRole> reverse = relation.reverse();
```

### TreeSelfRelation — 树形自关联

```java
TreeSelfRelation<Dept> tree = Relations.tree(Dept::getId, Dept::getParentId);

tree.parent(deptId);            // 查询父节点
tree.children(deptId);          // 查询子节点列表
tree.childrenIdsAsLong(deptId); // 子节点 ID 列表
tree.hasChildren(deptId);       // 是否有子节点
tree.isRoot(deptId);            // 是否为根节点
```

### 通用查询 DSL

详见上方 [通用查询 DSL](#通用查询-dsl) 部分。

详见 [quickstart-mybatis-flex/README.md](quickstart-mybatis-flex/README.md)

</details>

<details>
<summary><b>quickstart-web — Web 功能增强</b></summary>

### 统一响应 Ret&lt;T&gt;

```java
return Ret.ok(data);
return Ret.ok(() -> userService.findAll()); // 延迟加载
return Ret.ok().code(10001).msg("操作成功").data(result);

Ret.badRequest("参数错误");         // 400
Ret.unauthorized("未认证");         // 401
Ret.forbidden("无权限");            // 403
Ret.notFound("资源不存在");         // 404
Ret.tooManyRequests("请求过于频繁"); // 429
Ret.error("系统异常");              // 500
```

### 全局异常处理

- **异常链匹配**：递归遍历异常链（cause 优先匹配），而非仅匹配表面异常
- **继承体系查找**：在异常继承链中查找处理器
- **可注册自定义处理器**

```java
throw new BadRequestException("参数错误");     // 400
throw new UnauthorizedException("未认证");     // 401
throw new NotFoundException("不存在");         // 404
throw new BusinessException("业务异常");       // 自定义状态码

// 注册自定义异常处理器
handler.registry(CustomException.class, ex -> Ret.error(ex.getMessage()));
```

### 参数解析

```java
// @Json：GET 请求中接收 JSON 参数
@GetMapping("/user")
public Ret<List<User>> query(@Json UserQuery query) { ... }

// @Decrypt：自动解密请求参数
@PostMapping("/secure")
public Ret<String> secure(@Decrypt @RequestBody SecureData data) { ... }

// @EnumValue：枚举值映射（前端传 1 → Status.ACTIVE）
// 自动日期转换：Year、YearMonth、LocalDate、LocalDateTime
```

### 限流 & 防重 & 签名

```java
@RateLimit(count = 60, period = 1)   // 每秒 60 次
@NoRepeat                             // 防重复提交
@HMAC                                 // HMAC 签名验证
```

### Web 工具

```java
WebUtils.getIpAddress();           // 客户端真实 IP（支持代理）
WebUtils.getBasePath();            // 基础路径
WebUtils.getReq();                 // 当前请求
WebUtils.setFileHeaderToResp("report.xlsx"); // 文件下载响应头
```

</details>

<details>
<summary><b>quickstart-validation — 数据校验增强</b></summary>

### 自定义校验注解

| 注解 | 说明 |
|------|------|
| `@Identifier` | 标识符格式（中文/字母/数字/下划线/连字符） |
| `@Phone` | 手机号格式 |
| `@IdCard` | 身份证号格式 |
| `@EnumValue` | 值必须在指定枚举中 |
| `@DictValue` | 值在字典中 |
| `@DateRange` | 日期范围（支持字段级和类级） |
| `@CustomValid` | 触发 Verifiable 接口校验 |
| `@NoWhitespace` | 不允许空白字符 |
| `@NoNullElements` | 集合中不允许 null 元素 |
| `@Words` / `@ProvidedWords` | 值在静态/动态词库中 |
| `@JavaIdentifier` | Java 标识符格式 |

### @DateRange 用法

```java
// 字段级：日期在范围内
@DateRange(min = "2024-01-01", max = "2024-12-31")
private LocalDate eventDate;

// 类级：start 字段早于 end 字段
@DateRange(start = "startDate", end = "endDate")
public class EventDto {
    private LocalDate startDate;
    private LocalDate endDate;
}
```

### Verifiable — 编程式校验

```java
@Data
@CustomValid
public class UserCreateAo implements Verifiable {
    private String name;
    private Integer age;
    private String password;
    private String confirmPassword;

    @Override
    public void validate(Rejects rejects) {
        rejects.when(this.age < 0, "年龄不能为负数");
        rejects.when(!this.password.equals(this.confirmPassword),
            "confirmPassword", "两次密码不一致");
        rejects.ifNull(this.name, "name", "用户名不能为空");
    }
}
```

</details>

<details>
<summary><b>quickstart-domain — 通用领域模型</b></summary>

```java
// 分页请求
PageAo pageAo = PageAo.of(1, 10);
PageAo pageAo = PageAo.maximum();     // 查询全部

// 分页响应
PageRecordsVo<User> result = PageRecordsVo.of(page, users);
// { "page": { "current": 1, "size": 10, "total": 100 }, "records": [...] }

// 通用接口
Id<T>          // 标识实体具有 ID 属性
Coded          // 错误码体系
TreeNode<T,ID> // 树形节点接口
QueryAo        // 通用查询接口
```

</details>

<details>
<summary><b>quickstart-log — 日志增强</b></summary>

```java
// 方法调用日志
@Log
public User getUser(Long id) { ... }

@Log(level = LogLevel.DEBUG)
public List<User> listUsers() { ... }

@Log(excludeParams = {"password"})  // 排除敏感参数
public void updateUser(User user) { ... }

// 操作日志
@OperateLog(type = "CREATE", description = "创建用户")
public Ret<Void> createUser(@RequestBody UserCreateAo ao) { ... }

// 日志上下文
LogContext.setTraceId("abc-123-def");
String traceId = LogContext.getTraceId();

// 自定义操作日志处理器
@Component
public class MyOperateLogHandler implements OperateLogHandler {
    @Override
    public void handle(OperateLogRecord record) {
        logRepository.save(record);
    }
}
```

详见 [quickstart-log/README.md](quickstart-log/README.md)

</details>

<details>
<summary><b>quickstart-bt — 宝塔面板 SDK</b></summary>

提供宝塔面板 API 的 Java SDK，支持文件管理、Java 项目部署等。

```java
Bt bt = new Bt("https://panel.example.com", "api_key");

// 文件管理
bt.files().uploadFile("/www/wwwroot/app", localFile);

// Java 项目管理
bt.modJavaProject().restartProject("my-app");

// 一键重新部署（上传 + 重启）
bt.redeploy("my-app", new File("target/my-app.jar"));
```

</details>

<details>
<summary><b>第三方集成模块</b></summary>

| 模块 | 说明 |
|------|------|
| [quickstart-alipay](quickstart-alipay/) | 支付宝 SDK 封装（支付、退款、查询） |
| [quickstart-aliyun-oss](quickstart-aliyun-oss/) | 阿里云 OSS 对象存储（上传、下载、签名 URL） |
| [quickstart-ding-talk](quickstart-ding-talk/) | 钉钉开放平台集成（通讯录、消息、审批、宜搭） |
| [quickstart-mqtt](quickstart-mqtt/) | MQTT 消息队列（发布、订阅、连接管理） |

</details>

<details>
<summary><b>其他工具模块</b></summary>

| 模块 | 说明 |
|------|------|
| [quickstart-jackson](quickstart-jackson/) | Jackson JSON 增强（`@JsonArrayAsObject`、`@JsonDeduplicate`、`JPath`） |
| [quickstart-easyexcel](quickstart-easyexcel/) | Excel 处理（支持 LocalDate/LocalDateTime 扩展） |
| [quickstart-zxing](quickstart-zxing/) | 二维码/条形码生成 |
| [quickstart-ql-express](quickstart-ql-express/) | 阿里规则引擎 QLExpress 封装 |
| [quickstart-mustache](quickstart-mustache/) | Mustache 模板引擎 |
| [quickstart-graalvm](quickstart-graalvm/) | GraalVM 多语言支持 |
| [quickstart-graalvm-js](quickstart-graalvm-js/) | GraalVM JavaScript 引擎 |
| [quickstart-javacv](quickstart-javacv/) | JavaCV 音视频处理 |
| [quickstart-easy-captcha](quickstart-easy-captcha/) | 验证码生成 |
| [quickstart-file-storage](quickstart-file-storage/) | 自定义文件存储系统 |
| [quickstart-code-generator](quickstart-code-generator/) | 代码生成器（基于 Mustache 模板） |
| [quickstart-ddl-annotation](quickstart-ddl-annotation/) | DDL 注解支持 |

</details>

---

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 5.7+

### 1. 克隆项目

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

### 2. 构建项目

```bash
mvn clean install
```

### 3. 引入依赖

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

<dependency>
    <groupId>com.gitee.feizns</groupId>
    <artifactId>quickstart-mybatis-flex-spring-boot-starter</artifactId>
    <version>3.0.0-RELEASE</version>
</dependency>
```

### 4. 配置文件

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

### 5. 使用示例

```java
// 实体类
@Data
@Table("user")
public class User {
    @Id(keyType = KeyType.Auto)
    private Long id;
    private String username;
    private String email;
    private LocalDateTime createTime;
}

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

// Controller
@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserMapper userMapper;

    @GetMapping
    public Ret<PageRecordsVo<User>> page(PageAo pageAo, QueryAo queryAo) {
        SmartQueryChain<User> chain = Query.of(User.class, queryAo);
        List<User> users = chain.page(pageAo).list();
        return Ret.ok(PageRecordsVo.of(pageAo, users));
    }

    // GET — QueryParamsAo 自动从 URL 参数构建
    @GetMapping("/list")
    public Ret<PageRecordsVo<User>> list(QueryParamsAo query) {
        return Ret.ok(Query.vo(User.class, UserVo.class).page(query));
    }

    // POST — 请求体直接反序列化为 QueryBodyAo
    @PostMapping("/list")
    public Ret<PageRecordsVo<User>> listPost(@RequestBody QueryBodyAo query) {
        return Ret.ok(Query.vo(User.class, UserVo.class).page(query));
    }
}
```

---

## 许可证

Apache License 2.0

## 联系方式

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