› ›

使用稳定的插件 API 创建文本分析插件

编辑

使用稳定的插件 API 创建文本分析插件

编辑

文本分析插件为 Elasticsearch 提供自定义的 Lucene 分析器、令牌过滤器、字符过滤器和分词器。

稳定的插件 API

编辑

文本分析插件可以基于稳定的插件 API 开发。此 API 由以下依赖项组成：

plugin-api - 插件开发者用来实现自定义 Elasticsearch 插件的 API。
plugin-analysis-api - 插件开发者用来实现分析插件并将其集成到 Elasticsearch 中的 API。
lucene-analysis-common - plugin-analysis-api 的依赖项，包含核心 Lucene 分析接口，如 Tokenizer、Analyzer 和 TokenStream。

对于同一主要版本内的 Elasticsearch 新版本，针对此 API 构建的插件不需要重新编译。此 API 的未来版本将向后兼容，插件与未来版本的 Elasticsearch 具有二进制兼容性。换句话说，一旦你拥有一个可用的工件，你就可以在将 Elasticsearch 升级到新的错误修复版本或次要版本时重复使用它。

文本分析插件可以实现分析插件 API 提供的四个工厂类。

AnalyzerFactory 用于创建 Lucene 分析器
CharFilterFactory 用于创建字符过滤器
TokenFilterFactory 用于创建 Lucene 令牌过滤器
TokenizerFactory 用于创建 Lucene 分词器

实现稳定插件的关键是 @NamedComponent 注解。许多 Elasticsearch 组件都有在配置中使用的名称。例如，关键字分析器在配置中被引用时使用名称 "keyword"。一旦你的自定义插件安装在你的集群中，你的命名组件也可以在这些配置中通过名称引用。

你还可以将文本分析插件创建为经典插件。但是，经典插件会绑定到特定版本的 Elasticsearch。当你升级 Elasticsearch 时，你需要重新编译它们。因为经典插件是基于可能发生变化的内部 API 构建的，所以升级到新版本可能需要修改代码。

稳定插件文件结构

编辑

稳定插件是 ZIP 文件，由 JAR 文件和两个元数据文件组成

stable-plugin-descriptor.properties - 描述插件的 Java 属性文件。请参阅稳定插件的插件描述符文件。
named_components.json - 一个 JSON 文件，将接口映射到组件名称和实现类的键值对。

请注意，只有插件根目录下的 JAR 文件才会添加到插件的类路径中。如果你需要其他资源，请将它们打包到资源 JAR 中。

开发流程

编辑

Elastic 提供了一个 Gradle 插件 elasticsearch.stable-esplugin，这使得开发和打包稳定插件更加容易。本节中的步骤假设你使用此插件。但是，你不需要 Gradle 来创建插件。

Elasticsearch Github 存储库包含一个分析插件示例。示例 build.gradle 构建脚本为开发你自己的插件提供了一个很好的起点。

前提条件

编辑

插件是用 Java 编写的，因此你需要安装 Java 开发工具包 (JDK)。如果要使用 Gradle，请安装 Gradle。

逐步操作

编辑

为你的项目创建一个目录。
将示例 build.gradle 构建脚本复制到你的项目目录。请注意，此构建脚本使用 elasticsearch.stable-esplugin gradle 插件来构建你的插件。
编辑 build.gradle 构建脚本
- 将 pluginApiVersion 和匹配的 luceneVersion 变量的定义添加到文件的顶部。你可以在 Elasticsearch Github 存储库中的 build-tools-internal/version.properties 文件中找到这些版本。
- 编辑构建脚本的 esplugin 部分中的 name 和 description。这将创建插件描述符文件。如果你不使用 elasticsearch.stable-esplugin gradle 插件，请参阅稳定插件的插件描述符文件以手动创建该文件。
- 添加模块信息。
- 确保你已声明以下编译时依赖项。这些依赖项仅在编译时存在，因为 Elasticsearch 将在运行时提供这些库。
  - org.elasticsearch.plugin:elasticsearch-plugin-api
  - org.elasticsearch.plugin:elasticsearch-plugin-analysis-api
  - org.apache.lucene:lucene-analysis-common
- 对于单元测试，请确保这些依赖项也已作为 testImplementation 依赖项添加到 build.gradle 脚本中。
实现分析插件 API 中的接口，并使用 NamedComponent 对其进行注解。有关示例，请参阅文本分析插件示例。
现在，你应该可以通过运行以下命令来组装插件 ZIP 文件
```
gradle bundlePlugin
```
生成的插件 ZIP 文件将写入 build/distributions 目录。

YAML REST 测试

编辑

Gradle elasticsearch.yaml-rest-test 插件允许你使用 Elasticsearch yamlRestTest 框架测试你的插件。这些测试使用 YAML 格式的域语言，针对安装了你的插件的内部 Elasticsearch 集群发出 REST 请求，并检查这些请求的结果。YAML REST 测试目录的结构如下：

一个测试套件类，在 src/yamlRestTest/java 下定义。此类应扩展 ESClientYamlSuiteTestCase。
YAML 测试本身应在 src/yamlRestTest/resources/test/ 下定义。

« 创建 Elasticsearch 插件稳定插件的插件描述符文件 »