carm/EasySQL
carm/EasySQL
1
Fork 0
mirror of https://github.com/CarmJos/EasySQL.git synced 2024-09-19 21:35:47 +00:00
Code Issues Releases Activity

完善帮助

Browse Source
This commit is contained in:
Carm Jos 2022-02-10 20:31:26 +08:00
parent 5444015b8b
commit 22a8172490
3 changed files with 225 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
.documentation/README.md
View File

@ -1,3 +1,8 @@
# 欢迎使用 EasySQL ！
这个项目刚刚创建，详细的Javadoc与开发指南还在补充，请给我一点时间~
这个项目刚刚创建，详细的Javadoc与开发指南还在补充，请给我一点时间~
## 目录
- [Bob的EasySQL之旅(HikariCP)](USAGE-HIKARI.md) `@Ghost-Chu`

173
.documentation/USAGE-HIKARI.md
View File

@ -1,36 +1,46 @@
# EasySQL - HikariPool 使用指南
> 本文档由 GitHub 用户 @Ghost-chu 创建。
> 本文撰写于 2022/02/09，适配 EasySQL 版本 `v0.3.6`。
> 本文基于 `EasySQL-HikariPool` 版本编写。
本文档由 Github 用户 @Ghost-chu 创建。
本文撰写于 2022/02/09，适配 EasySQL 版本 `v0.3.6`。
本文基于 `EasySQL-HikariPool` 版本编写。
# EasySQL - HikariPool 使用指南
## 和 EasySQL 说你好：创建你的第一个 SQLManager
```java
public class HiEasySQL {
public static void createYourSQLManager() {
HikariConfig hikari = YOUR_HIKARI_CONFIG;
SQLManager sqlManager = EasySQL.createManager(hikari);
try {
if(!sqlManager.getConnection().isValid(5)){
logger.warning("Connection invalid!")
if (!sqlManager.getConnection().isValid(5)) {
logger.warning("Connection invalid!");
}
}catch (SQLException e){
logger.warning("Failed to connect to database!", e)
} catch (SQLException e) {
logger.warning("Failed to connect to database!", e);
}
}
}
```
至此，你已经创建了一个 SQLManager 对象。与 EasySQL 的故事由此开始。
至此，你已经创建了一个 SQLManager 对象，与 EasySQL 的故事由此开始。
## SQL起步： 查询 (Query)
EasySQL 官方推荐使用异步查询以避免产生性能影响和手动关闭连接的麻烦。本节我们将展示使用 "异步查询" 的示例代码，并讲解如何使用 "查询处理器" 和 "错误处理器"。
EasySQL 可以使用异步查询以避免产生性能影响和手动关闭连接的麻烦。本节我们将展示使用 "异步查询" 的示例代码，并讲解如何使用 "查询处理器" 和 "错误处理器"。
```java
public class HiEasySQL {
public static void trySomeQuery(SQLManager sqlManager) {
sqlManager.createQuery() // 创建一个查询
.inTable("table_name") // 指定表名
.selectColumns("name", "sex", "age") // 选择 "name", "sex", "age" 三个列
.addCondition("name","Bob") // 限定条件，"name" 必须是 Bob
.build() // 构建查询体
.executeAsync((query)-> { /*处理查询结果-SQLQuery*/ }, ((exception, sqlAction) -> { /*SQL异常处理-SQLExceptionHandler*/ })); // 异步查询
.addCondition("name", "Bob") // 限定条件，"name" 必须是 Bob
.build()/*构建查询体*/.executeAsync(
(query) -> { /*处理查询结果-SQLQuery*/ },
((exception, sqlAction) -> { /*SQL异常处理-SQLExceptionHandler*/ })
); // 异步查询~~~~
}
}
```
### SQLQuery
@ -52,8 +62,7 @@ SQLQuery 是 EasySQL 执行查询类请求统一返回的对象，包括如下
### SQLExceptionHandler
当出现 SQLException 异常时，如果你在查询中指定了一个 SQLExceptionHandler，则会被调用。
SQLExceptionHandler 接受两个参数：
当出现 SQLException 异常时，如果你在查询中指定了一个 SQLExceptionHandler，则会被调用。 SQLExceptionHandler 接受两个参数：
* SQLException - 发生的 SQL 异常
* SQLAction - 执行的 SQL 操作
@ -73,10 +82,14 @@ SQLAction 包含 EasySQL 在处理 SQL 请求时所使用到的信息：
除了 SELECT 查询操作以外，EasySQL 也当然支持 INSERT 插入操作。
```java
public class HiEasySQL {
public static void doSomeInsert(SQLManager sqlManager) {
sqlManager.createInsert("table_name")
.setColumnNames("name", "sex", "age")
.setParams("Alex","female",16)
.setParams("Alex", "female", 16)
.executeAsync();
}
}
```
EasySQL 使用 PreparedStatement 来填充参数，无需担心 SQL 注入问题。
@ -92,11 +105,15 @@ EasySQL 使用 PreparedStatement 来填充参数，无需担心 SQL 注入问题
Bob 是个喜欢改名的人，于是他今天给自己起了个新名字叫 Steve。因此我们需要更新数据库中已经存在的数据：
```java
sqlManager.createUpdate("table_name")
.addCondition("name","Bob")
.setColumnValues("name","Steve")
.build()
.executeAsync();
public class HiEasySQL {
public static void updateSomething(SQLManager sqlManager) {
sqlManager.createUpdate("table_name")
.addCondition("name", "Bob")
.setColumnValues("name", "Steve")
.build().executeAsync();
}
}
```
至此，Bob 就改名为 Steve 啦！
@ -107,12 +124,16 @@ Bob 是个喜欢改名的人，于是他今天给自己起了个新名字叫 Ste
不过，Steve 说它不记得这套房子是多久之前买的了，不过肯定是 10 年之前。
```java
public class HiEasySQL {
public static void sayGoodBye(SQLManager sqlManager) {
Date date = new Date(); // 使用当前日期时间戳创建一个 Date
date.setYear(date.getYear() - 10); // 把时间滑动到 10 年之前
sqlManager.createDelete("steve_house") // 进行删除
.addTimeCondition("purchase_date", new Date(0), date) // 选择从1970年1月1日0点一直到10年前的所有数据
.build()
.executeAsync(); //执行
}
}
```
现在 Steve 真的没有他的这套房了。
@ -123,10 +144,14 @@ Steve 买了一盒牛奶，他要在他的购物清单中标记牛奶已经买
不过，Steve 忘记了自己有没有将牛奶加入过购物清单。但是如果暴力 INSERT 肯定会出错，但是又觉得写个 INSERT OR UPDATE 太麻烦了，于是这件棘手的事情又丢到了我们的头上来。
```java
public class HiEasySQL {
public static void putAnyway(SQLManager sqlManager) {
sqlManager.createReplace("steve_list")
.setColumnNames("item","purchased")
.setParams("milk",true)
.setColumnNames("item", "purchased")
.setParams("milk", true)
.executeAsync();
}
}
```
生活总有简单的方法不是吗？
@ -135,18 +160,21 @@ Steve 买了一盒牛奶，他要在他的购物清单中标记牛奶已经买
Steve 的公司老板开发了一个 IM 软件，但是 Steve 公司运维是土豆，不会搞SQL。
最要命的是，Steve 的公司老板还不让你碰生产环境，于是你便不能指望土豆会去帮你完成建表的任务了。
除此之外，由于 IM 软件上的网友特能叭叭，你还需要稍微考虑下性能问题。不然你可能会被送去西伯利亚。
除此之外，由于 IM 软件上的网友特能叭叭，你还需要稍微考虑下性能问题。不然你可能会被送去西伯利亚。
```java
public class HiEasySQL {
public static void newTablePlease(SQLManager sqlManager) {
sqlManager.createTable("steve_im_history")
.addColumn("id", "BIGINT NOT NULL", "记录ID")
.addColumn("sender", "VARCHAR NOT NULL", "网友UUID")
.addColumn("message","TEXT NULL","网友发言")
.addColumn("message", "TEXT NULL", "网友发言")
.addAutoIncrementColumn("id") //设置 id 列自增
.setIndex(IndexType.PRIMARY_KEY,null,"id","sender") //配置主键
.setIndex(IndexType.INDEX,"sender_message_index","sender","message") //配置索引
.build()
.executeAsync();
.setIndex(IndexType.PRIMARY_KEY, null, "id", "sender") //配置主键
.setIndex(IndexType.INDEX, "sender_message_index", "sender", "message") //配置索引
.build().executeAsync();
}
}
```
## 上司的任务2：改表
@ -155,12 +183,17 @@ Steve 的公司老板和 Steve 提出了一个需求，迫不得已，Steve 要
然而此时表内已经存储了大量数据，不能删表再建，Steve 要想个办法对表做出相应的修改。
```java
public class HiEasySQL {
public static void newTablePlease(SQLManager sqlManager) {
sqlManager.alterTable("steve_im_history")
.addColumn("ipAddress","VARCHAR(255)")
.addColumn("ipAddress", "VARCHAR(255)")
.executeAsync();
sqlManager.alterTable("steve_im_history")
.modifyColumn("message","BIGTEXT")
.modifyColumn("message", "LONGTEXT")
.executeAsync();
}
}
```
多亏了我们的大力帮助。现在，Steve 被送去了南极担任公司的重要工作了。
@ -172,51 +205,83 @@ Steve 到达南极之后，南极的员工把2FA密钥塞给Steve便骑着海豚
然而，员工跑路的时候删库格盘了，现在 Steve 要自己想办法解决这个烂摊子了。
```java
public class HiEasySQL {
public static void iDontLikeHere(SQLManager sqlManager) {
sqlManager.createInsertBatch("polarbear")
.setColumnNames("name","temp","hunger")
.setColumnNames("name", "temp", "hunger")
.addParamsBatch("Karl", -17, 100)
.addParamsBatch("Lucy",-3,80)
.addParamsBatch("Lily",-10,70)
.executeAsync((list) -> {/*RowIDs*/} );
.addParamsBatch("Lucy", -3, 80)
.addParamsBatch("Lily", -10, 70)
.setReturnGeneratedKey(true)// 设定在后续返回自增主键
.executeAsync((list) -> {/*新增行的自增主键*/});
}
}
```
## 北极熊的熊猫之旅！？：复杂查询
Steve 翻看着跑路员工留下的为数不多的资料，发现公司在南极培育北极熊是为了让它们变成熊猫！
只要满足 “温度 < -100C, 饱食度 > 70, 名字中带有 PANDAKING 关键字并以符合条件的北极熊门的名字倒序排序后的第一条” 的北极熊就有希望变成熊猫！
只要满足 “温度 < -100C, 饱食度 > 70, 名字中带有 `PANDAKING` 关键字并以符合条件的北极熊门的名字倒序排序后的第一条” 的北极熊就有希望变成熊猫！
现在 Steve 已经迫不及待的看看是哪只熊猫如此幸运了！
```java
public class HiEasySQL {
public static void noBearsPlease(SQLManager sqlManager) {
sqlManager.createQuery()
.inTable("panda_king_proj")
.addCondition("temp" "<", -100)
.addCondition("hunger" ">", 70)
.addCondition("name","LIKE","PANDAKING")
.orderBy("name",false)
.addCondition("temp", "<", -100)
.addCondition("hunger", ">", 70)
.addCondition("name", "LIKE", "PANDAKING")
.orderBy("name", false)
.setLimit(1)
.build()
.executeAsync((result) -> {
result.getResultSet().next();
System.out.println(result.getResultSet().getString("name"));
.build().executeAsync((result) -> {
if (result.getResultSet().next()) {
System.out.println(result.getResultSet().getString("name"));
}
});
}
}
```
## 同步请求
经历人生坎坷后的 Steve 回到了自己的家：因为没能培育出熊猫来，他的老板 Async 炒了他，女友 Lambda 甩了他，连朋友 Handler 都放 Steve 鸽子，于是现在他很讨厌任何带有这两个名字的东西。
经历人生坎坷后的 Steve 回到了自己的家：因为没能培育出熊猫来，他的老板 Async 炒了他，女友 Lambda 甩了他，连朋友 Handler 都放 Steve 鸽子，于是现在他很讨厌任何带有这两个名字的东西。
```java
try(SQLQuery query = sqlManager.createQuery()
.inTable("the_end")
.addCondition("thanks_read","this_stupid_guide")
.build()
.execute()) {
ResultSet set = query.getResultSet(); // SQLQuery 关闭时，ResultSet 会一同关闭
set.next();
set.getString("see_you_next_time");
}catch (Exception exception){
public class HiEasySQL {
public static void syncLover(SQLManager sqlManager) {
try (SQLQuery query = sqlManager.createQuery().inTable("the_end")
.addCondition("thanks_read", "this_stupid_guide")
.build().execute()) {
ResultSet set = query.getResultSet(); // SQLQuery 关闭时，ResultSet 会一同关闭
if (set.next()) {
set.getString("see_you_next_time");
}
} catch (Exception exception) {
exception.printStackTrace();
}
}
}
```
当然，有时候 Steve 也会选择更优雅一点的方式。
```java
import org.jetbrains.annotations.Nullable;
import java.sql.SQLException;
public class HiEasySQL {
// 调用此方法，直接返回结果，再在调用处统一处理错误
public static @Nullable String eleganceNeverGone(SQLManager sqlManager) throws SQLException {
return sqlManager.createQuery().inTable("the_end")
.addCondition("thanks_read", "this_stupid_guide")
.build().executeFunction(query -> {
if (!query.getResultSet().next()) return null;
else return query.getResultSet().getString("see_you_next_time");
});
}
}
```
Steve 终究能找到继续生活下去的办法 :)

200
example/easysql-demo/src/main/java/EasySQLDemo.java
View File

@ -15,119 +15,119 @@ import java.util.UUID;
@SuppressWarnings("all")
public class EasySQLDemo {
public void createTable(SQLManager sqlManager) {
// 同步创建表
sqlManager.createTable("users")
public void createTable(SQLManager sqlManager) {
// 同步创建表
sqlManager.createTable("users")
// .addColumn("id", "INT(11) AUTO_INCREMENT NOT NULL PRIMARY KEY")
.addAutoIncrementColumn("id", NumberType.INT, true, true)
.addColumn("uuid", "VARCHAR(32) NOT NULL UNIQUE KEY")
.addColumn("username", "VARCHAR(16) NOT NULL")
.addColumn("age", "TINYINT NOT NULL DEFAULT 1")
.addColumn("email", "VARCHAR(32)")
.addColumn("phone", "VARCHAR(16)")
.addColumn("registerTime", "DATETIME NOT NULL")
.addAutoIncrementColumn("id", NumberType.INT, true, true)
.addColumn("uuid", "VARCHAR(32) NOT NULL UNIQUE KEY")
.addColumn("username", "VARCHAR(16) NOT NULL")
.addColumn("age", "TINYINT NOT NULL DEFAULT 1")
.addColumn("email", "VARCHAR(32)")
.addColumn("phone", "VARCHAR(16)")
.addColumn("registerTime", "DATETIME NOT NULL")
// .addColumn("INDEX `phone`") // 原始方法添加索引
.setIndex("username", IndexType.UNIQUE_KEY) // 添加唯一索引
.setIndex(IndexType.INDEX, "contact", "email", "phone") //添加联合索引 (示例)
.build().execute(null /* 不处理错误 */);
.setIndex("username", IndexType.UNIQUE_KEY) // 添加唯一索引
.setIndex(IndexType.INDEX, "contact", "email", "phone") //添加联合索引 (示例)
.build().execute(null /* 不处理错误 */);
sqlManager.createTable("user_ipaddr")
.addAutoIncrementColumn("id", NumberType.INT, true, true)
.addColumn("uuid", "VARCHAR(32) NOT NULL")
.addColumn("ip", "VARCHAR(16)")
.addColumn("time", "DATETIME NOT NULL")
.addForeignKey("uuid", null,
"users", "uuid",
ForeignKeyRule.CASCADE, ForeignKeyRule.CASCADE
)
.build().execute(null /* 不处理错误 */);
}
sqlManager.createTable("user_ipaddr")
.addAutoIncrementColumn("id", NumberType.INT, true, true)
.addColumn("uuid", "VARCHAR(32) NOT NULL")
.addColumn("ip", "VARCHAR(16)")
.addColumn("time", "DATETIME NOT NULL")
.addForeignKey("uuid", null,
"users", "uuid",
ForeignKeyRule.CASCADE, ForeignKeyRule.CASCADE
)
.build().execute(null /* 不处理错误 */);
}
public void alertTable(SQLManager sqlManager) {
// 同步更新表
sqlManager.alterTable("users")
.modifyColumn("age", "TINYINT NOT NULL DEFAULT 0")
.execute(null /* 不处理错误 */);
}
public void alertTable(SQLManager sqlManager) {
// 同步更新表
sqlManager.alterTable("users")
.modifyColumn("age", "TINYINT NOT NULL DEFAULT 0")
.execute(null /* 不处理错误 */);
}
public void sqlQuery(SQLManager sqlManager) {
// 同步SQL查询
try (SQLQuery query = sqlManager.createQuery()
.inTable("users") // 在users表中查询
.selectColumns("id", "name") // 选中 id 与 name列
.addCondition("age", ">", 18) // 限定 age 要大于5
.addCondition("email", null) // 限定查询 email 字段为空
.addNotNullCondition("phone") // 限定 phone 字段不为空
.addTimeCondition("registerTime", // 时间字段
System.currentTimeMillis() - 100000, //限制开始时间
-1//不限制结束时间
).build().execute()) {
ResultSet resultSet = query.getResultSet();
//do something
public void sqlQuery(SQLManager sqlManager) {
// 同步SQL查询
try (SQLQuery query = sqlManager.createQuery()
.inTable("users") // 在users表中查询
.selectColumns("id", "name") // 选中 id 与 name列
.addCondition("age", ">", 18) // 限定 age 要大于5
.addCondition("email", null) // 限定查询 email 字段为空
.addNotNullCondition("phone") // 限定 phone 字段不为空
.addTimeCondition("registerTime", // 时间字段
System.currentTimeMillis() - 100000, //限制开始时间
-1//不限制结束时间
).build().execute()) {
ResultSet resultSet = query.getResultSet();
//do something
} catch (SQLException exception) {
exception.printStackTrace();
}
} catch (SQLException exception) {
exception.printStackTrace();
}
UUID userUUID = sqlManager.createQuery()
.inTable("users") // 在users表中查询
.selectColumns("uuid")
.addCondition("id", 5) // 限定 id 为 5
.setLimit(1) // 只取出一个数据
.build().execute(query -> {
//可以直接进行数据处理
ResultSet result = query.getResultSet();
return result.next() ? UUIDUtil.toUUID(result.getString("uuid")) : null;
}, (exception, action) -> {
// 处理异常，不想处理直接填null
});
UUID userUUID = sqlManager.createQuery()
.inTable("users") // 在users表中查询
.selectColumns("uuid")
.addCondition("id", 5) // 限定 id 为 5
.setLimit(1) // 只取出一个数据
.build().execute(query -> {
//可以直接进行数据处理
ResultSet result = query.getResultSet();
return result.next() ? UUIDUtil.toUUID(result.getString("uuid")) : null;
}, (exception, action) -> {
// 处理异常，不想处理直接填null
});
}
}
public void sqlQueryAsync(SQLManager sqlManager) {
// 异步SQL查询
sqlManager.createQuery()
.inTable("users") // 在users表中查询
.addCondition("id", 5) // 限定 id 为 5
.setLimit(1) // 只取出一个数据
.build().executeAsync(success -> {
ResultSet resultSet = success.getResultSet();
if (resultSet != null && resultSet.next()) {
String username = resultSet.getString("username");
}
}, (exception, action) -> {
//do something
long createTIme = action.getCreateTime();
String shortID = action.getShortID();
String sqlContent = action.getSQLContent();
});
}
public void sqlQueryAsync(SQLManager sqlManager) {
// 异步SQL查询
sqlManager.createQuery()
.inTable("users") // 在users表中查询
.addCondition("id", 5) // 限定 id 为 5
.setLimit(1) // 只取出一个数据
.build().executeAsync(success -> {
ResultSet resultSet = success.getResultSet();
if (resultSet != null && resultSet.next()) {
String username = resultSet.getString("username");
}
}, (exception, action) -> {
//do something
long createTIme = action.getCreateTime();
String shortID = action.getShortID();
String sqlContent = action.getSQLContent();
});
}
public void sqlInsert(SQLManager sqlManager) {
// 同步SQL插入 （不使用try-catch的情况下，返回的数值可能为空。）
Integer id = sqlManager.createInsert("users")
.setColumnNames("username", "phone", "email", "registerTime")
.setParams("CarmJos", "18888888888", "carm@carm.cc", TimeDateUtils.getCurrentTime())
.setKeyIndex(1) // 设定自增主键的index，将会在后续返回自增主键
.execute((exception, action) -> {
// 处理异常
System.out.println("#" + action.getShortID() + " -> " + action.getSQLContent());
exception.printStackTrace();
});
public void sqlInsert(SQLManager sqlManager) {
// 同步SQL插入 （不使用try-catch的情况下，返回的数值可能为空。）
Integer id = sqlManager.createInsert("users")
.setColumnNames("username", "phone", "email", "registerTime")
.setParams("CarmJos", "18888888888", "carm@carm.cc", TimeDateUtils.getCurrentTime())
.setReturnGeneratedKey(true)// 设定在后续返回自增主键
.execute((exception, action) -> {
// 处理异常
System.out.println("#" + action.getShortID() + " -> " + action.getSQLContent());
exception.printStackTrace();
});
try {
Integer userID = sqlManager.createInsert("users")
.setColumnNames("username", "phone", "email", "registerTime")
.setParams("CarmJos", "18888888888", "carm@carm.cc", TimeDateUtils.getCurrentTime())
.setKeyIndex(1) // 设定自增主键的index，将会在后续返回自增主键
.execute();
try {
Integer userID = sqlManager.createInsert("users")
.setColumnNames("username", "phone", "email", "registerTime")
.setParams("CarmJos", "18888888888", "carm@carm.cc", TimeDateUtils.getCurrentTime())
.setKeyIndex(1) // 设定自增主键的index，将会在后续返回自增主键
.execute();
System.out.println("新用户的ID为 " + userID);
System.out.println("新用户的ID为 " + userID);
} catch (SQLException exception) {
exception.printStackTrace();
}
}
} catch (SQLException exception) {
exception.printStackTrace();
}
}
}