开启 v2.5.0 版本，并新增了 TrimWhere 标签，修改了相关的文档

blinkfox · May 7, 2021 · a4dc92b · a4dc92b
1 parent ca14d72
commit a4dc92b
Show file tree

Hide file tree

Showing 14 changed files with 271 additions and 109 deletions.
diff --git a/README.md b/README.md
@@ -2,15 +2,15 @@
 
 <div align="center"><img style="display: block; margin: 0 auto;" src="https://blinkfox.github.io/fenix/assets/images/logo.png" alt="fenix logo" /></div>
 
-[![Build Status](https://secure.travis-ci.org/blinkfox/fenix.svg)](https://travis-ci.org/blinkfox/fenix) [![HitCount](http://hits.dwyl.io/blinkfox/fenix.svg)](http://hits.dwyl.io/blinkfox/fenix) [![Javadocs](http://www.javadoc.io/badge/com.blinkfox/fenix.svg)](http://www.javadoc.io/doc/com.blinkfox/fenix) [![GitHub license](https://img.shields.io/github/license/blinkfox/fenix.svg)](https://github.com/blinkfox/fenix/blob/develop/LICENSE) [![fenix](https://img.shields.io/badge/fenix-v2.4.2-blue)](https://search.maven.org/artifact/com.blinkfox/fenix/2.4.2/jar) [![fenix starter](https://img.shields.io/badge/fenix%20spring%20boot%20starter-v2.4.2-blue)](https://search.maven.org/artifact/com.blinkfox/fenix-spring-boot-starter/2.4.2/jar) [![codecov](https://codecov.io/gh/blinkfox/fenix/branch/develop/graph/badge.svg)](https://codecov.io/gh/blinkfox/fenix)
+[![Build Status](https://secure.travis-ci.org/blinkfox/fenix.svg)](https://travis-ci.org/blinkfox/fenix) [![HitCount](http://hits.dwyl.io/blinkfox/fenix.svg)](http://hits.dwyl.io/blinkfox/fenix) [![Javadocs](http://www.javadoc.io/badge/com.blinkfox/fenix.svg)](http://www.javadoc.io/doc/com.blinkfox/fenix) [![GitHub license](https://img.shields.io/github/license/blinkfox/fenix.svg)](https://github.com/blinkfox/fenix/blob/develop/LICENSE) [![fenix](https://img.shields.io/badge/fenix-v2.5.0-blue)](https://search.maven.org/artifact/com.blinkfox/fenix/2.5.0/jar) [![fenix starter](https://img.shields.io/badge/fenix%20spring%20boot%20starter-v2.5.0-blue)](https://search.maven.org/artifact/com.blinkfox/fenix-spring-boot-starter/2.5.0/jar) [![codecov](https://codecov.io/gh/blinkfox/fenix/branch/develop/graph/badge.svg)](https://codecov.io/gh/blinkfox/fenix)
 
 > [Fenix](https://github.com/blinkfox/fenix)（菲尼克斯）是一个为了解决复杂动态 SQL (`JPQL`) 而生的 `Spring Data JPA` 扩展库，目的是辅助开发者更方便快捷的书写复杂、动态且易于维护的 SQL，支持 `XML`、Java 链式 `API` 和动态条件注解等四种方式来书写动态 SQL。
 
 [📖 使用文档](https://blinkfox.github.io/fenix) | [🍉 示例项目 (fenix-example)](https://github.com/blinkfox/fenix-example)
 
 ## 💎 一、特性
 
-- 简单、轻量级、无副作用的集成和使用，jar 包仅 `192 KB`；
+- 简单、轻量级、无副作用的集成和使用，jar 包仅 `194 KB`；
 - 作为 JPA 的扩展和增强，兼容 Spring Data JPA 原有功能和各种特性；
 - 提供了 `XML`、Java 链式 `API` 和动态条件注解等四种方式来书写动态 SQL；
 - `XML` 的方式功能强大，让 SQL 和 Java 代码解耦，易于维护；
@@ -40,14 +40,14 @@
 <dependency>
     <groupId>com.blinkfox</groupId>
     <artifactId>fenix-spring-boot-starter</artifactId>
-    <version>2.4.2</version>
+    <version>2.5.0</version>
 </dependency>
 ```
 
 ### 🌵 2. Gradle
 
 ```bash
-compile 'com.blinkfox:fenix-spring-boot-starter:2.4.2'
+compile 'com.blinkfox:fenix-spring-boot-starter:2.5.0'
 ```
 
 ### 🏕️ 3. 激活 Fenix (@EnableFenix)

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,6 +1,10 @@
 # 🍹 版本更新记录 :id=title
 
-## ⛸️ v2.4.2 小 bug 修复版本 🆕 (2021-02-03) :id=v242
+## 🎿 v2.5.0 新增了 trimWhere 标签 🆕 (2021-05-07) :id=v250
+
+- 新增了 `trimWhere` 标签，用于完全替代之前的 `where` 标签，用于修复它的已知 [bug](https://github.com/blinkfox/fenix/issues/43)，以前的 `where` 标签将继续保留但不再推荐使用；
+
+## ⛸️ v2.4.2 小 bug 修复版本 (2021-02-03) :id=v242
 
 - 修复了使用 `Pageable.unpaged()` 时的异常；
 

diff --git a/docs/README.md b/docs/README.md
@@ -9,7 +9,7 @@
 
 ## 💎 特性 :id=features
 
-- 简单、轻量级、无副作用的集成和使用，jar 包仅 `192 KB`；
+- 简单、轻量级、无副作用的集成和使用，jar 包仅 `194 KB`；
 - 作为 JPA 的扩展和增强，兼容 Spring Data JPA 原有功能和各种特性；
 - 提供了 `XML`、Java 链式 `API` 和动态条件注解等四种方式来书写动态 SQL；
 - `XML` 的方式功能强大，让 SQL 和 Java 代码解耦，易于维护；

diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -1,10 +1,10 @@
 ![logo](assets/images/logo.png)
 
-# Fenix <small>2.4.2</small>
+# Fenix <small>2.5.0</small>
 
 > 为解决复杂动态 SQL 而生的 Spring Data JPA 扩展库
 
-- 🌱 简单、可扩展、轻量级 (~192 KB jar)
+- 🌱 简单、可扩展、轻量级 (~194 KB jar)
 - 🌴 可返回任意自定义的实体对象
 - 🌿 比 MyBatis 更加强大的动态 SQL 能力
 - 🌾 支持“增量更新”和更快速的“批量增删改”操作

diff --git a/docs/compare-mybatis.md b/docs/compare-mybatis.md
@@ -88,12 +88,14 @@
             ol.createTime,
             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)"/>
+        OperationLog AS ol
+        <trimWhere>
+            <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)"/>
+        </trimWhere>
     </fenix>
 
 </fenixs>
@@ -105,7 +107,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 />` 标签即可动态处理 `WHERE` 与 `AND` 的关系，也可以将各个动态条件包裹在 `<where></where>` 标签内。
+- MyBatis 通过 `<trim />` 标签或者使用 `<where />` 标签来消除 `WHERE` 语句后的 `AND` 或者 `OR` 关键字，而 `Fenix` 也是直接将各个动态条件的 SQL 包裹在 `<trimWhere />` 标签中。
 - 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/quick-install.md b/docs/quick-install.md
@@ -16,14 +16,14 @@
 <dependency>
     <groupId>com.blinkfox</groupId>
     <artifactId>fenix-spring-boot-starter</artifactId>
-    <version>2.4.2</version>
+    <version>2.5.0</version>
 </dependency>
 ```
 
 ### 🌵 2. Gradle :id=spring-boot-gradle
 
 ```bash
-compile 'com.blinkfox:fenix-spring-boot-starter:2.4.2'
+compile 'com.blinkfox:fenix-spring-boot-starter:2.5.0'
 ```
 
 ### 🏕️ 3. 激活 Fenix (@EnableFenix) :id=enable-fenix
@@ -98,14 +98,14 @@ fenix:
 <dependency>
     <groupId>com.blinkfox</groupId>
     <artifactId>fenix</artifactId>
-    <version>2.4.2</version>
+    <version>2.5.0</version>
 </dependency>
 ```
 
 ### 🌻 2. Gradle :id=project-gradle
 
 ```bash
-compile 'com.blinkfox:fenix:2.4.2'
+compile 'com.blinkfox:fenix:2.5.0'
 ```
 
 ### 🏔️ 3. 激活 Fenix :id=project-enable-fenix

diff --git a/docs/xml/xml-tags.md b/docs/xml/xml-tags.md
@@ -16,7 +16,7 @@ Fenix 中提供了大量常见场景下的 XML 标签供开发者使用，且这
 - [between](/xml/xml-tags?id=between)
 - [in](/xml/xml-tags?id=in)
 - [is null](/xml/xml-tags?id=is-null)
-- [where](/xml/xml-tags?id=where)
+- [trimWhere](/xml/xml-tags?id=trimWhere)
 - [text](/xml/xml-tags?id=text)
 - [import](/xml/xml-tags?id=import)
 - [choose](/xml/xml-tags?id=choose)
@@ -293,71 +293,46 @@ AND u.sex in :mySex
 AND u.n_age IS NULL
 ```
 
-## 🐎 九、where :id=where
+## 🐎 九、trimWhere :id=trimWhere
 
-`where` 标签主要用于在全动态 SQL 的场景中消除 `WHERE` 关键字后面的 `AND` 或者 `OR` 关键字，防止拼接出的动态 SQL 语法不对。
+`trimWhere` 标签属于 `v2.5.0` 版本新增的标签。主要用于在全动态 SQL 的场景中消除 `WHERE` 关键字后面的 `AND` 或者 `OR` 关键字，防止拼接出的动态 SQL 语法不对。
+
+> **💡 注**：本 `trimWhere` 标签修改自之前版本中的 `where` 标签，不过 `where` 标签存在已知的 `bug`。因为 `where` 允许和其他的动态条件标签写在 XML 的同一层级，当动态标签都不满足条件时，会导致结果多一个 `WHERE` 关键字，导致最终生成的 JPQL 或 SQL 无法正确的运行。为了保持对以前 `where` 标签写法的兼容。所以，**在 `v2.5.0` 版本中新增了标签 `trimWhere` 标签。可以用于完全替代 `where` 标签，且写法上只允许包裹式的写法，并且以前的 `where` 标签将继续保留但不再推荐使用**。后续也将只会介绍 `trimWhere` 标签。
 
 ### 🔮 1. 标签 :id=where-tag
 
-下面是 `where` 标签的使用方式，两种方式是等价的，看情况选用一种方式即可。
+下面是 `trimWhere` 标签的使用方式。
 
 ```xml
-<!-- 直接在动态条件前加上 where 标签即可. -->
-<where />
-
-<!-- 或者将动态条件包裹在 where 标签内部也可以. -->
-<where>
-    <!-- 在 where 标签块中可以书写任何文本 SQL 或者 XML 语义化 SQL 标签. -->
-</where>
+<!-- 将动态条件包裹在 trimWhere 标签内部即可. -->
+<trimWhere>
+    <!-- 在 trimWhere 标签块中可以书写任何文本 SQL 或者 XML 语义化 SQL 标签. -->
+</trimWhere>
 ```
 
 ### 🧿 2. 使用示例 :id=where-demo
 
 ```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 结果为: -->
+<!-- 用于演示 trimWhere 标签的使用，假如 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>
+    <trimWhere>
         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>
+    </trimWhere>
     ORDER BY u.updateTime DESC
 </fenix>
 
-<!-- 用于演示 where 标签的使用，假如 user.email 和 birthday 的值都为空，那么生成的 SQL 结果为: -->
+<!-- 用于演示 trimWhere 标签的使用，假如 user.email 和 birthday 的值都为空，那么生成的 SQL 结果为: -->
 <!-- SELECT u FROM User -->
 <fenix id="testWhere2">
     SELECT u FROM @{entityName}
-    <where>
+    <trimWhere>
         <andEqual field="u.email" value="user.email" match="user.email != empty"/>
         <andLike field="u.birthday" value="user.birthday" match="user.birthday != empty"/>
-    </where>
+    </trimWhere>
 </fenix>
 ```
 

diff --git a/pom.xml b/pom.xml
@@ -5,7 +5,7 @@
 
     <groupId>com.blinkfox</groupId>
     <artifactId>fenix</artifactId>
-    <version>2.4.2</version>
+    <version>2.5.0-SNAPSHOT</version>
     <packaging>jar</packaging>
 
     <name>fenix</name>

diff --git a/src/main/java/com/blinkfox/fenix/config/FenixConfig.java b/src/main/java/com/blinkfox/fenix/config/FenixConfig.java
@@ -17,6 +17,7 @@
 import com.blinkfox.fenix.core.concrete.StartsWithHandler;
 import com.blinkfox.fenix.core.concrete.TextHandler;
 import com.blinkfox.fenix.core.concrete.WhereHandler;
+import com.blinkfox.fenix.core.concrete.TrimWhereHandler;
 import com.blinkfox.fenix.specification.handler.AbstractPredicateHandler;
 import com.blinkfox.fenix.specification.handler.impl.BetweenPredicateHandler;
 import com.blinkfox.fenix.specification.handler.impl.EndsWithPredicateHandler;
@@ -240,6 +241,7 @@ private static void initDefaultTagHandler() {
         add("choose", ChooseHandler::new);
         add("set", SetHandler::new);
         add("where", WhereHandler::new);
+        add("trimWhere", TrimWhereHandler::new);
     }
 
     /**

diff --git a/src/main/java/com/blinkfox/fenix/config/FenixConfigManager.java b/src/main/java/com/blinkfox/fenix/config/FenixConfigManager.java
@@ -41,7 +41,7 @@ public final class FenixConfigManager {
             + " |    __)/ __ \\ /    \\|  \\  \\/  /\n"
             + " |     \\\\  ___/|   |  \\  |>    < \n"
             + " \\___  / \\___  >___|  /__/__/\\_ \\\n"
-            + "     \\/      \\/     \\/         \\/ v2.4.2\n";
+            + "     \\/      \\/     \\/         \\/ v2.5.0\n";
 
     /**
      * Fenix 配置信息实例.

diff --git a/src/main/java/com/blinkfox/fenix/core/concrete/TrimWhereHandler.java b/src/main/java/com/blinkfox/fenix/core/concrete/TrimWhereHandler.java
@@ -0,0 +1,46 @@
+package com.blinkfox.fenix.core.concrete;
+
+import com.blinkfox.fenix.bean.BuildSource;
+import com.blinkfox.fenix.bean.SqlInfo;
+import com.blinkfox.fenix.core.FenixHandler;
+import com.blinkfox.fenix.core.FenixXmlBuilder;
+
+/**
+ * {@code <trimWhere></trimWhere>} 标签是可以包裹其他动态标签的标签，功能同 MyBatis 中的 {@code <where>} 标签相似，
+ * 用于去掉 {@code WHERE} 关键字后的 {@code AND} 或者 {@code OR} 关键字的 {@link FenixHandler} 接口的实现类.
+ *
+ * <p>注意：该标签源自于 {@code <where />}，由于 {@code <where />} 标签存在 bug，且为了保持向前兼容，所以新增此标签，并推荐使用此标签.</p>
+ *
+ * <p>XML 标签示例如：</p>
+ * <ul>
+ *     <li>{@code <trimWhere>...</trimWhere>}</li>
+ * </ul>
+ * <p>注：{@code <trimWhere>} 标签只能用来去掉{@code WHERE} 关键字后的 {@code AND} 或者 {@code OR} 关键字.</p>
+ *
+ * @author blinkfox on 2021-05-07.
+ * @see WhereHandler
+ * @since v2.5.0
+ */
+public class TrimWhereHandler implements FenixHandler {
+
+    /**
+     * 根据 {@link BuildSource} 的相关参数来动态构建出 {@code WHERE} 语句后的 SQL 或 JPQL 语句及参数信息.
+     *
+     * @param source 构建所需的 {@code BuildSource} 资源对象
+     */
+    @Override
+    public void buildSqlInfo(BuildSource source) {
+        // 进入此方法后，将 prependWhere 设置为 true,
+        // 说明后续的动态条件的 SQL 语句中都要判断是否要前置添加 WHERE 关键字，并去除掉 WHERE 后面的 AND 或者 OR 关键字.
+        // 在各个动态标签或文本标签中，如果处理了 WHERE 标签的情况之后，就再将 prependWhere 设置为 false 即可.
+        SqlInfo sqlInfo = source.getSqlInfo();
+        sqlInfo.setPrependWhere(true);
+        FenixXmlBuilder.buildSqlInfo(source.getNamespace(), sqlInfo, source.getNode(), source.getContext());
+
+        // 如果 '<trimWhere></trimWhere>' 标签中的内容构建完成之后，任然是 true 时，就设置为 false.
+        if (sqlInfo.isPrependWhere()) {
+            sqlInfo.setPrependWhere(false);
+        }
+    }
+
+}
diff --git a/src/main/java/com/blinkfox/fenix/core/concrete/WhereHandler.java b/src/main/java/com/blinkfox/fenix/core/concrete/WhereHandler.java
@@ -16,7 +16,7 @@
  * <p>注：{@code <where>} 标签只能用来去掉{@code WHERE} 关键字后的 {@code AND} 或者 {@code OR} 关键字.</p>
  *
  * @author blinkfox on 2019-08-07.
- * @see ImportHandler
+ * @see TrimWhereHandler
  * @since v2.1.0
  */
 public class WhereHandler implements FenixHandler {
@@ -32,12 +32,8 @@ public void buildSqlInfo(BuildSource source) {
         // 说明后续的动态条件的 SQL 语句中都要判断是否要前置添加 WHERE 关键字，并去除掉 WHERE 后面的 AND 或者 OR 关键字.
         // 在各个动态标签或文本标签中，如果处理了 WHERE 标签的情况之后，就再将 prependWhere 设置为 false 即可.
         SqlInfo sqlInfo = source.getSqlInfo();
-        String oldSql = sqlInfo.getJoin().toString();
         sqlInfo.setPrependWhere(true);
         FenixXmlBuilder.buildSqlInfo(source.getNamespace(), sqlInfo, source.getNode(), source.getContext());
-        if (oldSql.equals(sqlInfo.getJoin().toString())) {
-            sqlInfo.setPrependWhere(false);
-        }
     }
 
 }