ebatisElasticsearch ORM 框架

ebatis 是一个简单方便上手的 Elasticsearch ORM 框架。

ebatis 基于 Java High Level REST Client 开发，采用和 MyBatis 类似思想，只需要定义接口，便可访问Elasticsearch，隔离业务对Elasticserach底层接口的直接访问。如此以来，数据访问的时候，不需要自己手动去构建DSL语句，同时，当升级Elastisearch版本的时候，只需要升级ebatis到相应的版本即可，业务可以完全不用关心底层Elasticsearch驱动接口的变动，平滑升级，并且在搜索时，以ORM的形式与思想构建我们的条件，极大的提升开发效率，下面我们用简单的例子先快速入门ebatis。

创建索引

PUT /recent_order_index

{
  "settings": {
    "number_of_replicas": 0,
    "number_of_shards": 1
  },
  "mappings": {
    "properties": {
      "cargoId": {
        "type": "long"
      },
      "driverUserName": {
        "type": "keyword"
      },
      "loadAddress": {
        "type": "text"
      },
      "searchable": {
        "type": "boolean"
      },
      "companyId": {
        "type": "long"
      }
    }
  }
}

增加测试数据
POST /recent_order_index/_bulk

{"index":{}}
{"cargoId": 1, "driverUserName":"张三", "loadAddress": "南京市玄武区", "searchable": true,"companyId": 666}
{"index":{}}
{"cargoId": 2, "driverUserName":"李四", "loadAddress": "南京市秦淮区", "searchable": false,"companyId": 667}
{"index":{}}
{"cargoId": 3, "driverUserName":"王五", "loadAddress": "南京市六合区", "searchable": true,"companyId": 668}
{"index":{}}
{"cargoId": 4, "driverUserName":"赵六", "loadAddress": "南京市建邺区", "searchable": true,"companyId": 669}
{"index":{}}
{"cargoId": 5, "driverUserName":"钱七", "loadAddress": "南京市鼓楼区", "searchable": true,"companyId": 665}

POM依赖（目前也支持6.5.1.1.RELEASE）

<dependency>
     <groupId>io.manbang</groupId>
     <artifactId>ebatis-core</artifactId>
     <version>7.5.1.3.RELEASE</version>
</dependency>

创建集群连接

@AutoService(ClusterRouterProvider.class)
public class SampleClusterRouterProvider implements ClusterRouterProvider {
    public static final String SAMPLE_CLUSTER_NAME = "sampleCluster";
 
    @Override
    public ClusterRouter getClusterRouter(String name) {
        if (SAMPLE_CLUSTER_NAME.equalsIgnoreCase(name)) {
            Cluster cluster = Cluster.simple("127.0.0.1", 9200, Credentials.basic("admin", "123456"));
            ClusterRouter clusterRouter = ClusterRouter.single(cluster);
            return clusterRouter;
        } else {
            return null;
        }
    }
}

定义POJO对象

@Data
public class RecentOrder {
    private Long cargoId
    private String driverUserName;
    private String loadAddress;
    private Boolean searchable;
    private Integer companyId;
}
 
@Data
public class RecentOrderCondition {
    private Boolean searchable;
     
    private String driverUserName;
}

定义Mapper接口

@Mapper(indices = "recent_order_index")
public interface RecentOrderRepository {
    @Search
    List<RecentOrder> search(RecentOrderCondition condition);
}

测试接口

@Slf4j
public class OrderRepositoryTest {
 
    @Test
    public void search() {
        // 组装查询条件
        RecentOrderCondition condition = new RecentOrderCondition();
        condition.setSearchable(Boolean.TRUE);
        condition.setDriverUserName("张三");
 
        // 映射接口
        RecentOrderRepository repository = MapperProxyFactory.getMapperProxy(RecentOrderRepository.class, SampleClusterRouterProvider.SAMPLE_CLUSTER_NAME);
 
        // 搜索货源
        List<RecentOrder> orders = repository.search(condition);
 
        // 断言
        Assert.assertEquals(3, orders.size());
 
        // 打印输出
        orders.forEach(order -> log.info("{}", order));
    }
}

ebatis版本使用xx.xx.xx.xx.RELEASE表示，前三位代表Elasticsearch适配集群的驱动版本，后一位代表ebatis在此版本上的迭代。例如7.5.1.3.RELEASE表示ebatis在Elasticsearch 7.5.1版本上迭代的第三次版本。

其他Client的对比

目前，主流操作Elasticsearch 的四种驱动方式

下面，我们用满帮车货匹配一个默认排序场景来比较一下，看看不同的驱动方式，如何进行复杂搜索操作。搜索DSL语句如下：

{
  "query": {
    "bool": {
      "must": [
        {
          "bool": {
            "must": [
              {
                "bool": {
                  "should": [
                    {
                      "terms": {
                        "startDistrictId": [
                          684214,
                          981362
                        ],
                        "boost": 1.0
                      }
                    },
                    {
                      "terms": {
                        "startCityId": [
                          320705,
                          931125
                        ],
                        "boost": 1.0
                      }
                    }
                  ],
                  "adjust_pure_negative": true,
                  "boost": 1.0
                }
              },
              {
                "bool": {
                  "should": [
                    {
                      "terms": {
                        "endDistrictId": [
                          95312,
                          931125
                        ],
                        "boost": 1.0
                      }
                    },
                    {
                      "terms": {
                        "endCityId": [
                          589421,
                          953652
                        ],
                        "boost": 1.0
                      }
                    }
                  ],
                  "adjust_pure_negative": true,
                  "boost": 1.0
                }
              }
            ],
            "adjust_pure_negative": true,
            "boost": 1.0
          }
        },
        {
          "range": {
            "updateTime": {
              "from": 1608285822239,
              "to": null,
              "include_lower": true,
              "include_upper": true,
              "boost": 1.0
            }
          }
        },
        {
          "terms": {
            "cargoLabels": [
              "水果",
              "生鲜"
            ],
            "boost": 1.0
          }
        }
      ],
      "must_not": [
        {
          "terms": {
            "cargoCategory": [
              "A",
              "B"
            ],
            "boost": 1.0
          }
        },
        {
          "term": {
            "featureSort": {
              "value": "好货",
              "boost": 1.0
            }
          }
        }
      ],
      "should": [
        {
          "bool": {
            "must_not": [
              {
                "terms": {
                  "cargoChannel": [
                    "长途货源",
                    "一口价货源"
                  ],
                  "boost": 1.0
                }
              }
            ],
            "should": [
              {
                "bool": {
                  "must": [
                    {
                      "term": {
                        "searchableSources": {
                          "value": "ALL",
                          "boost": 1.0
                        }
                      }
                    },
                    {
                      "bool": {
                        "must": [
                          {
                            "terms": {
                              "cargoChannel": [
                                "No.1",
                                "No.2",
                                "No.3"
                              ],
                              "boost": 1.0
                            }
                          },
                          {
                            "term": {
                              "securityTran": {
                                "value": "平台保证",
                                "boost": 1.0
                              }
                            }
                          }
                        ],
                        "adjust_pure_negative": true,
                        "boost": 1.0
                      }
                    }
                  ],
                  "adjust_pure_negative": true,
                  "boost": 1.0
                }
              }
            ],
            "adjust_pure_negative": true,
            "boost": 1.0
          }
        }
      ],
      "adjust_pure_negative": true,
      "boost": 1.0
    }
  },
  "_source": {
    "includes": [
      "cargoId",
      "startDistrictId",
      "startCityId",
      "endDistrictId",
      "endCityId",
      "updateTime",
      "cargoLabels",
      "cargoCategory",
      "featureSort",
      "cargoChannel",
      "searchableSources",
      "securityTran"
    ],
    "excludes": []
  },
  "sort": [
    {
      "duplicate": {
        "order": "asc"
      }
    },
    {
      "_script": {
        "script": {
          "source": "searchCargo-script",
          "lang": "painless",
          "params": {
            "searchColdCargoTop": 0
          }
        },
        "type": "string",
        "order": "asc"
      }
    }
  ]
}

直接使用原生Java High Level REST Client接口方式：

final BoolQueryBuilder queryBuilder = QueryBuilders.boolQuery();
final TermsQueryBuilder startCityId = QueryBuilders.termsQuery("startCityId", Lists.newArrayList(320705L, 931125L));
final TermsQueryBuilder startDistrictId = QueryBuilders.termsQuery("startDistrictId", Lists.newArrayList(684214L, 981362L));
final TermsQueryBuilder endCityId = QueryBuilders.termsQuery("endCityId", Lists.newArrayList(589421L, 953652L));
final TermsQueryBuilder endDistrictId = QueryBuilders.termsQuery("endDistrictId", Lists.newArrayList(95312L, 931125L));
final BoolQueryBuilder startBuilder = QueryBuilders.boolQuery();
startBuilder.should(startCityId).should(startDistrictId);
final BoolQueryBuilder endBuilder = QueryBuilders.boolQuery();
endBuilder.should(endCityId).should(endDistrictId);
final BoolQueryBuilder cityBuilder = QueryBuilders.boolQuery();
cityBuilder.must(startBuilder);
cityBuilder.must(endBuilder);
queryBuilder.must(cityBuilder);
final RangeQueryBuilder rangeBuilder = QueryBuilders.rangeQuery("updateTime");
queryBuilder.must(rangeBuilder.from(1608285822239L));
final TermsQueryBuilder cargoLabelsBuilder = QueryBuilders.termsQuery("cargoLabels", Lists.newArrayList("水果", "生鲜"));
queryBuilder.must(cargoLabelsBuilder);
final TermsQueryBuilder cargoCategoryBuilder = QueryBuilders.termsQuery("cargoCategory", Lists.newArrayList("A", "B"));
final TermQueryBuilder featureSortBuilder = QueryBuilders.termQuery("featureSort", "好货");
queryBuilder.mustNot(cargoCategoryBuilder);
queryBuilder.mustNot(featureSortBuilder);
final BoolQueryBuilder cargoChannelBuilder = QueryBuilders.boolQuery();
queryBuilder.should(cargoChannelBuilder);
final TermsQueryBuilder channelBuilder = QueryBuilders.termsQuery("cargoChannel", Lists.newArrayList("长途货源", "一口价货源"));
cargoChannelBuilder.mustNot(channelBuilder);
final BoolQueryBuilder searchableSourcesBuilder = QueryBuilders.boolQuery();
cargoChannelBuilder.should(searchableSourcesBuilder);
final TermQueryBuilder sourceBuilder = QueryBuilders.termQuery("searchableSources", "ALL");
searchableSourcesBuilder.must(sourceBuilder);
final BoolQueryBuilder securityTranBuilder = QueryBuilders.boolQuery();
searchableSourcesBuilder.must(securityTranBuilder);
securityTranBuilder.must(QueryBuilders.termsQuery("cargoChannel", "No.1", "No.2", "No.3"));
securityTranBuilder.must(QueryBuilders.termQuery("securityTran", "平台保证"));
SearchSourceBuilder searchSource = new SearchSourceBuilder();
searchSource.query(queryBuilder);
searchSource.fetchSource(new String[]{"cargoId", "startDistrictId", "startCityId", "endDistrictId", "endCityId", "updateTime", "cargoLabels",
                "cargoCategory", "featureSort", "cargoChannel", "searchableSources", "securityTran"},
        new String[0]);
searchSource.sort("duplicate", SortOrder.ASC);
ScriptSortBuilder sortBuilder = SortBuilders.scriptSort(new org.elasticsearch.script.Script(ScriptType.INLINE,
        "painless", "searchCargo-script", Collections.emptyMap(), Collections.singletonMap("searchColdCargoTop", 0)),
        ScriptSortBuilder.ScriptSortType.STRING).order(SortOrder.ASC);
searchSource.sort(sortBuilder);

使用Spring Data Elasticsearch方式：

@Repository
interface CargoRepository extends ElasticsearchRepository<Cargo, String> {
    @Query("{\"match\": {\"name\": {\"query\": \"?0\.............."}}}")
    List<Cargo> findByCargoCondition(List<String> startCity, List<String> StartDistrictId /*,...*/);
}
final List<Cargo> cargos=cargoRepository.findByCargoCondition(Lists.newArrayList(320705L, 931125L),Lists.newArrayList(684214L, 981362L).........);

因为@Query需要将整个DSL语句填入，篇幅有限而且长度过长，所以省略展示 。
ebatis

// 1. 创建搜货条件POJO对象
@Data
public class CargoCondition implements SortProvider {
    @Must
    private City city;
    @Must
    private Range<Long> updateTime;
    @Must(queryType = QueryType.TERMS)
    private List<String> cargoLabels;
    @Must
    private Boolean searchable;
    @Must
    private CargoLines cargoLines;
    @Should
    private CargoChannel cargoChannel;
    @MustNot(queryType = QueryType.TERMS)
    private List<String> cargoCategory;
    @MustNot
    private String featureSort;
    private static final Sort[] SORTS = new Sort[]{Sort.fieldAsc("duplicate"),
            Sort.scriptStringAsc(Script.inline("searchCargo-script", Collections.singletonMap("searchColdCargoTop", 0)))};
    @Override
    public Sort[] getSorts() {
        return SORTS;
    }
    @Data
    public static class City {
        @Must
        private StartCity startCity;
        @Must
        private EndCity endCity;
    }
    @Data
    public static class StartCity {
        @Should(queryType = QueryType.TERMS)
        private List<Long> startDistrictId;
        @Should(queryType = QueryType.TERMS)
        private List<Long> startCityId;
    }
    @Data
    public static class EndCity {
        @Should(queryType = QueryType.TERMS)
        private List<Long> endDistrictId;
        @Should(queryType = QueryType.TERMS)
        private List<Long> endCityId;
    }
    @Data
    public static class CargoChannel {
        @MustNot(queryType = QueryType.TERMS)
        private List<String> cargoChannel;
        @Should
        private Security security;
    }
    @Data
    public static class Security {
        @Must
        private String searchableSources;
        @Must
        private SecurityChannel securityChannel;
    }
    @Data
    public static class SecurityChannel {
        @Must(queryType = QueryType.TERMS)
        private List<String> cargoChannel;
        @Must
        private String securityTran;
    }
    @Data
    public static class CargoLines {
        @Must(queryType = QueryType.TERMS)
        private List<String> cargoLines;
        @Must
        private CargoLabel cargoLabel;
    }
    @Data
    public static class CargoLabel {
        @Must(queryType = QueryType.TERMS)
        private List<String> cargoLines;
        @Must(queryType = QueryType.TERMS)
        private List<String> cargoLabels;
    }
}
// 2. 创建搜索接口
@Mapper(indices = "cargo")
public interface CargoMapper {
    @Search
    List<Cargo> searchCargo(CargoCondition condition);
}
 // 3. 拼装搜获条件
final CargoCondition cargo = new CargoCondition();
CargoCondition cargo = new CargoCondition();
final CargoCondition.City city = new CargoCondition.City();
cargo.setCity(city);
final CargoCondition.StartCity startCity = new CargoCondition.StartCity();
city.setStartCity(startCity);
startCity.setStartCityId(Lists.newArrayList(320705L,931125L));
startCity.setStartDistrictId(Lists.newArrayList(684214L,981362L));
final CargoCondition.EndCity endCity = new CargoCondition.EndCity();
city.setEndCity(endCity);
endCity.setEndCityId(Lists.newArrayList(589421L,953652L));
endCity.setEndDistrictId(Lists.newArrayList(95312L,931125L));
cargo.setUpdateTime(Range.ge(System.currentTimeMillis()));
cargo.setCargoLabels(Lists.newArrayList("水果","生鲜"));
final CargoCondition.CargoChannel cargoChannel = new CargoCondition.CargoChannel();
cargo.setCargoChannel(cargoChannel);
cargoChannel.setCargoChannel(Lists.newArrayList("长途货源","一口价货源"));
final CargoCondition.Security security = new CargoCondition.Security();
cargoChannel.setSecurity(security);
security.setSearchableSources("ALL");
final CargoCondition.SecurityChannel securityChannel = new CargoCondition.SecurityChannel();
security.setSecurityChannel(securityChannel);
securityChannel.setCargoChannel(Lists.newArrayList("No.1","No.2","No.3"));
securityChannel.setSecurityTran("平台保证");
cargo.setCargoCategory(Lists.newArrayList("A","B"));
cargo.setFeatureSort("好货");
// 4. 执行搜索
final List<Cargo> cargos = cargoMapper.searchCargo(condition);

从以上对比可以看出ebatis与Spring Data Elasticsearch相对原生Client构建搜索条件要方便很多，实际应用中，在复杂搜索场景条件多变的情况下，如果使用Spring Data Elasticsearch构建条件，在条件复杂场景下，需要自己构建原始DSL语句，例如：@Query("{"match": {"name": {"query": "?0.............."}}}")，在复杂场景下条件的构建会非常复杂且难以直观的定位。
使用ebatis最大的优点在于可以直观的以ORM形式构建我们的搜索条件，以面向对象的思想面对我们复杂的搜索场景，无论是条件的构建还是问题的定位，都相比Java High Level REST Clien和Spring Data Elasticsearch方便的多。

还有，搜索条件总是在变的，要调整的话，如果是原生接口和Spring，需要你不断的调整语句，甚至修改接口，但是ebatis，只需要你正常的修改一个POJO对象的属性，非常的高效。

ebatis进阶使用

执行类图

RequestExecutor：请求执行器，负责整个Elasticsearch请求的执行流程。

RequestFactory：求工厂接口，根据请求的方法定义和实参，创建ES请求。

Cluster：集群，负责Elasticsearch集群请求。

ResponseExtractor：响应提取器，提取Elasticsearch响应，构造返回体。

Interceptor：拦截器，负责ebatis调用过程的拦截。

Cluster

Cluster代表一个ES集群实例，ebatis内建了两个实现：SimpleCluster，FixWeightedCluster和SimpleFederalCluster。 SimpleCluster和FixedWeightedCluster的区别在于，后者是带固定权值的值，在对集群做负载均衡的时候，可以通过权值来控制负载的比例。SimpleFederalCluster的特殊地方在于，在一批集群上做批量操作，同步一批集群，一般用于一批集群数据的增删改，不适用于查。

ClusterRouter

ClusterRouter用于路由出一个可以访问Cluster，内部是通过负载均衡器ClusterLoadBalancer，来同一组集群中，选中一个集群的。根据不同的负载均衡器，ebatis内建了多个对应的路由器，默认提供的有随机负载均衡器，轮询负载均衡器，单集群均衡器，权重负载均衡器，当然也可以通过ebatis提供的接口，定制自己的策略均衡器。

接口定义支持的请求类型及响应类型

Entity指具体的实体类型

以上是目前支持的搜索类型，其他的请求类型还需后续的迭代支持。

异步支持

Mapper搜索方法支持异步操作，只需要将Mapper接口返回结果定义为CompletableFuture>，这样异步的调用不会阻塞并且立刻返回，业务方可以继续处理自己的业务逻辑，在需要获取结果时，提取结果。

拦截器

ebatis中拦截器的加载通过SPI方式实现，只需要提供的目标类实现io.manbang.ebatis.core.interceptor.Interceptor接口，并且在/META-INF/services目录下提供io.manbang.ebatis.core.interceptor.Interceptor文件，内容为提供的目标类的全限定名。也可以在目标类上加上注解@AutoService(Interceptor.class)，由auto-service替我们生成。拦截器的不同接口在请求的整个生命周期的不同阶段调用，可以自定符合自己业务逻辑的拦截器。

@Slf4j
@AutoService(Interceptor.class)
public class TestInterceptor implements Interceptor {
    @Override
    public int getOrder() {
        return 0;
    }
 
    @Override
    public void handleException(Throwable throwable) {
        log.error("Exception", throwable);
    }
 
    @Override
    public void preRequest(Object[] args) {
       ...
       //通过ContextHolder可以跨上下文获取绑定的值
       String userId = ContextHolder.getString("userId");
    }
 
    @Override
    public <T extends ActionRequest> void postRequest(RequestInfo<T> requestInfo) {
        ...
    }
 
    @Override
    public <T extends ActionRequest> void preResponse(PreResponseInfo<T> preResponseInfo) {
        ...
    }
 
    @Override
    public <T extends ActionRequest, R extends ActionResponse> void postResponse(PostResponseInfo<T, R> postResponseInfo) {
        ...
    }
}

与spring的集成，首先增加POM依赖

<dependency>
     <groupId>io.manbang</groupId>
     <artifactId>ebatis-spring</artifactId>
     <version>7.5.1.3.RELEASE</version>
</dependency>

增加Config

@Configuration
@EnableEasyMapper(basePackages = "io.manbang.ebatis.sample.mapper")
public class EbatisConfig {
    @Bean(destroyMethod = "close")
    public ClusterRouter clusterRouter() {
        Cluster cluster = Cluster.simple("127.0.0.1", 9200, Credentials.basic("admin", "123456"));
        ClusterRouter clusterRouter = ClusterRouter.single(cluster);
        return clusterRouter;
    }
}