Update 注解部分的结构

Author: abel533

.vuepress/config.js

@@ -89,12 +89,20 @@ module.exports = {
                                 'v2.x/2.7.logicalmapper.md',
                             ]
                         },
-                        'v2.x/3.entity.md',
+                        {
+                            title: '3. 实体类注解',
+                            sidebarDepth: 3,
+                            children: [
+                                'v2.x/3.1.entity.md',
+                                'v2.x/3.2.jpa.md',
+                                'v2.x/3.3.jakarta-jpa.md',
+                                'v2.x/3.4.custom.md',
+                            ]
+                        },
                         'v2.x/4.common.md',
                         'v2.x/5.service.md',
                         'v2.x/6.activerecord.md',
                         'v2.x/7.generator.md',
-                        'v2.x/8.jpa.md'
                     ]
                 },{
                     title: 'v1.x 使用指南',

docs/v2.x/3.entity.md renamed to docs/v2.x/3.1.entity.md

@@ -1,10 +1,10 @@
 ---
-title: 3. 实体类注解
+title: 3.1. 默认注解
 ---
 
 这部分属于 **mybatis-mapper/provider** 核心部分提供的基础注解，可以直接配合 mapper 使用。
 
-## 3.1 注解方法介绍
+## 3.1.1 注解方法介绍
 
 注解提供了大量的配置属性，详细介绍看代码注释：
 
@@ -133,7 +133,7 @@ public @interface Entity {
 }
 ```
 
-## 3.2 `@Entity.Table` 注解
+## 3.1.2 `@Entity.Table` 注解
 
 这个注解除了可以设置表名外，还有下面几个属性：
 
@@ -162,7 +162,7 @@ public class User {
 }
 ```
 
-## 3.3 `@Entity.Column` 注解
+## 3.1.3 `@Entity.Column` 注解
 
 列的注解包含了大量的属性，这些属性涉及到了查询列、插入列、更新列，以及所有可能出现在 `<result>` 和 `#{}` 中的参数。
 这些参数的含义直接看代码注释。

docs/v2.x/8.jpa.md renamed to docs/v2.x/3.2.jpa.md

@@ -1,8 +1,8 @@
 ---
-title: 8. JPA 注解支持
+title: 3.2. JPA 注解
 ---
 
-## 8.1 注解介绍
+## 3.2.1 注解介绍
 
 对 JPA 注解的支持非常有限，仅支持以下注解的部分属性：
 - `@Table`: 用于实体类，必须指定该注解，否则不会被识别为实体类
@@ -24,7 +24,7 @@ title: 8. JPA 注解支持
 
 除了 JPA 这几个注解外，还支持 `@Entity.Table` 和 `@Entity.Column` 注解，这些注解可以混用，相同含义的配置中，JPA优先级更高。
 
-## 8.2 JPA 示例
+## 3.2.2 JPA 示例
 
 ```java
 @Table(name = "user")
@@ -41,9 +41,9 @@ public class User {
 }
 ```
 
-## 8.3 扩展实现
+## 3.2.3 扩展实现
 
-### 8.3.1 查找实体类类型
+### 3.2.3.1 查找实体类类型
 
 首先通过 `JpaEntityClassFinder` 支持添加了 `javax.persistence.Table` 注解的实体类。
 
@@ -62,7 +62,7 @@ public class JpaEntityClassFinder extends GenericEntityClassFinder {
 }
 ```
 
-### 8.3.2 构建 EntityTable 信息
+### 3.2.3.2 构建 EntityTable 信息
 
 然后通过 `JpaEntityTableFactory` 读取 `javax.persistence.Table` 注解的配置信息。
 
@@ -97,7 +97,7 @@ public class JpaEntityTableFactory implements EntityTableFactory {
 
 如果返回了 `EntityTable`，就用 `javax.persistence.Table` 注解的配置覆盖 `EntityTable` 的配置，也就是 JPA 注解优先级高于默认的 `@Entity.Table` 注解。
 
-### 8.3.3 构建 EntityColumn 信息
+### 3.2.3.3 构建 EntityColumn 信息
 
 最后通过 `JpaEntityColumnFactory` 构建 `EntityColumn` 信息，这部分逻辑和上面类似，仍然支持 `@Entity.Column` 注解，而且 JPA 的优先级更高。
 

docs/v2.x/3.3.jakarta-jpa.md

@@ -0,0 +1,132 @@
+---
+title: 3.3. Jakarta JPA 注解
+---
+
+## 3.3.1 注解介绍
+
+对 JPA 注解的支持非常有限，仅支持以下注解的部分属性：
+- `@Table`: 用于实体类，必须指定该注解，否则不会被识别为实体类
+  - name: 设置表名
+    
+- `@Column`: 设置字段的列信息
+  - name: 列名
+  - insertable: 是否可插入
+  - updatable: 是否可更新
+  - scale: 小数位数
+
+- `@Id`: 主键标记
+
+- `@Transient`: 排除字段，没有标记该字段的所有字段都会作为表字段处理
+
+- `@OrderBy`: 设置字段排序，空值时为 `ASC`，除此之外，值只能为 `ASC` 或 `DESC`
+
+>除了上面提到的有限支持外，其他的 JPA 注解都不支持，如果有好的建议或者应用场景，可以提交 issue 或者 PR 增加额外的支持。
+
+除了 JPA 这几个注解外，还支持 `@Entity.Table` 和 `@Entity.Column` 注解，这些注解可以混用，相同含义的配置中，JPA优先级更高。
+
+## 3.3.2 JPA 示例
+
+```java
+@Table(name = "user")
+public class User {
+  @Id
+  @Column
+  private Long   id;
+  @Column(name = "name")
+  private String username;
+  @Column
+  @Entity.Column(selectable = false)
+  private String sex;
+  //忽略其他
+}
+```
+
+## 3.3.3 扩展实现
+
+### 3.3.3.1 查找实体类类型
+
+首先通过 `JpaEntityClassFinder` 支持添加了 `javax.persistence.Table` 注解的实体类。
+
+```java
+public class JpaEntityClassFinder extends GenericEntityClassFinder {
+
+  @Override
+  public boolean isEntityClass(Class<?> clazz) {
+    return clazz.isAnnotationPresent(Table.class);
+  }
+
+  @Override
+  public int getOrder() {
+    return super.getOrder() + 100;
+  }
+}
+```
+
+### 3.3.3.2 构建 EntityTable 信息
+
+然后通过 `JpaEntityTableFactory` 读取 `javax.persistence.Table` 注解的配置信息。
+
+```java
+public class JpaEntityTableFactory implements EntityTableFactory {
+
+  @Override
+  public EntityTable createEntityTable(Class<?> entityClass, Chain chain) {
+    EntityTable entityTable = chain.createEntityTable(entityClass);
+    if (entityClass.isAnnotationPresent(Table.class)) {
+      Table table = entityClass.getAnnotation(Table.class);
+      if(entityTable == null) {
+        entityTable = EntityTable.of(entityClass);
+      }
+      if (!table.name().isEmpty()) {
+        entityTable.table(table.name());
+      }
+    }
+    return entityTable;
+  }
+
+  @Override
+  public int getOrder() {
+    return EntityTableFactory.super.getOrder() + 100;
+  }
+
+}
+```
+在实现中先执行了 `chain.createEntityTable` 调用工厂链的后续方法创建 `EntityTable`，因此 JPA 注解实现支持和 `@Entity.Table` 注解混用。
+
+如果 `chain` 方法没有返回 `EntityTable`，就根据 `javax.persistence.Table` 注解创建。
+
+如果返回了 `EntityTable`，就用 `javax.persistence.Table` 注解的配置覆盖 `EntityTable` 的配置，也就是 JPA 注解优先级高于默认的 `@Entity.Table` 注解。
+
+### 3.3.3.3 构建 EntityColumn 信息
+
+最后通过 `JpaEntityColumnFactory` 构建 `EntityColumn` 信息，这部分逻辑和上面类似，仍然支持 `@Entity.Column` 注解，而且 JPA 的优先级更高。
+
+```java
+public class JpaEntityColumnFactory implements EntityColumnFactory {
+
+  @Override
+  public Optional<List<EntityColumn>> createEntityColumn(EntityTable entityTable, EntityField field, Chain chain) {
+    //代码太长，省略
+  }
+
+  @Override
+  public int getOrder() {
+    return EntityColumnFactory.super.getOrder() + 100;
+  }
+
+}
+```
+
+在上面具体代码的实现中，会先判断 `@Transient` 注解，只要标记了该注解就会忽略。
+
+然后是读取 JPA 中的 `@Column` 注解，支持下面的属性：
+- name: 列名
+- insertable: 是否可插入
+- updatable: 是否可更新
+- scale: 小数位数
+
+还支持 JPA 的 `@Id` 设置主键字段。
+
+支持 `@OrderBy` 设置字段的排序，这里有一定的限制，不能指定多个字段，只能为空（默认 `ASC`)或者为 `ASC` 或 `DESC`。
+
+除了上面提到的有限支持外，其他的 JPA 注解都不支持，如果有好的建议或者应用场景，可以提交 issue 或者 PR 增加额外的支持。

docs/v2.x/3.4.custom.md

@@ -0,0 +1,25 @@
+---
+title: 3.4. 自定义注解扩展
+---
+
+## 3.4 扩展介绍
+
+对 JPA 注解的支持非常有限，仅支持以下注解的部分属性：
+- `@Table`: 用于实体类，必须指定该注解，否则不会被识别为实体类
+  - name: 设置表名
+    
+- `@Column`: 设置字段的列信息
+  - name: 列名
+  - insertable: 是否可插入
+  - updatable: 是否可更新
+  - scale: 小数位数
+
+- `@Id`: 主键标记
+
+- `@Transient`: 排除字段，没有标记该字段的所有字段都会作为表字段处理
+
+- `@OrderBy`: 设置字段排序，空值时为 `ASC`，除此之外，值只能为 `ASC` 或 `DESC`
+
+>除了上面提到的有限支持外，其他的 JPA 注解都不支持，如果有好的建议或者应用场景，可以提交 issue 或者 PR 增加额外的支持。
+
+除了 JPA 这几个注解外，还支持 `@Entity.Table` 和 `@Entity.Column` 注解，这些注解可以混用，相同含义的配置中，JPA优先级更高。