高级检索

一、简介

1.1 概述

在HZERO平台中，提供了复杂的高级检索功能，能够支持用户在页面操作上自定义查询的条件和比较值，以及自定义排序等。

注意：高级检索功能依赖HZERO的高级检索插件，需要在平台服务添加高级检索插件（默认是依赖的，如果不需要可以手动在依赖中排除）。

• OP

<dependency>
    <groupId>org.hzero.plugin</groupId>
    <artifactId>platform-search</artifactId>
</dependency>

• SAAS

<dependency>
    <groupId>org.hzero.plugin</groupId>
    <artifactId>platform-search-saas</artifactId>
</dependency>

1.2 高级检索客户端组件坐标

<dependency>
    <groupId>org.hzero.boot</groupId>
    <artifactId>hzero-boot-platform</artifactId>
    <version>${hzero.boot.version}</version>
</dependency>

1.3 使用说明

• 高级检索前端展示样式

用户可以自定义查询规则然后保存起来，在列表中选择定义好的查询规则，可以重复使用，自定义规则也允许编辑复制和删除。

在列表中选择任一检索定义，会在右侧展示查询按钮和选项。

在列表中点击X可以取消所有检索条件。

• 高级检索配置定义页面

在顶部是检索的配置名称和描述，默认标记只允许一个检索配置拥有，并且默认的检索配置会在列表的第一个展示。

排序表格是定义当前检索的排序方式，可以自定义选择排序字段和排序方向。

查询表格用来自定义检索条件和比较方式，点击外层查询旁边的“高级检索”会策划出查询条件的输入框。

条件表格用于定义默认的检索条件比较方式以及比较值。

注意：如果同时定义了“条件”和“查询”，并且在外层的高级搜索中录入了比较值，最终的结果是所有条件的交集，也就是所有条件同时生效。

二、使用说明

2.1 后端使用

• 在平台服务中添加高级检索插件的依赖。
• 在需要使用高级检索的服务中添加高级检索客户端的依赖。
• 在需要支持高级检索的接口中添加高级检索参数。

@Permission(...)
@GetMapping
public ResponseEntity<Page<Order>> searchTest(
        SearchRequest searchRequest,
        @SortDefault(Order.FIELD_ORDER_ID) PageRequest pageRequest) {
    ...
}

• 高级检索插件仅支持自定义的查询，也就是说要自行编写mapper中的接口和在xml中添加实现SQL，高级检索参数作为查询参数传递到xml参数中，在这之前，需要处理一下这个参数：

  • 单表查询：handleEntity的主要目的是处理字段类型，防止java类型与数据库类型不能自动映射，如果不执行handleEntity方法，所有的值都以字符串来处理。

    SearchStatement.builder(searchRequest)
                   .handleEntity(Entity.class)
                   .builder();
    

  • 多表查询：handleEntity除了自动处理数据类型之外，还会自动处理字段的表别名

    SearchStatement.builder(searchRequest)
                   .handleEntity("tableAbbr1", Entity1.class)
                   .handleEntity("tableAbbr2", Entity2.class)
                   .builder();
    

  • SearchStatementBuilder其他方法：

    • handleTableAbbr(fieldName, tableAbbr)：定义字段对应的表别名
    • handleColumn(fieldName, column)：定义字段映射的列名称
    • handleType(fieldName, type)：定义字段的java类型

  • 字段与java值转换

    • 默认支持的java类型有：Byte、Short、Integer、Long、Float、Double、Character、String、Boolean、Date和LocalDate.
    • 如果需要添加额外的java类型处理或者覆盖默认处理方式，可以使用SearchValueProcessor.setProcessor(type, valueFunction)来添加或者覆盖处理方式。

• mapper中的定义：SearchStatement.builder(...).build()方法返回一个SearchStatement对象

List<Order> search(SearchStatement searchStatment);

• XML文件编写：

  • 判断是否包含自定义的查询条件：如果在mapper接口中为SearchStatement对象添加了@Param注解，需要在调用对象之前添加别名前缀

    <if test="criterionList != null and criterionList.size() > 0">
        ...
    </if>
    

  • 循环遍历拼接条件：这一段格式基本固定，如果你有需要可以自行调整

    <foreach collection="criterionList" item="criterion">
        <choose>
            <when test="criterion.noValue">
                ${criterion.andOr} ${criterion.condition}
            </when>
            <when test="criterion.singleValue">
                ${criterion.andOr} ${criterion.condition} #{criterion.value}
            </when>
            <when test="criterion.betweenValue">
                ${criterion.andOr} (${criterion.condition} #{criterion.value} and #{criterion.secondValue})
            </when>
            <when test="criterion.listValue">
                ${criterion.andOr} ${criterion.condition}
                <foreach close=")" collection="criterion.value" item="listItem" open="(" separator=",">
                    #{listItem}
                </foreach>
            </when>
        </choose>
    </foreach>
    

  • 判断是否包含自定义的排序条件：

    <if test="orderByList != null and orderByList.size() > 0">
       ...
    </if>
    

  • 循环遍历拼接排序：

    ORDER BY
    <foreach collection="orderByList" item="orderBy" separator=",">
        ${orderBy.columnName} ${orderBy.direction}
    </foreach>
    

  • 一个简单的XML完整示例：

    <select id="search" resultType="org.hzero.demo.domain.entity.Order">
        SELECT
            *
        FROM demo_order
        <where>
            <if test="criterionList != null and criterionList.size() > 0">
                <foreach collection="criterionList" item="criterion">
                    <choose>
                        <when test="criterion.noValue">
                            ${criterion.andOr} ${criterion.condition}
                        </when>
                        <when test="criterion.singleValue">
                            ${criterion.andOr} ${criterion.condition} #{criterion.value}
                        </when>
                        <when test="criterion.betweenValue">
                            ${criterion.andOr} (${criterion.condition} #{criterion.value} and #{criterion.secondValue})
                        </when>
                        <when test="criterion.listValue">
                            ${criterion.andOr} ${criterion.condition}
                            <foreach close=")" collection="criterion.value" item="listItem" open="(" separator=",">
                                #{listItem}
                            </foreach>
                        </when>
                    </choose>
                </foreach>
            </if>
        </where>
        <if test="orderByList != null and orderByList.size() > 0">
            ORDER BY
            <foreach collection="orderByList" item="orderBy" separator=",">
                ${orderBy.columnName} ${orderBy.direction}
            </foreach>
        </if>
    </select>