新增了另一种方式的使用和文档修改

blinkfox · Nov 20, 2019 · a5bf57e · a5bf57e
1 parent bd0348e
commit a5bf57e
Show file tree

Hide file tree

Showing 7 changed files with 89 additions and 31 deletions.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,6 +1,6 @@
-## v2.1.0 新增 <where> 标签和对应的 Java API (2019-11-20)
+## v2.1.0 新增 <where> 标签和对应的 Java API (2019-11-21)
 
-- 新增了 `<where>` 标签和 `where(Consumer<Fenix> consumer)` API，用来消除全动态 SQL 中 `WHERE` 关键字后的 `AND` 或者 `OR` 关键字；
+- 新增了 `<where>` 标签和动态 `where` 的 Java API，用来消除在全动态 SQL 中场景中，`WHERE` 关键字后的 `AND` 或者 `OR` 关键字；
 
 ## v2.0.0 支持 Spring Boot 的 2.2.0.RELEASE 版本 (2019-10-10)
 

diff --git a/docs/compare-mybatis.md b/docs/compare-mybatis.md
@@ -89,12 +89,11 @@
             ol.description
         FROM
             OperationLog AS ol
-        <where>
-            <andLike field="ol.title" value="log.title" match="log.title != empty"/>
-            <andIn field="ol.type" value="log.typeList" match="log.typeList != empty"/>
-            <andEqual field="ol.result" value="log.result" match="log.result != empty"/>
-            <andBetween field="ol.createTime" start="log.startTime" end="log.endTime" match="(log.startTime != empty) || (log.endTime != empty)"/>
-        </where>
+        <where />
+        <andLike field="ol.title" value="log.title" match="log.title != empty"/>
+        <andIn field="ol.type" value="log.typeList" match="log.typeList != empty"/>
+        <andEqual field="ol.result" value="log.result" match="log.result != empty"/>
+        <andBetween field="ol.createTime" start="log.startTime" end="log.endTime" match="(log.startTime != empty) || (log.endTime != empty)"/>
     </fenix>
 
 </fenixs>
@@ -106,7 +105,7 @@
 
 - MyBatis 只能写原生 SQL，无法享受跨数据库时的兼容性；由于 Fenix 是基于 Spring Data JPA 的扩展，即可以写 `JPQL` 语句，也可以写原生 `SQL` 语句，上述示例中写的是 `JPQL` 语句，SQL 的字段表达上更简洁，也不需要再定义 `resultMap` 映射关系。
 - MyBatis 书写动态 SQL 依赖只能使用 `if/else`、`foreach` 等分支选择、循环等操作，保证了灵活性，但是代码量和重复性较高，且 SQL 嵌套多层，视觉上比较混乱，可读写差；而 Fenix 也有 `if/else`、`foreach` 等分支循环操作，但内置了大量的更加简单、强大和语义化的 XML [SQL 标签](xml/xml-tags)，使用语义化的 SQL 标签，使得 SQL 的语义简单明了，没有多层嵌套，可读写更好，通过 `match` 属性的值来确定是否生成此条 SQL，来达到动态性。
-- MyBatis 通过 `trim` 标签或者使用 `<where>` 标签来消除 `WHERE` 语句后的 `AND` 关键字，`Fenix` 也是使用 `<where>` 标签来包裹即可。也可以通过在 `<fenix />` 节点中声明 `removeIfExist` 属性（非必填）来声明式的消除。
+- MyBatis 通过 `trim` 标签或者使用 `<where>` 标签来消除 `WHERE` 语句后的 `AND` 关键字，而 `Fenix` 也是直接使用 `<where />` 标签即可动态处理 `WHERE` 与 `AND` 的关系，也可以将各个动态条件包裹在 `<where></where>` 标签内。
 - MyBatis 的动态 SQL 解析引擎是 [OGNL](http://commons.apache.org/proper/commons-ognl/)，而 Fenix 的解析引擎是 [MVEL](http://mvel.documentnode.com/)，功能和性能上都更优一些。
 
 > 通过以上 MyBatis 和 Fenix 的各自 SQL 写法比较来看，`Fenix` 的 SQL 在**动态性**、**简介性**和**SQL 语义化**等方面，都更加强大。
diff --git a/docs/java/main-method.md b/docs/java/main-method.md
@@ -447,11 +447,32 @@ where(String text, String key, Object value)
 
 // 通过 Lambda 继续拼接 SQL，并动态处理 WHERE 关键字后的 AND 或者 OR 关键字.
 where(Consumer<Fenix> consumer)
+
+// 通过 Lambda 继续拼接 SQL，并动态处理 WHERE 关键字后的 AND 或者 OR 关键字.
+// 该方法等价于 XML 中的 <where></where> 标签
+where(Consumer<Fenix> consumer)
+
+// 使用该方法会动态处理 WHERE 关键字后的 AND 或者 OR 关键字，同 where(Consumer<Fenix> consumer) 方法类似.
+// 该方法等价于 XML 中的 <where /> 标签
+whereDynamic()
 ```
 
 ### 使用示例
 
-下面是 `where(Consumer<Fenix> consumer)` 的执行示例，供你参考。
+下面是动态 where（`whereDynamic()` 和 `where(Consumer<Fenix> consumer)`）的使用示例，供你参考。
+
+```java
+SqlInfo sqlInfo = Fenix.start()
+        .select("u")
+        .from("User")
+        .whereDynamic()
+        .andEqual("u.id", context.get("id"), context.get("id_a") != null)
+        .andLike("u.nickName", context.get("name"), context.get("name") != null)
+        .andLike("u.email", context.get("email"), context.get("email") != null)
+        .andIn("u.sex", (Object[]) context.get("sexs"), context.get("sexs") != null)
+        .orderBy("u.updateTime").desc()
+        .end();
+```
 
 ```java
 SqlInfo sqlInfo = Fenix.start()

diff --git a/docs/xml/xml-tags.md b/docs/xml/xml-tags.md
@@ -266,14 +266,44 @@ AND u.n_age IS NULL
 
 ### 标签
 
+下面是 `where` 标签的使用方式，两种方式是等价的，看情况选用一种方式即可。
+
 ```xml
+<!-- 直接在动态条件前加上 where 标签即可. -->
+<where />
+
+<!-- 或者将动态条件包裹在 where 标签内部也可以. -->
 <where>
     <!-- 在 where 标签块中可以书写任何文本 SQL 或者 XML 语义化 SQL 标签. -->
 </where>
 ```
 
 ### 使用示例
 
+```xml
+<!-- 用于演示 where 标签的使用，假如 user.email 的值为空，那么生成的 SQL 结果为: -->
+<!-- SELECT u FROM User WHERE u.id = :user_id AND u.name LIKE :user_name ORDER BY u.updateTime DESC -->
+<fenix id="testWhere">
+    SELECT u FROM @{entityName}
+    <where />
+    anD u.id = #{user.id}
+    <andEqual field="u.email" value="user.email" match="user.email != empty"/>
+    <andLike field="u.name" value="user.name" match="user.name != empty"/>
+    ORDER BY u.updateTime DESC
+</fenix>
+
+<!-- 用于演示 where 标签的使用，假如 user.email 和 birthday 的值都为空，那么生成的 SQL 结果为: -->
+<!-- SELECT u FROM User -->
+<fenix id="testWhere2">
+    SELECT u FROM @{entityName}
+    <where />
+    <andEqual field="u.email" value="user.email" match="user.email != empty"/>
+    <andLike field="u.birthday" value="user.birthday" match="user.birthday != empty"/>
+</fenix>
+```
+
+下面的使用方式等价于上面的方式，看情况选用一种方式来使用即可：
+
 ```xml
 <!-- 用于演示 where 标签的使用，假如 user.email 的值为空，那么生成的 SQL 结果为: -->
 <!-- SELECT u FROM User WHERE u.id = :user_id AND u.name LIKE :user_name ORDER BY u.updateTime DESC -->
@@ -284,8 +314,7 @@ AND u.n_age IS NULL
         <andEqual field="u.email" value="user.email" match="user.email != empty"/>
         <andLike field="u.name" value="user.name" match="user.name != empty"/>
     </where>
-    ORDER BY
-        u.updateTime DESC
+    ORDER BY u.updateTime DESC
 </fenix>
 
 <!-- 用于演示 where 标签的使用，假如 user.email 和 birthday 的值都为空，那么生成的 SQL 结果为: -->

diff --git a/src/main/java/com/blinkfox/fenix/core/Fenix.java b/src/main/java/com/blinkfox/fenix/core/Fenix.java
@@ -238,6 +238,18 @@ public Fenix where(Consumer<Fenix> consumer) {
         return this;
     }
 
+    /**
+     * 动态处理 WHERE 关键字.
+     *
+     * <p>使用该方法会动态处理 WHERE 关键字后的 AND 或者 OR 关键字，同 {@link #where(Consumer)} 方法类似.</p>
+     *
+     * @return {@link Fenix} 实例
+     */
+    public Fenix whereDynamic() {
+        this.source.getSqlInfo().setPrependWhere(true);
+        return this;
+    }
+
     /**
      * 拼接并带上 'AND' 关键字的字符串.
      *

diff --git a/src/test/java/com/blinkfox/fenix/core/FenixTest.java b/src/test/java/com/blinkfox/fenix/core/FenixTest.java
@@ -664,9 +664,9 @@ public void testWhere2() {
         SqlInfo sqlInfo = Fenix.start()
                 .select("u")
                 .from("User")
-                .where(fenix ->
-                        fenix.andEqual("u.id", context.get("id"), context.get("id_a") != null)
-                                .andLike("u.nickName", context.get("name"), context.get("name_b") != null))
+                .whereDynamic()
+                .andEqual("u.id", context.get("id"), context.get("id_a") != null)
+                .andLike("u.nickName", context.get("name"), context.get("name_b") != null)
                 .orderBy("u.updateTime").desc()
                 .end();
 
@@ -682,9 +682,9 @@ public void testWhere3() {
         SqlInfo sqlInfo = Fenix.start()
                 .select("u")
                 .from("User")
-                .where(fenix ->
-                        fenix.andEqual("u.id", context.get("id"), context.get("id_a") != null)
-                                .andLike("u.nickName", context.get("name"), context.get("name") != null))
+                .whereDynamic()
+                .andEqual("u.id", context.get("id"), context.get("id_a") != null)
+                .andLike("u.nickName", context.get("name"), context.get("name") != null)
                 .andIn("u.sex", (Object[]) context.get("sexs"), context.get("sexs") != null)
                 .orderBy("u.updateTime").desc()
                 .end();

diff --git a/src/test/resources/fenix/fenix.xml b/src/test/resources/fenix/fenix.xml
@@ -234,29 +234,26 @@
     <!-- 用于单元测试 where 标签生成的 JPQL 语句和参数. -->
     <fenix id="testWhere">
         SELECT u FROM @{entityName}
-        <where>
-            <andEqual field="u.id" value="user.id" match="user.id != empty"/>
-            <andLike field="u.name" value="user.name" match="user.name != empty"/>
-        </where>
+        <where />
+        <andEqual field="u.id" value="user.id" match="user.id != empty"/>
+        <andLike field="u.name" value="user.name" match="user.name != empty"/>
     </fenix>
 
     <!-- 用于单元测试 where 标签生成的 JPQL 语句和参数. -->
     <fenix id="testWhere2">
         SELECT u FROM @{entityName}
-        <where>
-            <andEqual field="u.email" value="user.email" match="user.email != empty"/>
-            <andLike field="u.birthday" value="user.birthday" match="user.birthday != empty"/>
-        </where>
+        <where />
+        <andEqual field="u.email" value="user.email" match="user.email != empty"/>
+        <andLike field="u.birthday" value="user.birthday" match="user.birthday != empty"/>
     </fenix>
 
     <!-- 用于单元测试 where 标签生成的 JPQL 语句和参数. -->
     <fenix id="testWhere3">
         SELECT u FROM @{entityName}
-        <where>
-            anD u.id = #{user.id}
-            <andEqual field="u.email" value="user.email" match="user.email != empty"/>
-            <andLike field="u.name" value="user.name" match="user.name != empty"/>
-        </where>
+        <where />
+        anD u.id = #{user.id}
+        <andEqual field="u.email" value="user.email" match="user.email != empty"/>
+        <andLike field="u.name" value="user.name" match="user.name != empty"/>
         ORDER BY
             u.updateTime DESC
     </fenix>