appbaseio/reactivesearch-api

ReactiveSearch API

ReactiveSearch API 是一个声明式的开源 API，用于查询 Elasticsearch，同时可作为 Elasticsearch 集群的反向代理和 API 网关。它最适合网站搜索、应用搜索和电商搜索等使用场景。

为什么使用 ReactiveSearch API

以一个图书电商网站的搜索查询为例：用户搜索关键词 "***"，需匹配 title 或 author 字段，且应用评分筛选仅返回评分 gte 4 的图书。

使用 Elasticsearch DSL 编写此查询约需 80 行代码，而使用 ReactiveSearch 仅需约 30 行代码。

![]([***]

两种格式的主要区别如下：

1. Elasticsearch 查询是命令式的，使用搜索引擎特定术语，表达能力强但学习曲线高；ReactiveSearch 查询是声明式的，隐藏了实现细节。
2. ReactiveSearch 查询避免了 Elasticsearch 查询的"嵌套地狱"，通过 react 属性将各个查询独立表达并组合。
3. 声明式特性使 ReactiveSearch 查询具有可组合性，便于捕获意图、丰富查询及对单个查询应用访问控制检查。
4. 声明式特性使其适合暴露在可公开检查的 Web 和移动网络中，而直接暴露 Elasticsearch DSL 可能导致脚本注入***风险。

ReactiveSearch 完整 API 参考见 此处。

安装

运行方式

运行 reactivesearch-api 需要 Elasticsearch 节点。可通过多种方式 搭建 Elasticsearch（本地或远程），以下为通过 Docker 镜像本地搭建单节点 Elasticsearch 的步骤。

注意：以下步骤假设系统已安装 Docker。

1. 创建 Docker 网络

    docker network create reactivesearch
   

2. 本地启动单节点 Elasticsearch 集群

    docker run -d --rm --name elasticsearch -p 9200:9200 -p 9300:9300 --net=reactivesearch -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch-oss:7.10.2
   

3. 本地启动 ReactiveSearch

    docker build -t reactivesearch . && docker run --rm --name reactivesearch -p 8000:8000 --net=reactivesearch --env-file=config/docker.env reactivesearch
   

为方便使用，上述步骤已整合到单个 docker-compose 文件中，可通过以下命令执行：

docker-compose up

从源码构建

从源码构建需安装 Git 和 Go（1.11 或更高版本）。

在项目目录中执行以下命令本地构建二进制文件：

make

构建后会在项目根目录生成可执行文件及插件库。启动 ReactiveSearch 服务器：

bash
./build/reactivesearch --env=config/manual.env --log=info

也可执行以下命令不生成可执行文件直接启动服务器（仍会生成插件库）：

make plugins
go run main.go --env=config/manual.env

注意：运行可执行文件需确保上游 Elasticsearch 已启动，其 URL 在 .env 文件中配置。

日志配置

通过运行时标志 log 更改默认日志模式，可选值：

debug

最详细，用于获取 Elasticsearch 交互日志。

info

打印基本信息。

error（默认）

仅记录错误。

CPU 性能分析

运行时设置 cpuprofile 标志为 true 可启用 CPU 性能分析。更多使用方法见 此文章。

TLS 支持

可通过 https 标志启动 ReactiveSearch 以提供 HTTPS 服务，需通过环境文件指定服务器密钥和证书文件位置。config/manual.env 配置了演示用的服务器密钥和证书，适用于 localhost。

bash
go run main.go --log=info --env=config/manual.env --https

若需在 localhost 手动测试 TLS 支持，curl 需额外传递 CA 证书参数：

bash
curl https://foo:bar@localhost:8000/_user --cacert sample/rootCA.pem

通过 HTTP 加载 JWT 密钥

若需测试通过 HTTP 加载 JWT 密钥，可执行以下命令启动提供密钥的 HTTP 服务器：

bash
cd sample
python -m SimpleHTTPServer 8500

然后启动 ReactiveSearch：

bash
go run main.go --log=info --env=config/manual-http-jwt.env

ReactiveSearch 还提供运行时设置密钥的 API 端点，因此初始可不设置密钥。

运行测试

目前已实现 auth、permissions、users 和 billing 模块的测试。运行测试：

bash
make test

或

bash
go test -p 1 ./...

扩展 ReactiveSearch API

ReactiveSearch 功能可通过插件扩展。插件可视为独立服务：可定义自己的路由（需避免与其他插件冲突）、中间件链，以及指定交互的数据库（如 Elasticsearch）。例如，可通过多个插件提供与多个数据库交互的特定服务。插件负责自身的请求生命周期。

插件无需必须定义路由，也可作为中间件供其他插件使用，无需新路由。插件间需避免循环依赖。

插件结构需遵循特定规范，详见插件 https://github.com/appbaseio/reactivesearch-api/blob/master/docs/plugins.md%E3%80%82

可用插件

User（用户）

与 ReactiveSearch 交互需定义 User 或权限。User 包含以下属性定义其能力：

• username：用户唯一标识。
• password：用户身份验证密码。
• is_admin：是否为管理员用户。
• categories：对应 Elasticsearch API 分类，如 Cat API、Search API、Docs API 等。
• acls：在每个 Elasticsearch API 分类内提供更细粒度控制。
• ops：用户可执行的操作。
• indices：用户有权访问的索引名称/模式。
• email：用户***地址。
• created_at：用户创建时间。

Permission（权限）

User 可创建 Permission 资源并关联，定义访问 Elasticsearch RESTful API 的能力。权限有固定的生存时间（TTL），过期后失效。权限由创建它的用户管理。

• username：自动生成的 Basic Auth 用户名。
• password：自动生成的 Basic Auth 密码。
• owner：权限所有者。
• creator：权限创建者。
• categories：对应 Elasticsearch API 分类，如 Cat API、Search API 等。
• acls：在每个 API 分类内提供更细粒度控制。
• ops：权限可执行的操作。
• indices：权限有权访问的索引名称/模式。
• sources：允许发起请求的源 IP。
• referers：允许发起请求的引用页。
• created_at：权限创建时间。
• ttl：权限有效期。
• limits：按 categories 划分的请求限制。
• description：权限用途描述。

Category（分类）

分类用于控制 ReactiveSearch 中的数据和 API 访问。除 Elasticsearch API 外，分类还涵盖 ReactiveSearch 自身 API，实现细粒度控制。Elasticsearch 分类对应其 API 分类，如 Document APIs、Search APIs 等；ReactiveSearch 分类对应其扩展 API，如分析和记账。支持的分类列表见 https://github.com/appbaseio/reactivesearch-api/blob/dev/docs/categories.md%E3%80%82

ACL（访问控制列表）

ACL 在分类基础上提供对 Elasticsearch API 的更细粒度控制。每个 ACL 对应 Elasticsearch API 的一个操作。设置分类会自动应用默认 ACL，设置 ACL 可进一步控制分类内的 API 访问。支持的 ACL 列表见 https://github.com/appbaseio/reactivesearch-api/blob/dev/docs/acls.md%E3%80%82

Op（操作）

操作定义请求的类型，在处理请求前识别。目前分为三类：

• Read：仅允许读请求。
• Write：仅允许写请求。
• Delete：仅允许删除请求。

允许修改数据需组合多个操作，如 ["read", "write"] 允许读写但禁止删除。

请求日志

ReactiveSearch 服务器会记录所有通过它发送到 Elasticsearch 的请求审计日志，包括请求和响应，供后续查看。可通过专用端点获取特定索引或整个集群的日志，详见 文档。

ReactiveSearch：UI 库

ReactiveSearch API 被 https://github.com/appbaseio/reactivesearch-api 和 https://github.com/appbaseio/searchbox 库使用。若使用 React、Vue、Flutter、React Native 或 Vanilla JS 构建搜索 UI，这些库提供常用搜索组件，可将开发时间从数周缩短至数天。

ReactiveSearch 🍞 与 appbase.io 🧈

appbase.io 在开源 ReactiveSearch API 基础上扩展了以下功能：

1. 可操作分析：捕获 ReactiveSearch API 遥测数据，提供用户、点击、转化、地理分布、慢搜索等搜索驱动洞察。
2. 搜索相关性：提供 REST API 和可视化界面，通过配置语言、搜索/聚合/结果设置、查询规则部署搜索相关性策略。
3. 应用缓存：提供极速搜索性能和更高的搜索吞吐量。
4. UI 构建器：无需代码创建搜索和推荐 UI 组件。

可 在云端部署 appbase.io，也可通过 AWS、Heroku、Docker 和 Kubernetes 一键安装，详见 快速入门。

文档

ReactiveSearch REST API 文档见 此处。