新增和修改了部分文档

blinkfox · Jan 2, 2021 · 897b238 · 897b238
1 parent 060b651
commit 897b238
Show file tree

Hide file tree

Showing 15 changed files with 438 additions and 56 deletions.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -1,77 +1,78 @@
-# 🍹 版本更新记录
+# 🍹 版本更新记录 :id=title
 
-## v2.4.1 计划
+## ⛳ v2.4.1 新增了 debug 模式和 bug 修复 🆕 (2021-01-02) :id=v241
 
-- 新增回了 `debug` 模式;
-- 修复 `<where />` 标签中的一些 bug;（完成）
+- 新增了 `debug` 模式，开启之后，可以在不重启服务的情况下，实时读取和解析 XML 文件中的 SQL；
+- 修复 `<where />` 标签中在混合使用了逻辑控制语法和 XML 标签语法时，去除 `AND` 前缀的一些 bug;
+- 升级了 `mvel` 的依赖到最新小版本；
 
-## 🥊 v2.4.0 增强 JPA 的增删改功能 🆕 (2020-12-09)
+## 🥊 v2.4.0 增强 JPA 的增删改功能 (2020-12-09) :id=v240
 
 - 新增了更快速高效的 JPA 批量“增删改”的支持；
 - 新增了增量更新的功能，即更新时只更新实体类中属性值不为 `null` 的字段；
 - 新增了三种主键 ID 生成策略类；
 - 修改或升级了相关依赖包的版本，如：去除了 `dom4j` 的显示依赖，因为 JPA Hibernate 中已经传递依赖了它；
 
-## 🏓 v2.3.6 小功能改进版本 (2020-08-27)
+## 🏓 v2.3.6 小功能改进版本 (2020-08-27) :id=v236
 
 - 新增了 `@EnableFenix` 注解中更多的配置信息，与 `@EnableJpaRepositories` 注解相对应；
 - 修改了求 `COUNT` 的 SQL 不支持 `DISTINCT` 的问题；
 
-## 🎳 v2.3.5 修复了在老版本 JPA 中某些情况下的 bug (2020-07-31)
+## 🎳 v2.3.5 修复了在老版本 JPA 中某些情况下的 bug (2020-07-31) :id=v235
 
 - 修复了在老版本 JPA 中，某些情况下出现 Javaassist 的 `ClassNotFoundException` 的问题；
 
-## 🥏 v2.3.4 升级了相关依赖包的版本 (2020-07-26)
+## 🥏 v2.3.4 升级了相关依赖包的版本 (2020-07-26) :id=v234
 
 - 升级了相关依赖包的版本，如：`dom4j`、`mvel` 等；
 
-## 🏈 v2.3.3 修复多线程下同一个接口方法的线程安全问题（强烈推荐升级） (2020-07-03)
+## 🏈 v2.3.3 修复多线程下同一个接口方法的线程安全问题（强烈推荐升级） (2020-07-03) :id=v233
 
 - 修复了在多线程情况下执行同一个 `repository` 接口方法时，可能出现参数混淆的线程安全问题；
 
-## 🏀 v2.3.2 修复某些情况下 JDBC 连接未释放的问题（强烈推荐升级） (2020-05-28)
+## 🏀 v2.3.2 修复某些情况下 JDBC 连接未释放的问题（强烈推荐升级） (2020-05-28) :id=v232
 
 - 修复了在异步多线程情况下，返回自定义实体 Bean 类型时，JDBC 连接未释放的问题，老版本可以使用 `@Transactional` 注解解决；
 
-## 🥎 v2.3.1 兼容支持最新 v2.3.0 版本的 Spring Data JPA (2020-05-18)
+## 🥎 v2.3.1 兼容支持最新 v2.3.0 版本的 Spring Data JPA (2020-05-18) :id=v231
 
 - 支持最新的 Spring Data JPA 版本(`v2.3.0`)，同时也能兼容之前的 Spring Data JPA 版本；
 
-## ⚽ v2.3.0 新增了基于 JPQL 方式时自定义命名参数名称的相关 API 和属性 (2020-05-09)
+## ⚽ v2.3.0 新增了基于 JPQL 方式时自定义命名参数名称的相关 API 和属性 (2020-05-09) :id=v230
 
 - 新增了基于 JPQL 的 XML 方式中的多个 XML 标签中，可以自定义命名参数名称的 `name` 属性；
 - 新增了基于 JPQL 的 Java API 方式中可以自定义命名参数名称的 `name` 参数相关的 API 方法；
 
-## ⚾ v2.2.0 新增了基于 Specification 的动态注解和 Java 链式 API (2020-02-02)
+## ⚾ v2.2.0 新增了基于 Specification 的动态注解和 Java 链式 API (2020-02-02) :id=v220
 
 - 新增了基于 `Specification` 的动态条件注解来动态查询数据；
 - 新增了基于 `Specification` 的 Java 链式 API 来动态查询数据；
 - 新增了 `@EnableFenix` 注解来配置 JPA 可以使用 Fenix 的相关 API；
 
-## 🏅 v2.1.0 新增 <where> 标签和对应的 Java API (2019-11-21)
+## 🏅 v2.1.0 新增 <where> 标签和对应的 Java API (2019-11-21) :id=v210
 
 - 新增了 `<where>` 标签和动态 `where` 的 Java API，用来消除在全动态 SQL 中场景中，`WHERE` 关键字后的 `AND` 或者 `OR` 关键字；
 
-## 🏆 v2.0.0 支持 Spring Boot 的 2.2.0.RELEASE 版本 (2019-10-10)
+## 🏆 v2.0.0 支持 Spring Boot 的 2.2.0.RELEASE 版本 (2019-10-10) :id=v200
 
 - 支持 Spring Boot 和 Spring Data JPA 的 `2.2.0.RELEASE`及以上的版本，同时也兼容之前的版本；
 
-## 🎖️ v1.1.1 求分页 count 小调整 (2019-10-10)
+## 🎖️ v1.1.1 求分页 count 小调整 (2019-10-10) :id=v111
 
 - **修改**了默认求总记录数 `count(*)` 时的 SQL 为 `count(*) as count`，即增加了 `as` 列；
 
-## 🎗️ v1.1.0 新增返回任意实体对象或集合 (2019-10-10)
+## 🎗️ v1.1.0 新增返回任意实体对象或集合 (2019-10-10) :id=v110
 
 - **新增**了**返回任意实体对象**或集合的功能，相比使用投影的方式更为简单和自然；
 
-## 🤹‍♂️ v1.0.1 bug 修复及小功能调整 (2019-09-01)
+## 🤹‍♂️ v1.0.1 bug 修复及小功能调整 (2019-09-01) :id=v101
 
 - **新增**了可以使用 `spring.jpa.show-sql` 的配置来作为是否打印 SQL 信息的依据之一；
 - **新增**了部分类的单元测试，提高了单元测试覆盖率；
 - **重构**了 XML 文件的扫描读取机制；
 - **修复**了 Spring Boot web 项目打成 `jar` 包时读取不到 Fenix `XML` 文件的问题；
 - **删除**了 Fenix `debug` 模式的功能；
 
-## 🎪 v1.0.0 第一个里程碑正式版 (2019-08-19)
+## 🎪 v1.0.0 第一个里程碑正式版 (2019-08-19) :id=v100
 
 - **新增**了 `Fenix` JPA 扩展库的核心功能；
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -1,6 +1,6 @@
 ![logo](assets/images/logo.png)
 
-# Fenix <small>2.4.0</small>
+# Fenix <small>2.4.1</small>
 
 > 为解决复杂动态 SQL 而生的 Spring Data JPA 扩展库
 

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -23,5 +23,8 @@
   - [🚀 更高效的【批量增删改】](cud/fast-batch-cud)
   - [🚁 非【null】属性的增量更新](cud/not-null-update)
   - [✈️ 更多的主键 ID 生成策略](cud/id-generator)
-- [🍬 更多功能](more-features)
+- 🍬 更多功能
+  - [🦋 返回自定义的实体对象](more/custom-entity)
+  - [🐛 调试 (debug) 模式](more/debug-mode)
+  - [🐝 其他功能](more/other-features)
 - [🍹 版本更新记录](CHANGELOG)
diff --git a/docs/cud/fast-batch-cud.md b/docs/cud/fast-batch-cud.md
@@ -1,6 +1,6 @@
-# 🚀 更高效的【批量增删改】
+# 🚀 更高效的【批量增删改】 :id=more-efficient-cud
 
-## 💐 一、JPA 中自带的优化配置
+## 💐 一、JPA 中自带的优化配置 :id=jpa-builtin-optimization
 
 在 Spring Data JPA 中批量保存或更新的 `saveAll` 方法性能较低。但是，Spring Data JPA（或者说 `Hibernate`）中也自带了关于批量操作的优化配置，通常默认没有开启，我建议你开启这些配置项。
 
@@ -19,9 +19,9 @@ spring:
           batch_versioned_data: true
 ```
 
-## 🌻 二、Fenix 中【批量增删改】的增强
+## 🌻 二、Fenix 中【批量增删改】的增强 :id=fenix-cud-enhance
 
-### 🍺 1. 如何使用
+### 🍺 1. 如何使用 :id=how-to-use
 
 Fenix 在 `2.4.0` 版本中提供了相比 `saveAll` 更高效的**批量新增**、**批量更新**和**批量删除**的方法。但是，Fenix 中并没有提供类似于 `saveAll` 这种能同时做到批量新增或者更新的方法，而是为了提高效率，对批量新增和批量更新的方法单独进行了实现和优化。这样即能保证对 JPA 的兼容性，又能提高各自处理场景的效率。需要开发人员可以根据自己的业务场景选择对应的方法。
 
@@ -42,7 +42,7 @@ public interface SchoolRepository extends FenixJpaRepository<School, String> {
 }
 ```
 
-### 🥤 2. 批量新增（saveBatch）
+### 🥤 2. 批量新增（saveBatch） :id=save-batch
 
 **批量新增**有两个重载方法：
 
@@ -68,7 +68,7 @@ public void testSaveBatch() {
 }
 ```
 
-### 🍹 3. 批量更新（updateBatch）
+### 🍹 3. 批量更新（updateBatch） :id=update-batch
 
 **批量更新**也有两个重载方法：
 
@@ -94,7 +94,7 @@ public void testUpdateBatch() {
 }
 ```
 
-### 🧃 4. 批量删除（deleteBatchByIds）
+### 🧃 4. 批量删除（deleteBatchByIds） :id=delete-batch
 
 Spring Data JPA 中已经有相关批量删除的方法了，比如：
 

diff --git a/docs/cud/id-generator.md b/docs/cud/id-generator.md
@@ -1,14 +1,14 @@
-# ✈️ 更多的主键 ID 生成策略
+# ✈️ 更多的主键 ID 生成策略 :id=title
 
-## 🆔 一、简介
+## 🆔 一、简介 :id=introduction
 
 Fenix 从 `2.4.0` 版本开始新增了三种主键 `ID` 的生产策略类供你选择和使用，同时也支持你通过 Java API 去调用生成 `ID`：
 
 - **❄️ 雪花算法 ID** (`Long` 长整型)
 - **☃️ 62 进制雪花算法 ID** (`String` 字符串型)
 - **🌟 62 进制 UUID** (`String` 字符串型)
 
-## ❄️ 二、雪花算法的 ID 生成策略
+## ❄️ 二、雪花算法的 ID 生成策略 :id=snowflake
 
 雪花算法 (`snowflake`) 已经是现在使用比较广泛的 ID 生成算法，其避免了 `UUID` 的冗长无序的缺点，生成的 ID 是**整体有序**的**长整型**数据，Fenix 中也默认做了集成和支持。
 
@@ -54,7 +54,7 @@ public class MyEntity {
 }
 ```
 
-## ☃️ 三、62 进制雪花算法的 ID 生成策略
+## ☃️ 三、62 进制雪花算法的 ID 生成策略 :id=snowflake-base62
 
 如果你的 ID 不是长整型（`Long`）的，是字符串类型（`String`）的，为了能缩短雪花算法 ID 字符串的长度，可以将原来长度为 `16` 位的雪花算法 ID 的转换为 `62` 进制，能大幅度缩短 `ID` 的长度为 `9` 位，且依然能保证**唯一性**和**整体有序性**。
 
@@ -110,7 +110,7 @@ String uuid = IdWorker.getUuid();
 String uuid2 = IdWorker.get62RadixUuid();
 ```
 
-## 🌟 四、62 进制 UUID 生成策略
+## 🌟 四、62 进制 UUID 生成策略 :id=uuid-base62
 
 鉴于 `UUID` 本质上是 `16` 进制的字符串，字符串长度为 `32` 位，依然可以通过进制转换，将其转换为 `62` 进制，能大幅度缩短 `UUID` 的字符串长度为 `19` 位，且依然能保证**唯一性**和**无序性**。
 
@@ -156,7 +156,7 @@ public class MyEntity {
 }
 ```
 
-## ☕ 五、通过 Java API 获取 ID
+## ☕ 五、通过 Java API 获取 ID :id=java-api
 
 在 Fenix 中，你也可以通过 Java API 调用生成雪花算法的 ID 或 `UUID`。
 

diff --git a/docs/cud/not-null-update.md b/docs/cud/not-null-update.md
@@ -1,12 +1,12 @@
-# 🚁 非【null】属性的增量更新
+# 🚁 非【null】属性的增量更新 :id=title
 
-## 🍀 一、初衷
+## 🍀 一、初衷 :id=original-intention
 
 在实际业务场景中，更新数据时，从前端得到的对象实体信息数据的参数中，部分信息是不为空，而我们业务上也只想更新这些不为空的字段到数据库中，而不是将空的数据也一起覆盖保存到数据库中，否则就会造成部分字段数据丢失的问题。
 
 Fenix 在 `2.4.0` 版本中增加了这种常见业务操作的功能处理。
 
-## 🍁 二、如何使用
+## 🍁 二、如何使用 :id=how-to-use
 
 首先，你须要让你业务功能的 `Repository` 接口继承自 `FenixJpaRepository` 接口。由于 `FenixJpaRepository` 接口继承自 `JpaRepository` 接口，所以 `FenixJpaRepository` 接口的功能完全兼容你以前所使用的 `JpaRepository` 的接口。
 
@@ -25,16 +25,17 @@ public interface SchoolRepository extends FenixJpaRepository<School, String> {
 }
 ```
 
-### 🍂 三、方法介绍
+### 🍂 三、方法介绍 :id=method-introduction
 
 **非 `null` 属性的增量更新**有两个方法：
 
-- `S saveOrUpdateByNotNullProperties(S entity)`: 新增实体或更新实体类中非 `null` 属性的字段值。本方法保存每条数据时会先查询判断是否存在，再进行插入或者更新。
-- `void saveOrUpdateAllByNotNullProperties(Iterable<S> entities)`: 新增或更新所有实体类中非 `null` 属性的字段值，本方法仅仅是上面方法的 `for` 循环版本，提供了循环处理的功能。
+- 🔹 `S saveOrUpdateByNotNullProperties(S entity)`: 新增实体或更新实体类中非 `null` 属性的字段值。本方法保存每条数据时会先查询判断是否存在，再进行插入或者更新。
+- 🔹 `void saveOrUpdateAllByNotNullProperties(Iterable<S> entities)`: 新增或更新所有实体类中非 `null` 属性的字段值，本方法仅仅是上面方法的 `for` 循环版本，提供了循环处理的功能。
 
-> **💡 注**：
-> 1. 上面两个方法的主要判断处理逻辑为：如果传入的实体主键 `ID` 为空，说明是新增的情况，就插入一条新的数据；如果实体的主键 `ID` 不为空，会先判断是否存在该 `ID` 的数据，如果不存在，也会新增插入一条数据；否则说明是更新的情况，会仅更新保存实体类属性中不为 `null` 值的属性字段到数据库中；
-> 2. 由于实际场景中难以区分空和 `null` 的关系，为了统一处理以及不和一些业务场景产生冲突，Fenix 中约定仅更新字段值不为 `null` 的值，如果实体对象中的属性值是空字符串`""`或者 `0` 等等，那么也认为是不为 `null` 的，视为业务上就是要保存空字符串值或者 `0`。所以，Fenix 中也会将该空字符串的值更新到数据库中。所以，**建议你的实体类中所有属性的类型都是对象包装类型，不要用 Java 中的 8 种原生基础类型**。
+**💡 注意事项**：
+
+- 🔸 上面两个方法的主要判断处理逻辑为：如果传入的实体主键 `ID` 为空，说明是新增的情况，就插入一条新的数据；如果实体的主键 `ID` 不为空，会先判断是否存在该 `ID` 的数据，如果不存在，也会新增插入一条数据；否则说明是更新的情况，会仅更新保存实体类属性中不为 `null` 值的属性字段到数据库中；
+- 🔸 由于实际场景中难以区分空和 `null` 的关系，为了统一处理以及不和一些业务场景产生冲突，Fenix 中约定仅更新字段值不为 `null` 的值，如果实体对象中的属性值是空字符串`""`或者 `0` 等等，那么也认为是不为 `null` 的，视为业务上就是要保存空字符串值或者 `0`。所以，Fenix 中也会将该空字符串的值更新到数据库中。所以，**建议你的实体类中所有属性的类型都是对象包装类型，不要用 Java 中的 8 种原生基础类型**。
 
 简单的使用示例如下：
 

diff --git a/docs/more-features.md b/docs/more-features.md
@@ -153,7 +153,34 @@ public final class BlogSqlInfoProvider {
 List<UserBlogInfo> queryUserBlogsWithFenixJava(@Param("userId") String userId, @Param("title") String title);
 ```
 
-## 🐛 二、从 XML 中获取 SQL 信息
+## 🐛 二、调试 (debug) 模式
+
+从 `2.4.1` 版本开始，新增回了 debug 调试模式的功能，也就是可以在不重启服务的情况下，每一条对 XML SQL 的请求，都会实时从 XML 文件流中读取和解析 SQL 语句。
+
+> **💡 注**：其实该功能在 `1.0.0` 版本中就有，只不过当时的 IDEA 在识别更新的文件时有些问题，导致该功能没有啥效果，所以就去掉了。现在又将此功能加了回来，更加方便开发人员快速、动态的调试 SQL 语句了。
+
+### 📝 1. 开启 debug 模式
+
+如果你是使用的 `fenix-spring-boot-starter`，那么只需要在你的 `application.yml` 或者 `application.properties` 文件中，将 `fenix.debug` 设置为 `true` 即可。
+
+```yaml
+fenix:
+  # v2.4.1 版本新增，表示是否开启 debug 调试模式，默认 false。
+  # 当开启之后，对 XML 中的 SQL 会进行实时文件流的读取和解析，不需要重启服务。切记仅在开发环境中开启此功能.
+  debug: true
+```
+
+如果不是使用的 `fenix-spring-boot-starter`，那么需要在你构造的 `FenixConfig` 实例对象中设置 `setDebug` 为 `true` 即可。
+
+### 🧬 2. IDEA 中开启热更新策略
+
+当然，还需要你开发使用的 IDE 能在服务运行期间动态识别到文件资源的更新，不同的 IDE 工具支持可能有差别。
+
+如果你使用的是 Intellij IDEA，那么可以通过 `Edit Configurations` 编辑应用运行时的更新策略。你可以将 `On 'update' action` 和 `On frame deactivation` 的值设置为：`Update classes and resources`。设置的结果效果图如下：
+
+![IDEA 中的资源更新的设置](https://statics.sh1a.qingstor.com/2021/01/02/idea-update.png)
+
+## 🦗 三、从 XML 中获取 SQL 信息
 
 Fenix 中会自动从 `XML` 中获取到 SQL 信息。如果你想手动从 `XML` 中获取到 SQL 信息（`SqlInfo`），也可以使用 `Fenix.java` 提供的 `API` 来获取。
 
@@ -165,7 +192,7 @@ Fenix.getXmlSqlInfo(String fullFenixId, Object context)
 Fenix.getXmlSqlInfo(String namespace, String fenixId, Object context)
 ```
 
-## 🐜 三、表达式、模版解析器
+## 🐜 四、表达式、模版解析器
 
 在 Fenix 中解析 XML 标签中的表达式或者模版是通过 `Mvel` 表达式语言来实现的，主要方法解析方法是封装在了`ParseHelper.java` 的工具类中，通过该类让开发人员自己测试表达式也是极为方便的。以下作简要介绍。
 
@@ -227,11 +254,11 @@ public void testParseTemplate2() {
 }
 ```
 
-## 🐝 四、上下文参数包装类
+## 🐝 五、上下文参数包装类
 
 Fenix 中提供了一个包装上下文参数为 `HashMap` 的包装器 `ParamWrapper` 工具类，其本质上就是对 `HashMap` 方法的一个**简单链式封装**。
 
-> **注**：提供该包装器类的主要目的是方便开发者封装较多的散参数或者多个 Java 对象为一个 `Map` 型的上下文参数。
+> **💡 注**：提供该包装器类的主要目的是方便开发者封装较多的散参数或者多个 Java 对象为一个 `Map` 型的上下文参数。
 
 ### 🛏️ 1. ParamWrapper主要方法
 
@@ -259,7 +286,7 @@ Map<String, Object> context = ParamWrapper.newInstance("sex", "1").put("stuId",
 
 前后对比来看，再仅仅只需要传入个别自定义参数时，能简化部分代码量和参数传递。
 
-## 🐞 五、表达式的真假判断
+## 🐞 六、表达式的真假判断
 
 Fenix 中关于表达式字符串的真假判断在 `com.blinkfox.fenix.helper.ParseHelper` 类中提供了静态方法。