Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/chaokunyang/jkes

A search framework and multi-tenant search platform based on java, kafka, kafka connect, elasticsearch
https://github.com/chaokunyang/jkes

elasticsearch java kafka kafka-connector odm rest-api search

Last synced: about 3 hours ago
JSON representation

A search framework and multi-tenant search platform based on java, kafka, kafka connect, elasticsearch

Awesome Lists containing this project

README 

        
# Jkes

Jkes是一个基于Java、Kafka、ElasticSearch的搜索框架。Jkes提供了注解驱动的JPA风格的对象/文档映射，使用rest api用于文档搜索。



## 安装

可以参考[`jkes-integration-test`](https://github.com/chaokunyang/jkes/tree/master/jkes-integration-test)项目快速掌握jkes框架的使用方法。[`jkes-integration-test`](https://github.com/chaokunyang/jkes/tree/master/jkes-integration-test)是我们用来测试功能完整性的一个Spring Boot Application。



- 安装`jkes-index-connector`和`jkes-delete-connector`到Kafka Connect类路径

- 安装 Smart Chinese Analysis Plugin

```shell

sudo bin/elasticsearch-plugin install analysis-smartcn

```



## 配置

- 引入jkes-spring-data-jpa依赖

- 添加配置

```java

@EnableAspectJAutoProxy

@EnableJkes

@Configuration

public class JkesConfig {



  @Bean

  public PlatformTransactionManager transactionManager(EntityManagerFactory factory, EventSupport eventSupport) {



    return new SearchPlatformTransactionManager(new JpaTransactionManager(factory), eventSupport);

  }

}

```

- 提供JkesProperties Bean

```java

@Component

@Configuration

public class JkesConf extends DefaultJkesPropertiesImpl {



    @PostConstruct

    public void setUp() {

        Config.setJkesProperties(this);

    }



    @Override

    public String getKafkaBootstrapServers() {

        return "k1-test.com:9292,k2-test.com:9292,k3-test.com:9292";

    }



    @Override

    public String getKafkaConnectServers() {

        return "http://k1-test.com:8084,http://k2-test.com:8084,http://k3-test.com:8084";

    }



    @Override

    public String getEsBootstrapServers() {

        return "http://es1-test.com:9200,http://es2-test.com:9200,http://es3-test.com:9200";

    }



    @Override

    public String getDocumentBasePackage() {

        return "com.timeyang.jkes.integration_test.domain";

    }



    @Override

    public String getClientId() {

        return "integration_test";

    }



}

```

这里可以很灵活，如果使用Spring Boot，可以使用`@ConfigurationProperties`提供配置



- 增加索引管理端点

因为我们不知道客户端使用的哪种web技术，所以索引端点需要在客户端添加。比如在`Spring MVC`中，可以按照如下方式添加索引端点

```java

@RestController

@RequestMapping("/api/search")

public class SearchEndpoint {



    private Indexer indexer;



    @Autowired

    public SearchEndpoint(Indexer indexer) {

        this.indexer = indexer;

    }



    @RequestMapping(value = "/start_all", method = RequestMethod.POST)

    public void startAll() {

        indexer.startAll();

    }



    @RequestMapping(value = "/start/{entityClassName:.+}", method = RequestMethod.POST)

    public void start(@PathVariable("entityClassName") String entityClassName) {

        indexer.start(entityClassName);

    }



    @RequestMapping(value = "/stop_all", method = RequestMethod.PUT)

    public Map stopAll() {

        return indexer.stopAll();

    }



    @RequestMapping(value = "/stop/{entityClassName:.+}", method = RequestMethod.PUT)

    public Boolean stop(@PathVariable("entityClassName") String entityClassName) {

        return indexer.stop(entityClassName);

    }



    @RequestMapping(value = "/progress", method = RequestMethod.GET)

    public Map getProgress() {

        return indexer.getProgress();

    }



}

```

## 快速开始

### 索引API

使用`com.timeyang.jkes.core.annotation`包下相关注解标记实体

```java

@lombok.Data

@Entity

@Document

public class Person extends AuditedEntity {



    // @Id will be identified automatically

    // @Field(type = FieldType.Long)

    @Id

    @GeneratedValue(strategy = GenerationType.IDENTITY)

    private Long id;



    @MultiFields(

            mainField = @Field(type = FieldType.Text),

            otherFields = {

                    @InnerField(suffix = "raw", type = FieldType.Keyword),

                    @InnerField(suffix = "english", type = FieldType.Text, analyzer = "english")

            }

    )

    private String name;



    @Field(type = FieldType.Keyword)

    private String gender;



    @Field(type = FieldType.Integer)

    private Integer age;



    // don't add @Field to test whether ignored

    // @Field(type = FieldType.Text)

    private String description;



    @Field(type = FieldType.Object)

    @ManyToOne(fetch = FetchType.EAGER)

    @JoinColumn(name = "group_id")

    private PersonGroup personGroup;



}

```

```java

@lombok.Data

@Entity

@Document(type = "person_group", alias = "person_group_alias")

public class PersonGroup extends AuditedEntity {

    @Id

    @GeneratedValue(strategy = GenerationType.IDENTITY)

    private Long id;

    private String name;

    private String interests;

    @OneToMany(fetch = FetchType.EAGER, cascade = CascadeType.ALL, mappedBy = "personGroup", orphanRemoval = true)

    private List persons;

    private String description;



    @DocumentId

    @Field(type = FieldType.Long)

    public Long getId() {

        return id;

    }



    @MultiFields(

            mainField = @Field(type = FieldType.Text),

            otherFields = {

                    @InnerField(suffix = "raw", type = FieldType.Keyword),

                    @InnerField(suffix = "english", type = FieldType.Text, analyzer = "english")

            }

    )

    public String getName() {

        return name;

    }



    @Field(type = FieldType.Text)

    public String getInterests() {

        return interests;

    }



    @Field(type = FieldType.Nested)

    public List getPersons() {

        return persons;

    }



    /**

     * 不加Field注解，测试序列化时是否忽略

     */

    public String getDescription() {

        return description;

    }

}

```

当更新实体时，文档会被自动索引到ElasticSearch；删除实体时，文档会自动从ElasticSearch删除。



### 搜索API

启动搜索服务[jkes-search-service](https://github.com/chaokunyang/jkes/tree/master/jkes-services/jkes-search-service)，搜索服务是一个Spring Boot Application，提供rest搜索api，默认运行在9000端口。

- URI query

```

curl -XPOST localhost:9000/api/v1/integration_test_person_group/person_group/_search?from=3&size=10

```



- Nested query

```

integration_test_person_group/person_group/_search?from=0&size=10

{

  "query": {

    "nested": {

      "path": "persons",

      "score_mode": "avg",

      "query": {

        "bool": {

          "must": [

            {

              "range": {

                "persons.age": {

                  "gt": 5

                }

              }

            }

          ]

        }

      }

    }

  }

}

```

- match query

```

integration_test_person_group/person_group/_search?from=0&size=10

{

  "query": {

      "match": {

        "interests": "Hadoop"

      }

    }

}

```

- bool query

```

{

  "query": {

    "bool" : {

      "must" : {

        "match" : { "interests" : "Hadoop" }

      },

      "filter": {

        "term" : { "name.raw" : "name0" }

      },

      "should" : [

        { "match" : { "interests" : "Flink" } },

        {

            "nested" : {

                "path" : "persons",

                "score_mode" : "avg",



                "query" : {

                    "bool" : {

                        "must" : [

                        { "match" : {"persons.name" : "name40"} },

                        { "match" : {"persons.interests" : "interests"} }

                        ],

                        "must_not" : {

                            "range" : {

                              "age" : { "gte" : 50, "lte" : 60 }

                            }

                          }

                    }

                }

            }

        }



      ],

      "minimum_should_match" : 1,

      "boost" : 1.0

    }



  }



}

```

- Source filtering

```

integration_test_person_group/person_group/_search

{

    "_source": false,

    "query" : {

        "match" : { "name" : "name17" }

    }

}

```

```

integration_test_person_group/person_group/_search

{

    "_source": {

            "includes": [ "name", "persons.*" ],

            "excludes": [ "date*", "version", "persons.age" ]

        },

    "query" : {

        "match" : { "name" : "name17" }

    }

}

```

- prefix

```

integration_test_person_group/person_group/_search

{ 

  "query": {

    "prefix" : { "name" : "name" }

  }

}

```

- wildcard

```

integration_test_person_group/person_group/_search

{

    "query": {

        "wildcard" : { "name" : "name*" }

    }

}

```

- regexp

```

integration_test_person_group/person_group/_search

{

    "query": {

        "regexp":{

            "name": "na.*17"

        }

    }

}

```



## Jkes工作原理

索引工作原理：

- 应用启动时，Jkes扫描所有标注`@Document`注解的实体，为它们构建元数据。

- 基于构建的元数据，创建`index`和`mapping`Json格式的配置，然后通过`ElasticSearch Java Rest Client`将创建/更新`index`配置。

- 为每个文档创建/更新`Kafka ElasticSearch Connector`，用于创建/更新文档

- 为整个项目启动/更新`Jkes Deleter Connector`，用于删除文档

- 拦截数据操作方法。将`* save(*)`方法返回的数据包装为`SaveEvent`保存到`EventContainer`；使用`(* delete*(..)`方法的参数，生成一个`DeleteEvent/DeleteAllEvent`保存到`EventContainer`。

- 拦截事务。在事务提交后使用`JkesKafkaProducer`发送`SaveEvent`中的实体到Kafka，Kafka会使用我们提供的`JkesJsonSerializer`序列化指定的数据，然后发送到Kafka。

- 与`SaveEvent`不同，`DeleteEvent`会直接被序列化，然后发送到Kafka，而不是只发送一份数据

- 与`SaveEvent`和`DeleteEvent`不同，`DeleteAllEvent`不会发送数据到Kafka，而是直接通过`ElasticSearch Java Rest Client`删除相应的`index`，然后重建该索引，重启`Kafka ElasticSearch Connector`



查询工作原理：

- 查询服务通过rest api提供

- 我们没有直接使用ElasticSearch进行查询，因为我们需要在后续版本使用机器学习进行搜索排序，而直接与ElasticSearch进行耦合，会增加搜索排序API的接入难度

- 查询服务是一个Spring Boot Application，使用docker打包为镜像

- 查询服务提供多版本API，用于API进化和兼容

- 查询服务解析`json`请求，进行一些预处理后，使用`ElasticSearch Java Rest Client`转发到ElasticSearch，将得到的响应进行解析，进一步处理后返回到客户端。

- 为了便于客户端人员开发，查询服务提供了一个[查询UI界面](http://localhost:9000/api/v1)，开发人员可以在这个页面得到预期结果后再把json请求体复制到程序中。



## 流程图

![Jkes流程图](https://raw.githubusercontent.com/chaokunyang/jkes/master/docs/images/Jkes%20Architecture.png)



## 模块介绍

### jkes-core

`jkes-core`是整个`jkes`的核心部分。主要包括以下功能：

- `annotation`包提供了jkes的核心注解

- `elasticsearch`包封装了`elasticsearch`相关的操作，如为所有的文档创建/更新索引，更新mapping

- `kafka`包提供了Kafka 生产者，Kafka Json Serializer，Kafka Connect Client

- `metadata`包提供了核心的注解元数据的构建与结构化模型

- `event`包提供了事件模型与容器

- `exception`包提供了常见的Jkes异常

- `http`包基于`Apache Http Client`封装了常见的http json请求

- `support`包暴露了Jkes核心配置支持

- `util`包提供了一些工具类，便于开发。如：Asserts, ClassUtils, DocumentUtils, IOUtils, JsonUtils, ReflectionUtils, StringUtils



### jkes-boot

`jkes-boot`用于与一些第三方开源框架进行集成。



当前，我们通过`jkes-spring-data-jpa`，提供了与`spring data jpa`的集成。通过使用Spring的AOP机制，对`Repository`方法进行拦截，生成`SaveEvent/DeleteEvent/DeleteAllEvent`保存到`EventContainer`。通过使用我们提供的`SearchPlatformTransactionManager`，对常用的事务管理器(如`JpaTransactionManager`)进行包装，提供事务拦截功能。



在后续版本，我们会提供与更多框架的集成。



`jkes-spring-data-jpa`说明：

- `ContextSupport`类用于从bean工厂获取`Repository Bean`

- `@EnableJkes`让客户端能够轻松开启Jkes的功能，提供了与Spring一致的配置模型

- `EventSupport`处理事件的细节，在保存和删除数据时生成相应事件存放到`EventContainer`，在事务提交和回滚时处理相应的事件

- `SearchPlatformTransactionManager`包装了客户端的事务管理器，在事务提交和回滚时加入了`回调hook`

- `audit`包提供了一个简单的`AuditedEntity`父类，方便添加审计功能，版本信息可用于结合`ElasticSearch`的版本机制保证不会索引过期文档数据

- `exception`包封装了常见异常

- `intercept`包提供了AOP切点和切面

- `index`包提供了`全量索引`功能。当前，我们提供了基于`线程池`的索引机制和基于`ForkJoin`的索引机制。在后续版本，我们会重构代码，增加基于`阻塞队列`的`生产者-消费者`模式，提供并发性能

- 



### jkes-services

`jkes-services`主要用来提供一些服务。

目前，`jkes-services`提供了以下服务：

- `jkes-delete-connector`

    

  - `jkes-delete-connector`是一个`Kafka Connector`，用于从kafka集群获取索引删除事件(`DeleteEvent`)，然后使用`Jest Client`删除ElasticSearch中相应的文档。

   

  - 借助于Kafka Connect的rest admin api，我们轻松地实现了多租户平台上的文档删除功能。只要为每个项目启动一个`jkes-delete-connector`，就可以自动处理该项目的文档删除工作。避免了每启动一个新的项目，我们都得手动启动一个Kafka Consumer来处理该项目的文档删除工作。尽管可以通过正则订阅来减少这样的工作，但是还是非常不灵活

    

- `jkes-search-service`

  

  - `jkes-search-service`是一个restful的搜索服务，提供了多版本的rest query api。查询服务提供多版本API，用于API进化和兼容

  - `jkes-search-service`目前支持URI风格的搜索和JSON请求体风格的搜索。

  - 我们没有直接使用ElasticSearch进行查询，因为我们需要在后续版本使用机器学习进行搜索排序，而直接与ElasticSearch进行耦合，会增加搜索排序的接入难度

  - 查询服务是一个Spring Boot Application，使用docker打包为镜像

  - 查询服务解析`json`请求，进行一些预处理后，使用`ElasticSearch Java Rest Client`转发到ElasticSearch，将得到的响应进行解析，进一步处理后返回到客户端。

  - 为了便于客户端人员开发，查询服务提供了一个[查询UI界面](http://localhost:9000/api/v1)，开发人员可以在这个页面得到预期结果后再把json请求体复制到程序中。



后续，我们将会基于`zookeeper`构建索引集群，提供集群索引管理功能



### jkes-integration-test

`jkes-integration-test`是一个基于Spring Boot集成测试项目，用于进行`功能测试`。同时测量一些常见操作的`吞吐率`



## Development

To build a development version you'll need a recent version of Kafka. You can build jkes with Maven using the standard lifecycle phases.



## Contribute

- Source Code: https://github.com/chaokunyang/jkes

- Issue Tracker: https://github.com/chaokunyang/jkes/issues



## LICENSE

This project is licensed under Apache License 2.0.