!220 feat：Active Record 也支持三种关联查询方式

Merge pull request !220 from 王帅/main

docs/zh/base/active-record.md

@@ -137,30 +137,54 @@ Account.create()
     .page(Page.of(1,10));
 ```
 
-## 多表关联
+## 关联查询 <Badge type="tip" text="v1.5.5" />
 
-`Model` 提供了 `joins` 与 `@Relation` 两种方式实现多表关联查询，例如：用户与角色的关系：
+`Model` 提供了三种方式实现多表关联查询，例如：用户与角色的关系：
 
-- 通过 [joins](./relations-query.md#方案-3-join-query) 联表方式查询数据：
+- （默认）通过 [Joins Query](./relations-query.md#方案-3-join-query) 联表方式查询数据：
 
 ```java
 User.create()
     .select(USER.ALL_COLUMNS,ROLE.ALL_COLUMNS)
     .leftJoin(USER_ROLE).as("ur").on(USER_ROLE.USER_ID.eq(USER.USER_ID))
     .leftJoin(ROLE).as("r").on(USER_ROLE.ROLE_ID.eq(ROLE.ROLE_ID))
-    .where(USER.USER_ID.eq(2))
+    .where(USER.USER_ID.eq(1))
     .one();
 ```
-> 更多关于 `left join` 等 join 查询，请请点击 [这里](./relations-query.md#方案-3-join-query);
 
+> 获取更多关于 `Joins Query` 的信息，请点击 [这里](./relations-query.md#方案-3-join-query)
 
-
-- 通过 [@Relation](./relations-query.md#方案-1relations-注解) 相关注解查询数据：
+- 通过 [Relations Query](./relations-query.md#方案-1relations-注解) 的方式查询数据：
 
 ```java
 User.create()
-    .where(USER.USER_ID.eq(2))
-    .oneWithRelations();
+    .where(USER.USER_ID.eq(1))
+    .withRelations() // 使用 Relations Query 的方式进行关联查询。
+    .maxDepth(3) // 设置父子关系查询中，默认的递归查询深度。
+    .ignoreRelations("orderList") // 忽略查询部分 Relations 注解标记的属性。
+    .extraCondition("id",100) // 添加额外的 Relations 查询条件。
+    .one();
 ```
 
-> 以上是用于查询 `一对多`、`多对多` 等场景，更多信息请点击 [这里](./relations-query.md#方案-1-relations-注解);
+> 获取更多关于 `Relations Query` 的信息，请点击 [这里](./relations-query.md#方案-1relations-注解)
+
+- 通过 [Fields Query](./relations-query.md#方案-1relations-注解) 的方式查询数据：
+
+```java
+User.create()
+    .where(USER.USER_ID.eq(1))
+    .withFields() // 使用 Fields Query 的方式进行关联查询。
+    .fieldMapping(User::getRoleList,user-> // 设置属性对应的 QueryWrapper 查询。
+    QueryWrapper.create()
+    .select()
+    .from(ROLE)
+    .where(ROLE.ROLE_ID.in(
+    QueryWrapper.create()
+    .select(USER_ROLE.ROLE_ID)
+    .from(USER_ROLE)
+    .where(USER_ROLE.USER_ID.eq(user.getUserId()))
+    )))
+    .one();
+```
+
+> 获取更多关于 `Fields Query` 的信息，请点击 [这里](./relations-query.md#方案-2field-query)

mybatis-flex-core/src/main/java/com/mybatisflex/core/activerecord/MapperModel.java

@@ -147,22 +147,4 @@ public interface MapperModel<T> {
         return Optional.ofNullable(oneById());
     }
 
-    /**
-     * 根据实体类主键获取一条数据，并查询 {@code @Relation} 注解关联的内容。
-     *
-     * @return 数据
-     */
-    default T oneWithRelationsById() {
-        return baseMapper().selectOneWithRelationsById(pkValues());
-    }
-
-    /**
-     * 根据实体类主键获取一条数据，并查询 {@code @Relation} 注解关联的内容，封装为 {@link Optional} 返回。
-     *
-     * @return 数据
-     */
-    default Optional<T> oneWithRelationsByIdOpt() {
-        return Optional.ofNullable(oneWithRelationsById());
-    }
-
 }

mybatis-flex-core/src/main/java/com/mybatisflex/core/activerecord/Model.java

@@ -16,7 +16,9 @@
 
 package com.mybatisflex.core.activerecord;
 
+import com.mybatisflex.core.activerecord.query.FieldsQuery;
 import com.mybatisflex.core.activerecord.query.QueryModel;
+import com.mybatisflex.core.activerecord.query.RelationsQuery;
 import com.mybatisflex.core.paginate.Page;
 import com.mybatisflex.core.util.SqlUtil;
 
@@ -92,14 +94,16 @@ public abstract class Model<T extends Model<T>>
     }
 
     /**
-     * 根据实体类构建的条件获取一条数据，并查询 {@code @Relation} 注解关联的内容。
+     * 根据实体类构建的条件获取一条数据，返回的数据为 asType 类型。
      *
+     * @param asType 接收数据类型
      * @return 数据
      */
-    public T oneWithRelations() {
-        return baseMapper().selectOneWithRelationsByQuery(queryWrapper().limit(1L));
+    public <R> R oneAs(Class<R> asType) {
+        return baseMapper().selectOneByQueryAs(queryWrapper(), asType);
     }
 
+
     /**
      * 根据实体类构建的条件获取一条数据，并封装为 {@link Optional} 返回。
      *
@@ -110,12 +114,13 @@ public abstract class Model<T extends Model<T>>
     }
 
     /**
-     * 根据实体类构建的条件获取一条数据，并查询 {@code @Relation} 注解关联的内容，封装为 {@link Optional} 返回。
+     * 根据实体类构建的条件获取一条数据，返回的数据为 asType 类型，并封装为 {@link Optional} 返回。
      *
+     * @param asType 接收数据类型
      * @return 数据
      */
-    public Optional<T> oneWithRelationsOpt() {
-        return Optional.ofNullable(oneWithRelations());
+    public <R> Optional<R> oneAsOpt(Class<R> asType) {
+        return Optional.ofNullable(oneAs(asType));
     }
 
     /**
@@ -128,12 +133,13 @@ public abstract class Model<T extends Model<T>>
     }
 
     /**
-     * 根据实体类构建的条件获取多条数据，并查询 {@code @Relation} 注解关联的内容。
+     * 根据实体类构建的条件获取多条数据，返回的数据为 asType 类型。
      *
+     * @param asType 接收数据类型
      * @return 数据列表
      */
-    public List<T> listWithRelations() {
-        return baseMapper().selectListWithRelationsByQuery(queryWrapper());
+    public <R> List<R> listAs(Class<R> asType) {
+        return baseMapper().selectListByQueryAs(queryWrapper(), asType);
     }
 
     /**
@@ -147,13 +153,32 @@ public abstract class Model<T extends Model<T>>
     }
 
     /**
-     * 根据实体类构建的条件获取分页数据，并查询 {@code @Relation} 注解关联的内容。
+     * 根据实体类构建的条件获取分页数据，返回的数据为 asType 类型。
      *
-     * @param page 分页对象
+     * @param page   分页对象
+     * @param asType 接收数据类型
      * @return 分页数据
      */
-    public Page<T> pageWithRelations(Page<T> page) {
-        return baseMapper().paginateWithRelations(page, queryWrapper());
+    public <R> Page<R> pageAs(Page<R> page, Class<R> asType) {
+        return baseMapper().paginateAs(page, queryWrapper(), asType);
+    }
+
+    /**
+     * 使用 {@code Fields Query} 的方式进行关联查询。
+     *
+     * @return {@code Fields Query} 查询
+     */
+    public FieldsQuery<T> withFields() {
+        return new FieldsQuery<>(this);
+    }
+
+    /**
+     * 使用 {@code Relations Query} 的方式进行关联查询。
+     *
+     * @return {@code Relations Query} 查询
+     */
+    public RelationsQuery<T> withRelations() {
+        return new RelationsQuery<>(this);
     }
 
 }

mybatis-flex-core/src/main/java/com/mybatisflex/core/activerecord/query/AbstractQuery.java

@@ -0,0 +1,160 @@
+/*
+ *  Copyright (c) 2022-2023, Mybatis-Flex (fuhai999@gmail.com).
+ *  <p>
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *  <p>
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *  <p>
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.mybatisflex.core.activerecord.query;
+
+import com.mybatisflex.core.BaseMapper;
+import com.mybatisflex.core.activerecord.Model;
+import com.mybatisflex.core.paginate.Page;
+import com.mybatisflex.core.query.QueryWrapper;
+
+import java.util.List;
+import java.util.Optional;
+
+/**
+ * 抽象关联查询。
+ *
+ * @author 王帅
+ * @since 2023-07-30
+ */
+public abstract class AbstractQuery<T extends Model<T>> {
+
+    protected final Model<T> model;
+
+    protected AbstractQuery(Model<T> model) {
+        this.model = model;
+    }
+
+    /**
+     * @return 主键
+     */
+    protected Object[] pkValues() {
+        return model.pkValues();
+    }
+
+    /**
+     * @return BaseMapper
+     */
+    protected BaseMapper<T> baseMapper() {
+        return model.baseMapper();
+    }
+
+    /**
+     * @return QueryWrapper
+     */
+    protected QueryWrapper queryWrapper() {
+        return model.queryWrapper();
+    }
+
+    /**
+     * 根据实体类主键获取一条数据。
+     *
+     * @return 数据
+     */
+    public abstract T oneById();
+
+    /**
+     * 根据实体类主键获取一条数据，并封装为 {@link Optional} 返回。
+     *
+     * @return 数据
+     */
+    public Optional<T> oneByIdOpt() {
+        return Optional.ofNullable(oneById());
+    }
+
+    /**
+     * 根据实体类主键获取一条数据。
+     *
+     * @return 数据
+     */
+    public abstract <R> R oneByIdAs(Class<R> asType);
+
+    /**
+     * 根据实体类主键获取一条数据，并封装为 {@link Optional} 返回。
+     *
+     * @return 数据
+     */
+    public <R> Optional<R> oneByIdAsOpt(Class<R> asType) {
+        return Optional.ofNullable(oneByIdAs(asType));
+    }
+
+    /**
+     * 根据实体类构建的条件获取一条数据。
+     *
+     * @return 数据
+     */
+    public abstract T one();
+
+    /**
+     * 根据实体类构建的条件获取一条数据，返回的数据为 asType 类型。
+     *
+     * @param asType 接收数据类型
+     * @return 数据
+     */
+    public abstract <R> R oneAs(Class<R> asType);
+
+    /**
+     * 根据实体类构建的条件获取一条数据，并封装为 {@link Optional} 返回。
+     *
+     * @return 数据
+     */
+    public Optional<T> oneOpt() {
+        return Optional.ofNullable(one());
+    }
+
+    /**
+     * 根据实体类构建的条件获取一条数据，返回的数据为 asType 类型，并封装为 {@link Optional} 返回。
+     *
+     * @param asType 接收数据类型
+     * @return 数据
+     */
+    public <R> Optional<R> oneOptAs(Class<R> asType) {
+        return Optional.ofNullable(oneAs(asType));
+    }
+
+    /**
+     * 根据实体类构建的条件获取多条数据。
+     *
+     * @return 数据列表
+     */
+    public abstract List<T> list();
+
+    /**
+     * 根据实体类构建的条件获取多条数据，返回的数据为 asType 类型。
+     *
+     * @param asType 接收数据类型
+     * @return 数据列表
+     */
+    public abstract <R> List<R> listAs(Class<R> asType);
+
+    /**
+     * 根据实体类构建的条件获取分页数据。
+     *
+     * @param page 分页对象
+     * @return 分页数据
+     */
+    public abstract Page<T> page(Page<T> page);
+
+    /**
+     * 根据实体类构建的条件获取分页数据，返回的数据为 asType 类型。
+     *
+     * @param page   分页对象
+     * @param asType 接收数据类型
+     * @return 分页数据
+     */
+    public abstract <R> Page<R> pageAs(Page<R> page, Class<R> asType);
+
+}

mybatis-flex-core/src/main/java/com/mybatisflex/core/activerecord/query/FieldsQuery.java

@@ -0,0 +1,169 @@
+/*
+ *  Copyright (c) 2022-2023, Mybatis-Flex (fuhai999@gmail.com).
+ *  <p>
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *  <p>
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *  <p>
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.mybatisflex.core.activerecord.query;
+
+import com.mybatisflex.core.activerecord.Model;
+import com.mybatisflex.core.field.FieldQuery;
+import com.mybatisflex.core.field.FieldQueryManager;
+import com.mybatisflex.core.field.QueryBuilder;
+import com.mybatisflex.core.mybatis.MappedStatementTypes;
+import com.mybatisflex.core.paginate.Page;
+import com.mybatisflex.core.util.FieldWrapper;
+import com.mybatisflex.core.util.LambdaGetter;
+import com.mybatisflex.core.util.LambdaUtil;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 使用 {@code Fields Query} 的方式进行关联查询。
+ *
+ * @author 王帅
+ * @since 2023-07-30
+ */
+public class FieldsQuery<T extends Model<T>> extends AbstractQuery<T> {
+
+    private final Map<String, FieldQuery> fieldQueryMap;
+
+    public FieldsQuery(Model<T> model) {
+        super(model);
+        this.fieldQueryMap = new HashMap<>();
+    }
+
+    /**
+     * 设置属性对应的 {@code QueryWrapper} 查询。
+     *
+     * @param field   属性
+     * @param builder {@code QueryWrapper} 构建
+     * @param <F>     属性类型
+     * @return 属性查询构建
+     */
+    public <F> FieldsQuery<T> fieldMapping(LambdaGetter<F> field, QueryBuilder<F> builder) {
+        return fieldMapping(field, false, builder);
+    }
+
+    /**
+     * 设置属性对应的 {@code QueryWrapper} 查询。
+     *
+     * @param field   属性
+     * @param prevent 阻止对嵌套类属性的查询
+     * @param builder {@code QueryWrapper} 构建
+     * @param <F>     属性类型
+     * @return 属性查询构建
+     */
+    public <F> FieldsQuery<T> fieldMapping(LambdaGetter<F> field, boolean prevent, QueryBuilder<F> builder) {
+        String fieldName = LambdaUtil.getFieldName(field);
+        Class<?> entityClass = LambdaUtil.getImplClass(field);
+        FieldQuery fieldQuery = new FieldQuery();
+        fieldQuery.setPrevent(prevent);
+        fieldQuery.setFieldName(fieldName);
+        fieldQuery.setQueryBuilder(builder);
+        fieldQuery.setEntityClass(entityClass);
+        fieldQuery.setFieldWrapper(FieldWrapper.of(entityClass, fieldName));
+        this.fieldQueryMap.put(entityClass.getName() + '#' + fieldName, fieldQuery);
+        return this;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public T oneById() {
+        List<T> entities = Collections.singletonList(baseMapper().selectOneById(pkValues()));
+        FieldQueryManager.queryFields(baseMapper(), entities, fieldQueryMap);
+        return entities.get(0);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    @SuppressWarnings("unchecked")
+    public <R> R oneByIdAs(Class<R> asType) {
+        try {
+            MappedStatementTypes.setCurrentType(asType);
+            List<R> entities = Collections.singletonList((R) baseMapper().selectOneById(pkValues()));
+            FieldQueryManager.queryFields(baseMapper(), entities, fieldQueryMap);
+            return entities.get(0);
+        } finally {
+            MappedStatementTypes.clear();
+        }
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public T one() {
+        List<T> entities = Collections.singletonList(baseMapper().selectOneByQuery(queryWrapper()));
+        FieldQueryManager.queryFields(baseMapper(), entities, fieldQueryMap);
+        return entities.get(0);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public <R> R oneAs(Class<R> asType) {
+        List<R> entities = Collections.singletonList(baseMapper().selectOneByQueryAs(queryWrapper(), asType));
+        FieldQueryManager.queryFields(baseMapper(), entities, fieldQueryMap);
+        return entities.get(0);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public List<T> list() {
+        List<T> entities = baseMapper().selectListByQuery(queryWrapper());
+        FieldQueryManager.queryFields(baseMapper(), entities, fieldQueryMap);
+        return entities;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public <R> List<R> listAs(Class<R> asType) {
+        List<R> entities = baseMapper().selectListByQueryAs(queryWrapper(), asType);
+        FieldQueryManager.queryFields(baseMapper(), entities, fieldQueryMap);
+        return entities;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public Page<T> page(Page<T> page) {
+        baseMapper().paginate(page, queryWrapper());
+        FieldQueryManager.queryFields(baseMapper(), page.getRecords(), fieldQueryMap);
+        return page;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public <R> Page<R> pageAs(Page<R> page, Class<R> asType) {
+        baseMapper().paginateAs(page, queryWrapper(), asType);
+        FieldQueryManager.queryFields(baseMapper(), page.getRecords(), fieldQueryMap);
+        return page;
+    }
+
+}

mybatis-flex-core/src/main/java/com/mybatisflex/core/activerecord/query/RelationsQuery.java

@@ -0,0 +1,129 @@
+/*
+ *  Copyright (c) 2022-2023, Mybatis-Flex (fuhai999@gmail.com).
+ *  <p>
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *  <p>
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *  <p>
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+
+package com.mybatisflex.core.activerecord.query;
+
+import com.mybatisflex.core.activerecord.Model;
+import com.mybatisflex.core.paginate.Page;
+import com.mybatisflex.core.relation.RelationManager;
+
+import java.util.List;
+
+/**
+ * 使用 {@code Relations Query} 的方式进行关联查询。
+ *
+ * @author 王帅
+ * @since 2023-07-30
+ */
+public class RelationsQuery<T extends Model<T>> extends AbstractQuery<T> {
+
+    public RelationsQuery(Model<T> model) {
+        super(model);
+    }
+
+    /**
+     * 忽略查询部分 {@code Relations} 注解标记的属性。
+     *
+     * @param fields 属性
+     * @return {@code Relations} 查询构建
+     */
+    public RelationsQuery<T> ignoreRelations(String... fields) {
+        RelationManager.addIgnoreRelations(fields);
+        return this;
+    }
+
+    /**
+     * 设置父子关系查询中，默认的递归查询深度。
+     *
+     * @param maxDepth 查询深度
+     * @return {@code Relations} 查询构建
+     */
+    public RelationsQuery<T> maxDepth(int maxDepth) {
+        RelationManager.setMaxDepth(maxDepth);
+        return this;
+    }
+
+    /**
+     * 添加额外的 {@code Relations} 查询条件。
+     *
+     * @param key   键
+     * @param value 值
+     * @return {@code Relations} 查询构建
+     */
+    public RelationsQuery<T> extraConditionParam(String key, Object value) {
+        RelationManager.addExtraConditionParam(key, value);
+        return this;
+    }
+
+    @Override
+    public T oneById() {
+        return baseMapper().selectOneWithRelationsById(pkValues());
+    }
+
+    @Override
+    public <R> R oneByIdAs(Class<R> asType) {
+        return baseMapper().selectOneWithRelationsByIdAs(pkValues(), asType);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public T one() {
+        return baseMapper().selectOneWithRelationsByQuery(queryWrapper());
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public <R> R oneAs(Class<R> asType) {
+        return baseMapper().selectOneWithRelationsByQueryAs(queryWrapper(), asType);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public List<T> list() {
+        return baseMapper().selectListWithRelationsByQuery(queryWrapper());
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public <R> List<R> listAs(Class<R> asType) {
+        return baseMapper().selectListWithRelationsByQueryAs(queryWrapper(), asType);
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public Page<T> page(Page<T> page) {
+        return baseMapper().paginateWithRelations(page, queryWrapper());
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public <R> Page<R> pageAs(Page<R> page, Class<R> asType) {
+        return baseMapper().paginateWithRelationsAs(page, queryWrapper(), asType);
+    }
+
+}

mybatis-flex-core/src/main/java/com/mybatisflex/core/relation/RelationManager.java

@@ -99,7 +99,7 @@ public class RelationManager {
         extraConditionParams.set(params);
     }
 
-    public static void addExtraConditionParam(String key, String value) {
+    public static void addExtraConditionParam(String key, Object value) {
         Map<String, Object> params = extraConditionParams.get();
         if (params == null) {
             params = new HashMap<>();

mybatis-flex-test/mybatis-flex-spring-boot-test/src/test/java/com/mybatisflex/test/mapper/ActiveRecordTest.java

@@ -119,9 +119,41 @@ class ActiveRecordTest {
 
         User user2 = User.create()
             .where(USER.USER_ID.eq(2))
-            .oneWithRelations();
+            .withRelations()
+            .one();
 
         Assertions.assertEquals(user1.toString(), user2.toString());
     }
 
+    @Test
+    void testRelationsQuery() {
+        User.create()
+            .where(USER.USER_ID.ge(1))
+            .withRelations() // 使用 Relations Query 的方式进行关联查询。
+            .maxDepth(3) // 设置父子关系查询中，默认的递归查询深度。
+            .ignoreRelations("orderList") // 忽略查询部分 Relations 注解标记的属性。
+            .extraCondition("id", 100) // 添加额外的 Relations 查询条件。
+            .list()
+            .forEach(System.out::println);
+    }
+
+    @Test
+    void testFieldsQuery() {
+        User.create()
+            .where(USER.USER_ID.ge(1))
+            .withFields() // 使用 Fields Query 的方式进行关联查询。
+            .fieldMapping(User::getRoleList, user -> // 设置属性对应的 QueryWrapper 查询。
+                QueryWrapper.create()
+                    .select()
+                    .from(ROLE)
+                    .where(ROLE.ROLE_ID.in(
+                        QueryWrapper.create()
+                            .select(USER_ROLE.ROLE_ID)
+                            .from(USER_ROLE)
+                            .where(USER_ROLE.USER_ID.eq(user.getUserId()))
+                    )))
+            .list()
+            .forEach(System.out::println);
+    }
+
 }