各位 Easysearch 的小夥伴們，我們前一陣剛把 easysearch-client 更新到了 2.0.2 版本！藉此詳細介紹下新版客户端的使用。
新版客户端和 1.0 版本相比，完全重構，拋棄了舊版客户端的一些歷史包袱，從裏到外都煥然一新！不管是剛入門的小白還是經驗豐富的老司機，2.0.x 客户端都能讓你開發效率蹭蹭往上漲！
到底有啥新東西？
- 更輕更快： 以前的版本依賴了一堆亂七八糟的東西，現在好了，我們把那些沒用的都砍掉了，客户端變得更苗條，性能也槓槓的！
- 類型安全，告別迷糊： 常用的 Easysearch API 現在都配上了強類型的請求和響應對象，再也不用擔心寫錯參數類型了，代碼也更好看了，維護起來也更省心！
- 同步異步，想咋用咋用： 所有 API 都支持同步和異步兩種調用方式，不管是啥場景，都能輕鬆應對！
- 構建查詢，跟搭積木一樣簡單： 我們用了流式構建器和函數式編程，構建複雜查詢的時候，代碼寫起來那叫一個流暢，看着也舒服！
- 和 Jackson 無縫對接： 可以輕鬆地把你的 Java 類和客户端 API 關聯起來，數據轉換嗖嗖的快！
快速上手
廢話不多説，咱們直接上乾貨！這部分教你怎麼快速安裝和使用 easysearch-client 2.0.2 客户端，還會演示一些基本操作。
安裝
easysearch-client 2.0.2 已經上傳到 Maven 中央倉庫了，加到你的項目裏超級方便。
最低要求： JDK 8 或者更高版本
依賴管理： 客户端內部用 Jackson 來處理對象映射。
Maven 項目
在你的 pom.xml 文件的 <dependencies> 裏面加上這段：
<dependencies>
<dependency>
<groupId>com.infinilabs</groupId>
<artifactId>easysearch-client</artifactId>
<version>2.0.2</version>
</dependency>
</dependencies>Gradle 項目
在你的 build.gradle 文件的 dependencies 裏面加上這段：
dependencies {
implementation 'com.infinilabs:easysearch-client:2.0.2'
}初始化客户端
下面這段代碼演示了怎麼初始化一個啓用了安全通信加密和 security 的 Easysearch 客户端，看起來有點長，別慌，我們一步一步解釋！
public static EasysearchClient create() throws NoSuchAlgorithmException, KeyStoreException,
KeyManagementException {
final HttpHost[] hosts = new HttpHost[]{new HttpHost("localhost", 9200, "https")};
final SSLContext sslContext = SSLContextBuilder.create()
.loadTrustMaterial(null, (chains, authType) -> true).build();
SSLIOSessionStrategy sessionStrategy = new SSLIOSessionStrategy(sslContext, NoopHostnameVerifier.INSTANCE);
final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY, new UsernamePasswordCredentials("username", "passwowd"));
RestClient restClient = RestClient.builder(hosts)
.setHttpClientConfigCallback(httpClientBuilder ->
httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider)
.setSSLStrategy(sessionStrategy)
.disableAuthCaching()
).setRequestConfigCallback(requestConfigCallback ->
requestConfigCallback.setConnectTimeout(30000).setSocketTimeout(300000))
.build();
EasysearchTransport transport = new RestClientTransport(
restClient, new JacksonJsonpMapper());
return new EasysearchClient(transport);
}這段代碼，簡單來説，就是：
- 連上 Easysearch： 我們要用 HTTPS 連接到本地的 9200 端口。
- 搞定證書： 這裏為了方便，我們信任了所有證書（注意！生產環境一定要配置好你們自己的證書）。
- 填上用户名密碼： 這裏需要填上你的用户名和密碼。
- 設置連接參數： 設置了連接超時時間（30 秒）和讀取超時時間（300 秒）。
- 創建客户端： 最後，我們就創建好了一個
EasysearchClient實例，可以開始幹活了！
舉個栗子：批量操作
下面的例子演示了怎麼用 bulk API 來批量索引數據：
public static void bulk() throws Exception {
String json2 = "{"
+ " \"@timestamp\": \"2023-01-08T22:50:13.059Z\","
+ " \"agent\": {"
+ " \"version\": \"7.3.2\","
+ " \"type\": \"filebeat\","
+ " \"ephemeral_id\": \"3ff1f2c8-1f7f-48c2-b560-4272591b8578\","
+ " \"hostname\": \"ba-0226-msa-fbl-747db69c8d-ngff6\""
+ " }"
+ "}";
EasysearchClient client = create();
BulkRequest.Builder br = new BulkRequest.Builder();
br.index("test1");
for (int i = 0; i < 10; i++) {
BulkOperation.Builder builder = new BulkOperation.Builder();
IndexOperation.Builder indexBuilder = new IndexOperation.Builder();
builder.index(indexBuilder.document(JsonData.fromJson(json2)).build());
br.operations(builder.build());
}
for (int i = 0; i < 10; i++) {
BulkOperation.Builder builder = new BulkOperation.Builder();
IndexOperation.Builder indexBuilder = new IndexOperation.Builder();
indexBuilder.document(JsonData.fromJson(json2)).index("test2");
builder.index(indexBuilder.build());
br.operations(builder.build());
}
for (int i = 0; i < 10; i++) {
Map<String, Object> map = new HashMap<>();
map.put("@timestamp", "2023-01-08T22:50:13.059Z");
map.put("field1", "value1");
IndexOperation.Builder indexBuilder = new IndexOperation.Builder();
indexBuilder.document(map).index("test3");
br.operations(new BulkOperation(indexBuilder.build()));
}
BulkResponse bulkResponse = client.bulk(br.build());
if (bulkResponse.errors()) {
for (BulkResponseItem item : bulkResponse.items()) {
System.out.println(item.toString());
}
}
client._transport().close();
}這個例子裏，我們一口氣把數據批量索引到了 test1、test2 和 test3 這三個索引裏，
並且展示了三種在 bulk API 中構建 IndexOperation 的方式，雖然它們最終都能實現將文檔索引到 Easysearch，但在使用場景和靈活性上還是有一些區別的：
這段代碼的核心是利用 BulkRequest.Builder 來構建一個批量請求，並通過 br.operations(...) 方法添加多個操作。而每個操作，在這個例子裏，都是一個 IndexOperation，也就是索引一個文檔。IndexOperation 可以通過 IndexOperation.Builder 來創建。
三種方式的區別主要體現在如何構建 IndexOperation 裏的 document 部分，也就是要索引的文檔內容。
第一種方式：使用 JsonData.fromJson(json2) 且不指定索引。
特點：
使用 JsonData.fromJson(json2) 將一個 JSON 字符串直接轉換成 JsonData 對象作為文檔內容。
這裏沒有在 IndexOperation.Builder 上調用 index() 方法來指定索引名稱。由於沒有在每個 IndexOperation 中指定索引，這個索引名稱將回退到 BulkRequest.Builder 上設置的索引，即 br.index("test1")，所以這 10 個文檔都會被索引到 test1。
當你需要將一批相同結構的 JSON 文檔索引到同一個索引時，這種方式比較簡潔。
第二種方式：使用 JsonData.fromJson(json2) 並指定索引
特點：
同樣使用 JsonData.fromJson(json2) 將 JSON 字符串轉換成 JsonData 對象。
關鍵區別在於，這裏在 IndexOperation.Builder 上調用了 index("test2")，為每個操作單獨指定了索引名稱。
這 10 個文檔會被索引到 test2，即使 BulkRequest.Builder 上設置了 index("test1") 也沒用，因為 IndexOperation 裏的設置優先級更高。
當你需要將一批相同結構的 JSON 文檔索引到不同的索引時，就需要使用這種方式來分別指定索引。
第三種方式：使用 Map<String, Object> 並指定索引
特點：
使用 Map<String, Object> 來構建文檔內容，這種方式更加靈活，可以構建任意結構的文檔。
同樣在 IndexOperation.Builder 上調用了 index("test3") 指定了索引名稱。
使用 new BulkOperation(indexBuilder.build()) 代替之前的 builder.index(indexBuilder.build())， 這是等價的。
這 10 個文檔會被索引到 test3。
當你需要索引的文檔結構不固定，或者你需要動態構建文檔內容時，使用 Map 是最佳選擇。例如，你可以根據不同的業務邏輯，往 Map 裏添加不同的字段。
總結
這次 easysearch-client 2.0.x Java 客户端的更新真的很給力，強烈建議大家升級體驗！相信我，用了新版客户端，你的開發效率絕對會提升一大截！
想要了解更多？
- 客户端 Maven 地址： https://mvnrepository.com/artifact/com.infinilabs/easysearch-client/2.0.2
- 更詳細的文檔和示例代碼在 官網 持續更新中，請隨時關注！
大家有啥問題或者建議，也歡迎隨時反饋！
作者：張磊，極限科技（INFINI Labs）搜索引擎研發負責人，對 Elasticsearch 和 Lucene 源碼比較熟悉，目前主要負責公司的 Easysearch 產品的研發以及客户服務工作。
