Merge pull request #3 from blinkfox/master

Master
blinkfox · Aug 12, 2020 · 323de1c · 323de1c
2 parents 11fdb47 + c391e0b
commit 323de1c
Show file tree

Hide file tree

Showing 219 changed files with 12,657 additions and 1,110 deletions.
diff --git a/README.md b/README.md
diff --git a/blinkfox-checks.xml b/blinkfox-checks.xml
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,3 +1,34 @@
+## v2.3.5 修复了在老版本 JPA 中某些情况下的 bug (2020-07-31)
+
+- 修复了在老版本 JPA 中，某些情况下出现 Javaassist 的 `ClassNotFoundException` 的问题；
+
+## v2.3.4 升级了相关依赖包的版本 (2020-07-26)
+
+- 升级了相关依赖包的版本，如：`dom4j`、`mvel` 等；
+
+## v2.3.3 修复多线程下同一个接口方法的线程安全问题（强烈推荐升级） (2020-07-03)
+
+- 修复了在多线程情况下执行同一个 `repository` 接口方法时，可能出现参数混淆的线程安全问题；
+
+## v2.3.2 修复某些情况下 JDBC 连接未释放的问题（强烈推荐升级） (2020-05-28)
+
+- 修复了在异步多线程情况下，返回自定义实体 Bean 类型时，JDBC 连接未释放的问题，老版本可以使用 `@Transactional` 注解解决；
+
+## v2.3.1 兼容支持最新 v2.3.0 版本的 Spring Data JPA (2020-05-18)
+
+- 支持最新的 Spring Data JPA 版本(`v2.3.0`)，同时也能兼容之前的 Spring Data JPA 版本；
+
+## v2.3.0 新增了基于 JPQL 方式时自定义命名参数名称的相关 API 和属性 (2020-05-09)
+
+- 新增了基于 JPQL 的 XML 方式中的多个 XML 标签中，可以自定义命名参数名称的 `name` 属性；
+- 新增了基于 JPQL 的 Java API 方式中可以自定义命名参数名称的 `name` 参数相关的 API 方法；
+
+## v2.2.0 新增了基于 Specification 的动态注解和 Java 链式 API (2020-02-02)
+
+- 新增了基于 `Specification` 的动态条件注解来动态查询数据；
+- 新增了基于 `Specification` 的 Java 链式 API 来动态查询数据；
+- 新增了 `@EnableFenix` 注解来配置 JPA 可以使用 Fenix 的相关 API；
+
 ## v2.1.0 新增 <where> 标签和对应的 Java API (2019-11-21)
 
 - 新增了 `<where>` 标签和动态 `where` 的 Java API，用来消除在全动态 SQL 中场景中，`WHERE` 关键字后的 `AND` 或者 `OR` 关键字；

diff --git a/docs/README.md b/docs/README.md
@@ -1,30 +1,37 @@
 # Fenix
 
-> [Fenix](https://github.com/blinkfox/fenix)（菲尼克斯）是一个为了解决复杂动态 SQL (`JPQL`) 而生的 `Spring Data JPA` 扩展库，目的是辅助开发者更方便快捷的书写复杂、动态且易于维护的 SQL，支持 `XML` 和 Java 链式 `API` 两种方式来书写动态 SQL。
+> [Fenix](https://github.com/blinkfox/fenix)（菲尼克斯）是一个为了解决复杂动态 SQL (`JPQL`) 而生的 `Spring Data JPA` 扩展库，目的是辅助开发者更方便快捷的书写复杂、动态且易于维护的 SQL，支持 `XML`、Java 链式 `API` 和动态条件注解等四种方式来书写动态 SQL。
+
+- [示例项目 (fenix-example)](https://github.com/blinkfox/fenix-example)
 
 ## 特性
 
-- 简单、轻量级、无副作用的集成和使用，jar 包仅 `86 KB`；
+- 简单、轻量级、无副作用的集成和使用，jar 包仅 `177 KB`；
 - 作为 JPA 的扩展和增强，兼容 Spring Data JPA 原有功能和各种特性；
-- 提供了 `XML` 和纯 Java API 两种方式来书写 SQL；
+- 提供了 `XML`、Java 链式 `API` 和动态条件注解等四种方式来书写动态 SQL；
 - `XML` 的方式功能强大，让 SQL 和 Java 代码解耦，易于维护；
-- 也可以采用 Java 链式 `API` 来书写动态 SQL；
-- 具有动态性、极致的可复用性和可调试性的优点；
+- 可以采用 Java 链式 `API` 来书写动态 SQL；
+- 可以采用动态条件注解和Java 链式 `API` 来书写出动态的 `Specification`。
+- 具有动态性、极致的可复用性的优点；
 - SQL 执行结果可返回任意自定义的实体对象，比使用 JPA 自身的投影方式更加简单和自然；
-- 具有可扩展性，可自定义 `XML` 语义标签和对应的标签处理器来生成自定义逻辑的 SQL 片段和参数；
+- 具有可扩展性，如：可自定义 `XML` 语义标签和对应的标签处理器来生成自定义逻辑的 SQL 片段和参数；
 
 ## 初衷
 
-随着 [Spring Data JPA](https://spring.io/projects/spring-data-jpa) 越来越流行，极大的方便了数据的“增删改”和简单查询的场景，但是在复杂、动态查询方面就显得有些“糟糕”了，相比 `MyBatis` 的 `XML` 动态 SQL 而言，缺少了一定优雅和可维护性。
+随着 [Spring Data JPA](https://spring.io/projects/spring-data-jpa) 越来越流行，极大的方便了数据的“增删改”和简单查询的场景，但是在复杂、动态查询方面就显得有些“糟糕”了，相比 `MyBatis` 的 `XML` 动态 SQL 而言，缺少了一定优雅和可维护性，而使用原生的 `Specification` 又显得过于“臃肿”。
 
 所有，为了能使开发人员能像在 `MyBatis` 中那样在 `XML` 中书写 `JPQL` 语句，Fenix 中引入了 [MVEL](http://mvel.documentnode.com/) 表达式和模板引擎的语法来书写和渲染 XML 中的动态 SQL。通俗的说，就是支持使用表达式、`if/else`、`foreach` 等来达到跟 MyBatis 类似的动态 SQL 能力。但是，仅靠这些“灵活”的动态能力，仍然会书写出大量相似或重复的 SQL。
 
 因此，为了更加极致的解决 SQL 片段“**相似或重复**”的问题，Fenix 中引入了 SQL 片段的“**语义化标签**”，将大多数常见的 SQL 片段做成 `XML` 标签，通过传递的字段动态的参数值就可以生成对应的 SQL 片段和命名参数。语言化的 XML 标签可以在各个需要的地方复用，也可以自定义自己的 XML SQL 标签。
 
-为了便于开发人员书写一般中短长度的动态 SQL，Fenix 还提供了 Java 链式 `API` 书写动态 SQL 的方式，使 SQL 可读性和紧凑性更好，如果要书写静态或动态的中、长 SQL，则推荐使用 `XML` 方式，便于集中阅读、调试和维护 SQL。
+同时，Fenix 还提供了 Java 链式 `API` 书写动态 SQL 和动态 `Specification` 的方式，使 SQL 可读性和紧凑性更好。还可以使用动态条件注解将查询条件的实体 Bean 中标记对应的查询条件注解，而获得动态的查询能力。如果要书写静态或动态的中、长 SQL，则推荐使用 `XML` 方式，便于集中阅读、调试和维护 SQL。
 
 > **注**：本 `Fenix` 扩展库开发的核心思想来源于我几年前写的动态 SQL 拼接库 [Zealot](https://github.com/blinkfox/zealot)。如果你熟悉星际争霸的话，大概能理解其中的关系。
 
 ## 开源许可证
 
 本 `Fenix` 的 Spring Data JPA 扩展库遵守 [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0) 许可证。
+
+## 鸣谢
+
+感谢 [JetBrains 公司](https://www.jetbrains.com/?from=fenix) 为本开源项目提供的免费正版 Intellij IDEA 的 License 支持。
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -1,13 +1,13 @@
 ![logo](assets/images/logo.png)
 
-# Fenix <small>2.1.0</small>
+# Fenix <small>2.3.5</small>
 
 > 为解决复杂动态 SQL 而生的 Spring Data JPA 扩展库
 
-- 简单、可扩展、轻量级  (~86 KB jar)
+- 简单、可扩展、轻量级 (~177 KB jar)
 - 可返回任意自定义的实体对象
 - 比 MyBatis 更加强大的动态 SQL 能力
-- 支持 XML 文件和 Java 链式 API 两种方式书写 SQL
+- 支持 XML 文件、Java 链式 API、动态注解等四种方式书写动态 SQL
 
 [GitHub](https://github.com/blinkfox/fenix/)
 [开始阅读](README)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,15 +1,23 @@
 - 快速入门
   - [简介](README)
-  - [与 MyBatis 的 SQL 写法比较](compare-mybatis)
+  - [与 MyBatis 的 XML 的 SQL 写法比较](compare-mybatis)
   - [快速集成](quick-install)
   - [快速开始](quick-start)
+  - [四种使用方式示例](usage-example)
   - [@QueryFenix 注解](queryfenix-introduction)
-- XML方式
+- 基于 JPQL(或SQL) 的 XML 方式
   - [逻辑控制语法](xml/logic-control)
   - [SQL 语义化标签](xml/xml-tags)
   - [自定义标签](xml/custom-tag)
-- Java方式
+- 基于 JPQL(或SQL) 的 Java API 方式
   - [总体示例](java/example)
   - [API 方法](java/main-method)
+- 基于 Specification 的 Java API 方式
+  - [总体示例](sp-api/example)
+  - [API 方法](sp-api/main-method)
+- 基于 Specification 的 Java Bean 注解方式
+  - [使用介绍](sp-bean/introduction)
+  - [内置条件注解](sp-bean/annotations)
+  - [自定义条件注解](sp-bean/custom-annotation)
 - [更多功能](more-features)
 - [版本更新记录](CHANGELOG)
diff --git a/docs/compare-mybatis.md b/docs/compare-mybatis.md
@@ -1,4 +1,4 @@
-# 与 MyBatis 的 SQL 写法比较
+# 与 MyBatis XML 的 SQL 写法比较
 
 ## 假设业务查询场景
 
@@ -13,7 +13,7 @@
 - **操作结果**：数据库字段类型为 `int` 型，只能下拉选择一个选项值来进行**等值查询**（`=`）；
 - **操作时间**：数据库字段类型为 `datetime` 型，可以选择开始时间或者结束时间来进行**区间查询**（`BETWEEN ? AND ?`、`>=`、`<=`）；
 
-## 使用 MyBatis 的 SQL 写法
+## 使用 MyBatis XML 的 SQL 写法
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -71,7 +71,7 @@
 </mapper>
 ```
 
-## 使用 Fenix 的 SQL 写法
+## 使用 Fenix XML 的 SQL 写法
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
@@ -108,4 +108,4 @@
 - 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 语义化**等方面，都更加强大。
+> 通过以上 MyBatis 和 Fenix 的各自 SQL 写法比较来看，`Fenix` 的 SQL 在**动态性**、**简洁性**和**SQL 语义化**等方面，都更加强大。
diff --git a/docs/index.html b/docs/index.html
@@ -48,7 +48,6 @@
   <script src="//cdn.bootcss.com/prism/1.16.0/components/prism-sql.min.js"></script>
   <script src="//cdn.bootcss.com/prism/1.16.0/components/prism-yaml.min.js"></script>
   <script src="//cdn.bootcss.com/docsify/4.9.4/plugins/search.min.js"></script>
-  <!-- <script src="//cdn.bootcss.com/docsify/4.9.4/plugins/emoji.min.js"></script> -->
   <script src="//cdn.bootcss.com/docsify/4.9.4/plugins/zoom-image.min.js"></script>
 </body>
 </html>
diff --git a/docs/java/main-method.md b/docs/java/main-method.md
@@ -153,21 +153,28 @@ params(Map<String, Object> paramMap)
 ```java
 // 生成等值查询的 SQL 片段
 equal(String field, Object value)
+equal(String field, Object value, String name) // v2.3.0 版本新增，可以自定义命名参数名称.
 equal(String field, Object value, boolean match)
+equal(String field, Object value, String name, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " AND " 前缀等值查询的 SQL 片段.
 andEqual(String field, Object value)
+andEqual(String field, Object value, String name) // v2.3.0 版本新增，可以自定义命名参数名称.
 andEqual(String field, Object value, boolean match)
+andEqual(String field, Object value, String name, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " OR " 前缀等值查询的 SQL 片段.
 orEqual(String field, Object value)
+orEqual(String field, Object value, String name) // v2.3.0 版本新增，可以自定义命名参数名称.
 orEqual(String field, Object value, boolean match)
+orEqual(String field, Object value, String name, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 ```
 
 **方法解释**：
 
 - `equal`、`andEqual`、`orEqual`，分别表示拼接等值查询 SQL 的前缀为 `空字符串`、`AND`、`OR`；
 - `field`，表示数据库字段或实体属性；
+- `name`，表示 JPA 查询条件的命名参数名称，`v2.3.0` 版本新增的参数。如果没有该参数或者参数值为空，将默认使用 `field` 字段来作为命名参数名称；
 - `value`，表示 Java 中的变量或常量值；
 - `match`，表示是否生成该 SQL 片段，值为 `true` 时生成，否则不生成；
 
@@ -199,22 +206,30 @@ orEqual(String field, Object value, boolean match)
 ```java
 // 生成 BETWEEN 区间查询的 SQL 片段，当某一个值为 null 时，会是大于等于或小于等于的情形.
 - between(String field, Object startValue, Object endValue)
+- between(String field, String startName, Object startValue, String endName, Object endValue) // v2.3.0 版本新增，可以自定义命名参数名称.
 - between(String field, Object startValue, Object endValue, boolean match)
+- between(String field, String startName, Object startValue, String endName, Object endValue, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " AND " 前缀的 BETWEEN 区间查询的 SQL 片段，当某一个值为 null 时，会是大于等于或小于等于的情形.
 - andBetween(String field, Object startValue, Object endValue)
+- andBetween(String field, String startName, Object startValue, String endName, Object endValue) // v2.3.0 版本新增，可以自定义命名参数名称.
 - andBetween(String field, Object startValue, Object endValue, boolean match)
+- andBetween(String field, String startName, Object startValue, String endName, Object endValue, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " OR " 前缀的 BETWEEN 区间查询的 SQL 片段，当某一个值为 null 时，会是大于等于或小于等于的情形.
 - orBetween(String field, Object startValue, Object endValue)
+- orBetween(String field, String startName, Object startValue, String endName, Object endValue) // v2.3.0 版本新增，可以自定义命名参数名称.
 - orBetween(String field, Object startValue, Object endValue, boolean match)
+- orBetween(String field, String startName, Object startValue, String endName, Object endValue, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 ```
 
 **方法解释**：
 
 - `between`、`andBetween`、`orBetween`，分别表示拼接区间查询SQL的前缀为 `空字符串`、`AND`、`OR`；
 - `field`，表示数据库字段或实体属性；
+- `startName`，表示 JPA 查询条件开始值的命名参数名称，`v2.3.0` 版本新增的参数。如果没有该参数或者参数值为空，将默认使用 `field` + `_start` 来作为命名参数名称；
 - `startValue`，表示区间查询的开始值；
+- `endName`，表示 JPA 查询条件结束值的命名参数名称，`v2.3.0` 版本新增的参数。如果没有该参数或者参数值为空，将默认使用 `field` + `_end` 来作为命名参数名称；
 - `endValue`，表示区间查询的结束值；
 - `match`，表示是否生成该SQL片段，值为`true`时生成，否则不生成；
 
@@ -261,45 +276,70 @@ assertEquals(3, sqlInfo.getParams().size());
 ```java
 // 生成 IN 范围查询的 SQL 片段.
 in(String field, Object[] values)
+in(String field, String name, Object[] values) // v2.3.0 版本新增，可以自定义命名参数名称.
 in(String field, Collection<?> values)
+in(String field, String name, Collection<?> values) // v2.3.0 版本新增，可以自定义命名参数名称.
 in(String field, Object[] values, boolean match)
+in(String field, String name, Object[] values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 in(String field, Collection<?> values, boolean match)
+in(String field, String name, Collection<?> values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " AND " 前缀的 IN 范围查询的 SQL 片段.
 andIn(String field, Object[] values)
+andIn(String field, String name, Object[] values) // v2.3.0 版本新增，可以自定义命名参数名称.
 andIn(String field, Collection<?> values)
+andIn(String field, String name, Collection<?> values) // v2.3.0 版本新增，可以自定义命名参数名称.
 andIn(String field, Object[] values, boolean match)
+andIn(String field, String name, Object[] values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 andIn(String field, Collection<?> values, boolean match)
+andIn(String field, String name, Collection<?> values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " OR " 前缀的 IN 范围查询的 SQL 片段.
 orIn(String field, Object[] values)
+orIn(String field, String name, Object[] values) // v2.3.0 版本新增，可以自定义命名参数名称.
 orIn(String field, Collection<?> values)
+orIn(String field, String name, Collection<?> values) // v2.3.0 版本新增，可以自定义命名参数名称.
 orIn(String field, Object[] values, boolean match)
+orIn(String field, String name, Object[] values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 orIn(String field, Collection<?> values, boolean match)
+orIn(String field, String name, Collection<?> values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成 " NOT IN " 范围查询的 SQL 片段.
 notIn(String field, Object[] values)
+notIn(String field, String name, Object[] values) // v2.3.0 版本新增，可以自定义命名参数名称.
 notIn(String field, Collection<?> values)
+notIn(String field, String name, Collection<?> values) // v2.3.0 版本新增，可以自定义命名参数名称.
 notIn(String field, Object[] values, boolean match)
+notIn(String field, String name, Object[] values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 notIn(String field, Collection<?> values, boolean match)
+notIn(String field, String name, Collection<?> values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " AND " 前缀的 " NOT IN " 范围查询的 SQL 片段.
 andNotIn(String field, Object[] values)
+andNotIn(String field, String name, Object[] values) // v2.3.0 版本新增，可以自定义命名参数名称.
 andNotIn(String field, Collection<?> values)
+andNotIn(String field, String name, Collection<?> values) // v2.3.0 版本新增，可以自定义命名参数名称.
 andNotIn(String field, Object[] values, boolean match)
+andNotIn(String field, String name, Object[] values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 andNotIn(String field, Collection<?> values, boolean match)
+andNotIn(String field, String name, Collection<?> values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 
 // 生成带 " OR " 前缀的 " NOT IN " 范围查询的 SQL 片段.
 orNotIn(String field, Object[] values)
+orNotIn(String field, String name, Object[] values) // v2.3.0 版本新增，可以自定义命名参数名称.
 orNotIn(String field, Collection<?> values)
+orNotIn(String field, String name, Collection<?> values) // v2.3.0 版本新增，可以自定义命名参数名称.
 orNotIn(String field, Object[] values, boolean match)
+orNotIn(String field, String name, Object[] values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 orNotIn(String field, Collection<?> values, boolean match)
+orNotIn(String field, String name, Collection<?> values, boolean match) // v2.3.0 版本新增，可以自定义命名参数名称.
 ```
 
 **方法解释**：
 
 - `in`、`andIn`、`orIn`，分别表示拼接范围查询SQL的前缀为 `空字符串`、`AND`、`OR`；
 - `field`，表示数据库字段或实体属性；
+- `name`，表示 JPA 查询条件的命名参数名称，`v2.3.0` 版本新增的参数。如果没有该参数或者参数值为空，将默认使用 `field` 字段来作为命名参数名称；
 - `values`，表示范围查询需要的参数的数组或集合；
 - `match`，表示是否生成该SQL片段，值为`true`时生成，否则不生成；