修改Java流式SQL方面的文档说明为1.3.0的内容

lyg888 · Apr 30, 2018 · 2482ea7 · 2482ea7
1 parent ff9fdd6
commit 2482ea7
Show file tree

Hide file tree

Showing 7 changed files with 167 additions and 23 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Zealot
 
-[![Build Status](https://secure.travis-ci.org/blinkfox/zealot.svg)](https://travis-ci.org/blinkfox/zealot) [![codecov](https://codecov.io/gh/blinkfox/zealot/branch/master/graph/badge.svg)](https://codecov.io/gh/blinkfox/zealot) [![Maven Central](https://img.shields.io/maven-central/v/com.blinkfox/zealot.svg)](http://search.maven.org/#artifactdetails%7Ccom.blinkfox%7Czealot%7C1.2.0%7Cjar) [![Javadocs](http://www.javadoc.io/badge/com.blinkfox/zealot.svg)](http://www.javadoc.io/doc/com.blinkfox/zealot)
+[![Build Status](https://secure.travis-ci.org/blinkfox/zealot.svg)](https://travis-ci.org/blinkfox/zealot) [![Maven Central](https://img.shields.io/maven-central/v/com.blinkfox/zealot.svg)](http://search.maven.org/#artifactdetails%7Ccom.blinkfox%7Czealot%7C1.2.0%7Cjar) [![Javadocs](http://www.javadoc.io/badge/com.blinkfox/zealot.svg)](http://www.javadoc.io/doc/com.blinkfox/zealot) [![codecov](https://codecov.io/gh/blinkfox/zealot/branch/master/graph/badge.svg)](https://codecov.io/gh/blinkfox/zealot)
 
 一个简单、强大的Java动态SQL和参数生成工具库。[文档地址](https://blinkfox.github.io/zealot/)
 
@@ -16,12 +16,20 @@ SQL对开发人员来说是核心的资产之一，在开发中经常需要书
 
 ## 二、主要特性
 
-- 轻量级，jar包仅仅`52`k大小，集成和使用简单
-- 提供了纯`Java`代码或`XML`两种方式书写维护SQL
-- `Java`的方式采用流式API的方式书写动态SQL，易于书写阅读
+- 轻量级，jar包仅仅`74`k大小，简单、无副作用的集成和使用
+- 提供了纯`Java`代码和`XML`两种方式书写维护SQL
+- `Java`的方式采用流式API的方式书写动态SQL，易于书写和阅读
 - `XML`的方式让SQL和Java代码解耦和，易于维护
 - 具有动态性、可复用逻辑和可半调试性的优点
-- 具有可扩展性，可自定义标签和处理器来完成自定义逻辑的SQL和参数生成
+- 具有可扩展性，可自定义`XML`标签和处理器来完成自定义逻辑的SQL和参数生成
+
+## 1.3.0版本新增特性
+
+- 完善各种动态SQL操作符和XML标签的`与`、`或`、`非`的逻辑
+- 新增了Zealot配置和调用的更多重载方法
+- 新增了通过注解来配置自定义标签和其对应的Handler
+- 新增了扫描XML文件所在位置（可多个位置，用逗号隔开，目录或具体XML文件均可），默认扫描项目资源目录下`zealot`目录及子目录下的xml文件
+- 新增了`removeIfExist()`方法用来消除`where 1 = 1`等类似无用SQL片段的SQL
 
 ## 三、集成使用
 
@@ -37,13 +45,13 @@ SQL对开发人员来说是核心的资产之一，在开发中经常需要书
 <dependency>
     <groupId>com.blinkfox</groupId>
     <artifactId>zealot</artifactId>
-    <version>1.2.1</version>
+    <version>1.3.0-SNAPSHOT</version>
 </dependency>
 ```
 
 ## 四、Java链式式之ZealotKhala
 
-在Java中书写中等长度的SQL，用`+`连接的字符串尤其是动态字符串，会导致SQL的可读性极差且拼接性能较低，在`Zealot v1.0.4`版本中提供了一个额外高效的SQL字符串链式拼接工具Khala，但Khala只提供拼接字符串的功能，并不具有返回动态SQL和参数的特性，便决定在`v1.1.0`版本中新增了`ZealotKhala`，`ZealotKhala`类也采用流式API的方式可以书写出更流畅的动态SQL，且会得到动态SQL的有序参数。其使用示例如下：
+在Java中书写中等长度的SQL，用`+`连接的字符串尤其是动态字符串，会导致SQL的可读性极差且拼接性能较低，在`Zealot v1.0.4`版本中提供了一个额外高效的SQL字符串链式拼接工具`Khala`(**已被弃用**)，但Khala只提供拼接字符串的功能，并不具有返回动态SQL和参数的特性，便决定在`v1.1.0`版本中新增了`ZealotKhala`，`ZealotKhala`类也采用流式API的方式可以书写出更流畅的动态SQL，且会得到动态SQL的有序参数。其使用示例如下：
 
 ```java
 public class ZealotKhalaTest {
@@ -64,6 +72,7 @@ public class ZealotKhalaTest {
                 .leftJoin("user_detail AS d").on("u.id = d.user_id")
                 .where("u.id != ''")
                 .andLike("u.name", userName)
+                // 该doAnything方法可以在拼接期间做任何代码插入和注入，如果是Java8的话，可以转为Lamda表达式
                 .doAnything(true, new ICustomAction() {
                     @Override
                     public void execute(final StringBuilder join, final List<Object> params) {
@@ -78,6 +87,7 @@ public class ZealotKhalaTest {
                 .andLessEqual("d.birthday", endBirthday)
                 .andBetween("d.birthday", startBirthday, endBirthday)
                 .andIn("u.sex", sexs)
+                .andIsNotNull("u.state")
                 .orderBy("d.birthday").desc()
                 .end();
         String sql = sqlInfo.getSql();
@@ -87,10 +97,11 @@ public class ZealotKhalaTest {
         assertEquals("SELECT u.id, u.name, u.email, d.birthday, d.address FROM user AS u "
                 + "LEFT JOIN user_detail AS d ON u.id = d.user_id WHERE u.id != '' AND u.name LIKE ? "
                 + "abc111 AND u.age > ? AND u.age < ? AND d.birthday >= ? AND d.birthday <= ? "
-                + "AND d.birthday BETWEEN ? AND ? AND u.sex in (?, ?) ORDER BY d.birthday DESC", sql);
+                + "AND d.birthday BETWEEN ? AND ? AND u.sex IN (?, ?) AND u.state IS NOT NULL "
+                + "ORDER BY d.birthday DESC", sql);
         assertArrayEquals(new Object[]{"%zhang%", 5, 21, 13, "1990-03-25", "2010-08-28",
                 "1990-03-25", "2010-08-28", 0, 1} ,arr);
-        log.info("testSql()方法生成的sql信息:" + sql + "\n参数为:" + Arrays.toString(arr));
+        log.info("-- testSql()方法生成的sql信息:\n" + sql + "\n-- 参数为:\n" + Arrays.toString(arr));
     }
 
 }
@@ -99,8 +110,10 @@ public class ZealotKhalaTest {
 打印结果如下：
 
 ```sql
-testSql()方法生成的sql信息:SELECT u.id, u.name, u.email, d.birthday, d.address FROM user AS u LEFT JOIN user_detail AS d ON u.id = d.user_id WHERE u.id != '' AND u.name LIKE ? abc111 AND u.age > ? AND u.age < ? AND d.birthday >= ? AND d.birthday <= ? AND d.birthday BETWEEN ? AND ? AND u.sex in (?, ?) ORDER BY d.birthday DESC
-参数为:[%zhang%, 5, 21, 13, 1990-03-25, 2010-08-28, 1990-03-25, 2010-08-28, 0, 1]
+-- testSql()方法生成的sql信息:
+SELECT u.id, u.name, u.email, d.birthday, d.address FROM user AS u LEFT JOIN user_detail AS d ON u.id = d.user_id WHERE u.id != '' AND u.name LIKE ? abc111 AND u.age > ? AND u.age < ? AND d.birthday >= ? AND d.birthday <= ? AND d.birthday BETWEEN ? AND ? AND u.sex in (?, ?) AND u.state IS NOT NULL ORDER BY d.birthday DESC
+-- 参数为:
+[%zhang%, 5, 21, 13, 1990-03-25, 2010-08-28, 1990-03-25, 2010-08-28, 0, 1]
 ```
 
 ## 五、XML方式之Zealot
@@ -847,12 +860,30 @@ public void testParseTemplate2() {
 - isNotMatch(String match, Object paramObj)，是否不匹配，同`isMatch`相反，只有解析到的值是false时，才认为是false。
 - isTrue(String exp, Object paramObj)，是否为true，只有当解析值确实为true时，才为true。
 
+#### (4). 消除`1 = 1`等无用SQL
+
+在拼接动态SQL中避免不了会出现`1 = 1`等无用的子SQL片段，现在可以通过在生成完的SqlInfo对象中的`removeIfExist(subSql)`方法来消除它，其他类似的子SQL也都可以消除。使用示例如下：
+
+```java
+sqlInfo.removeIfExist(" 1 = 1 AND");
+
+// 或者
+sqlInfo.removeIfExist(" 1 <> 1");
+```
+
 ## 九、许可证
 
 Zealot类库遵守[Apache License 2.0][6] 许可证
 
 ## 十、版本更新记录
 
+- v1.3.0(2018-05-02)
+  - 新增完善各种动态SQL操作符和XML标签的`与`、`或`、`非`的逻辑
+  - 新增了根据自定义模式构建模糊匹配的likePattern标签，新增了isNull、isNotNull等情况
+  - 新增了消除`where 1 = 1`等场景的SQL
+  - 新增了Zealot调用的重载方法
+  - 新增了扫描XML路径来检测识别zealot xml（不配置扫描XML位置的话，默认扫描资源目录下`zealot/`目录中的xml文件）
+  - 新增了扫描Handler注解(`@Tagger`、`@Taggers`)的功能和快速配置
 - v1.2.1(2018-02-04)
   - 新增了通过ZealotConfig的已有实例来配置zealot，这样方便了从spring等已有实例中做配置
 - v1.2.0(2017-08-18)

diff --git a/docs/introduction.md b/docs/introduction.md
@@ -1,4 +1,4 @@
-[![Build Status](https://secure.travis-ci.org/blinkfox/zealot.svg)](https://travis-ci.org/blinkfox/zealot) [![codecov](https://codecov.io/gh/blinkfox/zealot/branch/master/graph/badge.svg)](https://codecov.io/gh/blinkfox/zealot) [![Maven Central](https://img.shields.io/maven-central/v/com.blinkfox/zealot.svg)](http://search.maven.org/#artifactdetails%7Ccom.blinkfox%7Czealot%7C1.2.0%7Cjar) [![Javadocs](http://www.javadoc.io/badge/com.blinkfox/zealot.svg)](http://www.javadoc.io/doc/com.blinkfox/zealot)
+[![Build Status](https://secure.travis-ci.org/blinkfox/zealot.svg)](https://travis-ci.org/blinkfox/zealot) [![Maven Central](https://img.shields.io/maven-central/v/com.blinkfox/zealot.svg)](http://search.maven.org/#artifactdetails%7Ccom.blinkfox%7Czealot%7C1.2.0%7Cjar) [![Javadocs](http://www.javadoc.io/badge/com.blinkfox/zealot.svg)](http://www.javadoc.io/doc/com.blinkfox/zealot) [![codecov](https://codecov.io/gh/blinkfox/zealot/branch/master/graph/badge.svg)](https://codecov.io/gh/blinkfox/zealot)
 
 > `Zealot`是一个简单、强大的Java动态SQL和参数的生成工具库，目的是帮助`Java`开发者书写复杂、动态且易于维护的`SQL`，它只专注于动态构造和生成`SQL`，不做`SQL`执行器，也更不做`ORM`。所以，能集成到任何`ORM`、`Java DAO`工具以及原生的`JDBC`中。
 

diff --git a/docs/java/general-example.md b/docs/java/general-example.md
@@ -19,6 +19,7 @@ public class ZealotKhalaTest {
                 .leftJoin("user_detail AS d").on("u.id = d.user_id")
                 .where("u.id != ''")
                 .andLike("u.name", userName, userName != null)
+                // 该doAnything方法可以在拼接期间做任何代码插入和注入，如果是Java8的话，可以转为Lamda表达式
                 .doAnything(true, new ICustomAction() {
                     @Override
                     public void execute(final StringBuilder join, final List<Object> params) {
@@ -33,6 +34,7 @@ public class ZealotKhalaTest {
                 .andLessEqual("d.birthday", endBirthday)
                 .andBetween("d.birthday", startBirthday, endBirthday)
                 .andIn("u.sex", sexs)
+                .andIsNotNull("u.state")
                 .orderBy("d.birthday").desc()
                 .end();
         String sql = sqlInfo.getSql();
@@ -42,10 +44,11 @@ public class ZealotKhalaTest {
         assertEquals("SELECT u.id, u.name, u.email, d.birthday, d.address FROM user AS u "
                 + "LEFT JOIN user_detail AS d ON u.id = d.user_id WHERE u.id != '' AND u.name LIKE ? "
                 + "abc111 AND u.age > ? AND u.age < ? AND d.birthday >= ? AND d.birthday <= ? "
-                + "AND d.birthday BETWEEN ? AND ? AND u.sex in (?, ?) ORDER BY d.birthday DESC", sql);
+                + "AND d.birthday BETWEEN ? AND ? AND u.sex IN (?, ?) AND u.state IS NOT NULL "
+                + "ORDER BY d.birthday DESC", sql);
         assertArrayEquals(new Object[]{"%zhang%", 5, 21, 13, "1990-03-25", "2010-08-28",
                 "1990-03-25", "2010-08-28", 0, 1} ,arr);
-        log.info("-- testSql()方法生成的sql信息:\n" + sql + "\n-- 参数为:" + Arrays.toString(arr));
+        log.info("-- testSql()方法生成的sql信息:\n" + sql + "\n-- 参数为:\n" + Arrays.toString(arr));
     }
 
 }
@@ -55,7 +58,7 @@ public class ZealotKhalaTest {
 
 ```sql
 -- testSql()方法生成的sql信息:
-SELECT u.id, u.name, u.email, d.birthday, d.address FROM user AS u LEFT JOIN user_detail AS d ON u.id = d.user_id WHERE u.id != '' AND u.name LIKE ? abc111 AND u.age > ? AND u.age < ? AND d.birthday >= ? AND d.birthday <= ? AND d.birthday BETWEEN ? AND ? AND u.sex in (?, ?) ORDER BY d.birthday DESC
+SELECT u.id, u.name, u.email, d.birthday, d.address FROM user AS u LEFT JOIN user_detail AS d ON u.id = d.user_id WHERE u.id != '' AND u.name LIKE ? abc111 AND u.age > ? AND u.age < ? AND d.birthday >= ? AND d.birthday <= ? AND d.birthday BETWEEN ? AND ? AND u.sex in (?, ?) AND u.state IS NOT NULL ORDER BY d.birthday DESC
 -- 参数为:
 [%zhang%, 5, 21, 13, 1990-03-25, 2010-08-28, 1990-03-25, 2010-08-28, 0, 1]
 ```
diff --git a/docs/java/main-method.md b/docs/java/main-method.md
@@ -64,10 +64,16 @@ equal系列是用来拼接SQL中等值查询的系列方法，生成如：` u.em
 - andEqual(String field, Object value, boolean match)
 - orEqual(String field, Object value)
 - orEqual(String field, Object value, boolean match)
+- notEqual(String field, Object value)
+- notEqual(String field, Object value, boolean match)
+- andNotEqual(String field, Object value)
+- andNotEqual(String field, Object value, boolean match)
+- orNotEqual(String field, Object value)
+- orNotEqual(String field, Object value, boolean match)
 
 **方法解释**：
 
-- equal、andEqual、orEqual，分别表示拼接等值查询SQL的前缀为`空字符串`,` AND `，` OR `
+- equal、andEqual、orEqual，分别表示拼接等值查询SQL的前缀为`空字符串`,` AND `，` OR `。
 - field，表示数据库字段
 - value，表示Java中的变量或常量值
 - match，表示是否生成该SQL片段，值为`true`时生成，否则不生成
@@ -126,6 +132,7 @@ u.nick_name = ? AND u.true_age = ? AND u.true_age = ? OR u.email = ?
 - `moreEqual` 大于等于
 - `lessEqual` 小于等于
 - `like` 模糊查询
+- `likePattern` 根据自定义模式来匹配
 
 !> 以上各系列的方法也同equal，这里就不再赘述了。
 
@@ -205,10 +212,16 @@ in系列是用来拼接SQL中范围查询的系列方法，生成如：` u.sex i
 - andIn(String field, Object[] values, boolean match)
 - orIn(String field, Object[] values)
 - orIn(String field, Object[] values, boolean match)
+- notIn(String field, Object[] values)
+- notIn(String field, Object[] values, boolean match)
+- andNotIn(String field, Object[] values)
+- andNotIn(String field, Object[] values, boolean match)
+- orNotIn(String field, Object[] values)
+- orNotIn(String field, Object[] values, boolean match)
 
 **方法解释**：
 
-- in、andIn、orIn，分别表示拼接范围查询SQL的前缀为`空字符串`,` AND `，` OR `
+- in、andIn、orIn，分别表示拼接范围查询SQL的前缀为`空字符串`,` AND `，` OR `。
 - field，表示数据库字段
 - values，表示范围查询需要的参数的数组
 - match，表示是否生成该SQL片段，值为`true`时生成，否则不生成
@@ -226,7 +239,7 @@ public static void init() {
 }
 
 /**
- * between相关方法测试.
+ * in相关方法测试.
  */
 @Test
 public void testBetween() {
@@ -253,13 +266,84 @@ u.sex in (?, ?) AND u.sex in (?, ?) OR u.sex in (?, ?)
 [0, 1, 0, 1, 0, 1]
 ```
 
+### isNull
+
+#### 方法介绍
+
+`isNull`系列是用来拼接SQL中判断字段为null值或不为null值情况的系列方法，生成如：` u.state IS NULL `这样SQL片段的功能，主要包含如下方法：
+
+- isNull(String field)
+- isNull(String field, boolean match)
+- andIsNull(String field)
+- andIsNull(String field, boolean match)
+- orIsNull(String field)
+- orIsNull(String field, boolean match)
+- isNotNull(String field)
+- isNotNull(String field, boolean match)
+- andIsNotNull(String field)
+- andIsNotNull(String field, boolean match)
+- orIsNotNull(String field)
+- orIsNotNull(String field, boolean match
+
+**方法解释**：
+
+- isNull、andIsNull、orIsNull，分别表示拼接null值判断SQL的前缀为`空字符串`,` AND `，` OR `。
+- field，表示数据库字段
+- match，表示是否生成该SQL片段，值为`true`时生成，否则不生成
+
+#### 使用示例如下：
+
+```java
+/**
+ * IS NULL相关方法测试.
+ */
+@Test
+public void testIsNull() {
+    long start = System.currentTimeMillis();
+
+    SqlInfo sqlInfo = ZealotKhala.start()
+            .isNull("a.name")
+            .isNull("b.email")
+            .isNull("a.name", true)
+            .isNull("b.email", false)
+            .andIsNull("a.name")
+            .andIsNull("b.email")
+            .andIsNull("a.name", false)
+            .andIsNull("b.email", true)
+            .orIsNull("a.name")
+            .orIsNull("b.email")
+            .orIsNull("a.name", false)
+            .orIsNull("b.email", true)
+            .end();
+
+    log.info("testIn()方法执行耗时:" + (System.currentTimeMillis() - start) + " ms");
+    String sql = sqlInfo.getSql();
+    Object[] arr = sqlInfo.getParamsArr();
+
+    // 断言并输出sql信息
+    assertEquals("a.name IS NULL b.email IS NULL a.name IS NULL AND a.name IS NULL AND b.email IS NULL "
+            + "AND b.email IS NULL OR a.name IS NULL OR b.email IS NULL OR b.email IS NULL", sql);
+    assertArrayEquals(new Object[]{} ,arr);
+    log.info("-- testIsNull()方法生成的sql信息:\n" + sql + "\n-- 参数为:\n" + Arrays.toString(arr));
+}
+```
+
+打印的SQL如下：
+
+```sql
+-- testIsNull()方法生成的sql信息:
+a.name IS NULL b.email IS NULL a.name IS NULL AND a.name IS NULL AND b.email IS NULL AND b.email IS NULL OR a.name IS NULL OR b.email IS NULL OR b.email IS NULL
+-- 参数为:
+[]
+```
+
 ### doAnything
 
 > doAnything(ICustomAction action)
 
 > doAnything(boolean match, ICustomAction action)
 
-这两个方法主要用来方便你在链式拼接的过程中，来完成更多自定义、灵活的操作。`match`意义和上面类似，值为true时才执行，`ICustomAction`是你自定义操作的接口，执行时调用`execute()`方法,使用示例如下：
+这两个方法主要用来方便你在链式拼接的过程中，来完成更多自定义、灵活的操作。`match`意义和上面类似，值为true时才执行，`ICustomAction`是你自定义操作的函数式接口，执行时调用`execute()`方法,使用示例如下：
 
 ```java
 SqlInfo sqlInfo = ZealotKhala.start()
@@ -273,3 +357,16 @@ SqlInfo sqlInfo = ZealotKhala.start()
         })
         .end();
 ```
+
+如果是Java8的话，可以将以上代码转成Lambda表达式，代码如下：
+
+```java
+SqlInfo sqlInfo = ZealotKhala.start()
+        .doAnything(true, (join, params) -> {
+                join.append("abc111");
+                params.add(5);
+                log.info("执行了自定义操作，可任意插入、拼接字符串和有序参数...");
+            }
+        })
+        .end();
+```
diff --git a/docs/java/use-intro.md b/docs/java/use-intro.md
@@ -1,6 +1,6 @@
-在Java中书写中等长度的SQL，用`+`连接的字符串或`StringBuilder`等尤其是动态字符串，会导致SQL的可读性很差，在`Zealot v1.0.4`版本中提供了一个额外高效的SQL字符串链式拼接工具`Khala`，但`Khala`只提供拼接字符串的功能，并不具有返回动态SQL和参数的特性，便决定在v1.1.0版本中新增了`ZealotKhala`，`ZealotKhala`也采用了`流式API`的方式来书写“更流畅”的动态SQL，且会得到动态SQL的有序参数。
+在Java中书写中等长度的SQL，用`+`连接的字符串或`StringBuilder`等尤其是动态字符串，会导致SQL的可读性很差，在`Zealot v1.0.4`版本中提供了一个额外高效的SQL字符串链式拼接工具`Khala`(**已被弃用**)，但`Khala`只提供拼接字符串的功能，并不具有返回动态SQL和参数的特性，便决定在v1.1.0版本中新增了`ZealotKhala`，`ZealotKhala`也采用了`流式API`的方式来书写“更流畅”的动态SQL，且会得到动态SQL的有序参数。
 
-ZealotKhala 使用方式如下：
+`ZealotKhala`使用方式如下：
 
 ```java
 SqlInfo sqlInfo = ZealotKhala.start()