Easysearch Plugin Template

一个极简的 Easysearch 插件开发模板，演示如何实现自定义 REST API 端点。

快速开始

1. 使用模板创建你的插件

点击 GitHub 的 "Use this template" 按钮，或手动克隆后修改：

# 修改插件名称（3个地方）
# 1. build.gradle: esplugin.name = 'your-plugin-name'
# 2. settings.gradle: rootProject.name = 'your-project-name'
# 3. 包名: src/main/java/org/easysearch/plugin/yourname/

2. 构建插件

推荐优先使用 Gradle（主构建工具），pom.xml 作为 Maven 构建示例：

• Gradle：主构建链，覆盖插件打包、单元测试、yamlRestTest、integTest
• Maven：简化版构建链，覆盖编译、单元测试、插件 zip 打包

./gradlew build
mvn test package

插件包默认生成位置：

• Gradle：build/distributions/your-plugin.zip
• Maven：target/your-plugin.zip

Maven 元数据说明

• Gradle：在 build.gradle 的 esplugin 块中配置插件元数据，构建时自动生成 plugin-descriptor.properties
• Maven：需手动维护 src/main/plugin-metadata/plugin-descriptor.properties 模板，构建时通过 pom.xml 的 properties 填充：
  • plugin.name - 插件名称
  • plugin.classname - 插件入口类全限定名
  • easysearch.version - Easysearch 版本

版本适配说明

如果你要适配不同的 Easysearch 版本：

• Gradle：修改 build.gradle 中默认值，或通过系统属性覆盖
• Maven：修改 pom.xml 中的 easysearch.version 属性

Gradle 默认值示例：

easysearch_version = System.getProperty("easysearch.version", "2.1.0")

将默认版本号 2.1.0 改为目标版本，或在构建时通过 -Deasysearch.version=目标版本 覆盖。

示例命令（可直接复制）：

./gradlew build -Deasysearch.version=2.2.0
mvn test package -Deasysearch.version=2.2.0

3. 安装到 Easysearch

# 在 Easysearch 目录中执行
bin/easysearch-plugin install file:///path/to/your-plugin.zip

模板示例功能

本模板实现了一个简单的 /_hello REST 端点：

GET /_hello?name=tom

响应：

{
  "message": "Hello tom",
  "cluster_name": "easysearch-cluster",
  "node_name": "node-1",
  "timestamp": 1710000000000
}

开发你自己的插件

项目结构

src/main/java/org/easysearch/plugin/hello/
├── HelloPlugin.java           # 插件入口类
└── rest/
    └── RestHelloAction.java   # REST 处理器示例

关键步骤

1. 修改插件类

   • 重命名 HelloPlugin.java 为你自己的类名
   • 实现需要的插件接口（如 ActionPlugin, AnalysisPlugin 等）

2. 添加 REST 端点

   • 参考 RestHelloAction.java 创建新的 REST 处理器
   • 在 HelloPlugin.getRestHandlers() 中注册

3. 配置插件信息

   • Gradle：修改 build.gradle 中的 esplugin { ... }
   • Maven：修改 pom.xml

测试

模板现在包含最基础的两类测试：

• 单元测试：src/test/java/org/easysearch/plugin/hello/rest/RestHelloActionTest.java
• YAML REST 套件入口：src/yamlRestTest/java/org/easysearch/plugin/hello/HelloClientYamlTestSuiteIT.java
• YAML REST API 定义：src/yamlRestTest/resources/rest-api-spec/api/hello.json
• YAML REST 测试：src/yamlRestTest/resources/rest-api-spec/test/hello/10_basic.yml

常用命令：

./gradlew test
./gradlew yamlRestTest
./gradlew check
mvn test
mvn package

说明：

• test 运行普通单元测试（类名需要匹配 *Test）
• 单元测试基于 EasySearchTestCase（推荐沿用 testXxx 方法命名）
• yamlRestTest 会启动测试集群并执行 REST 用例（需要 src/yamlRestTest/java 下有 suite 类）
• check 已配置为同时触发 integTest 与 yamlRestTest
• mvn test / mvn package 只覆盖简化版 Maven 构建，不会替代 Gradle 的集成测试链路

构建说明

本项目以 Gradle 为主构建工具，提供完整的开发、测试、打包链路：

• 编译插件代码
• 运行单元测试
• 启动测试集群并执行 YAML REST 测试
• 打包为可安装的分发包

同时附带 pom.xml 作为 Maven 构建示例，演示如何仅用 Maven 完成基础编译、单元测试和插件打包。适合以下场景：

• 团队只能使用 Maven 构建
• 作为集成到其他 Maven 项目的参考

注意：Maven 构建不包含 YAML REST 测试和集成测试功能。

版本兼容

组件	版本
Easysearch	2.x
Gradle	8.10.2
Java	11+

许可证

Copyright © INFINI LTD. All rights reserved.
Licensed under the Apache License, Version 2.0.