mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
2894 words
8 minutes
Elasticsearch 从 0 到 1(四):用 Spring Boot 提供商品搜索接口
2025-06-07
2026-09-27

第三篇已经能在 Kibana 中搜索商品。这一篇把同样的能力变成一个 HTTP 接口:接收关键词、品牌、分类和价格区间,返回分页商品以及标题高亮。

这里最容易让人困惑的不是 Java 语法,而是把所有事情塞进一段嵌套的客户端调用:校验参数、决定排序、拼查询、拆结果都挤在一起,稍微改一个需求就很难读懂。我们按一次请求经过的步骤拆开,每层只处理一种问题。

前提:完成第二篇的索引和五条样本,确认第三篇的查询能返回 1001、1005。Java 程序连接第一篇的本机 ES,查询使用 products-read,练习写入使用 products-write。

1. 先拿到完整工程,再读关键代码#

本篇提供一个独立 Maven 工程,正文展示关键步骤,完整文件包含 package、import、启动类和测试,避免照抄时还需要补一批未定义的方法。

下载完整示例工程(tar.gz) · 查看运行说明

组件固定版本
Java17,或支持 release 17 的较新 JDK
Spring Boot3.3.1
Elasticsearch 服务端8.14.0
Java API Client / REST Client都为 8.14.0

这些是教学基线,不代表当前最新生产版本。尤其不要只升级 elasticsearch-java,却让框架依赖管理把底层 elasticsearch-rest-client 留在另一个版本。

完整的 pom.xml使用 Spring Boot 3.3.1 parent,并包含 Web、Validation、两个固定版本的 ES 客户端和测试依赖。本例没有同时引入 Spring Data Elasticsearch,便于先看清 DSL 与官方客户端的对应关系。

下载并解压后,在工程目录执行:

mvn test
mvn spring-boot:run

测试通过只能说明 Java 侧的查询构建、参数绑定和结果处理符合预期,不需要也不会连接真实 ES。启动服务后,仍要连接已导入样本的本机 ES,完成文末的端到端验证。

工程中一次搜索经过的路径如下:

flowchart LR R["GET 请求"] --> C["Controller:绑定并校验"] C --> S["Service:构造 DSL"] S --> E["Java Client:请求 ES"] E --> P["Service:检查并转换响应"] P --> V["SearchPage:返回 JSON"]

2. 客户端只创建一次,交给 Spring 管理关闭#

完整配置在 ElasticsearchConfig.java。可以把它理解成三层:

  • RestClient 管理 HTTP 连接和超时。
  • RestClientTransport 负责传输,以及 Java 对象和 JSON 的转换。
  • ElasticsearchClient 提供搜索、写入等 API。

创建连接时使用 Spring Boot 已配置的 ObjectMapper,并让 Spring 在关闭应用时关闭 transport。下面是配置中的核心部分,完整类还包含连接地址校验:

@Bean(destroyMethod = "close")
public ElasticsearchTransport elasticsearchTransport(
ObjectMapper objectMapper,
@Value("${app.elasticsearch.url}") String url) {
RestClient restClient = RestClient.builder(HttpHost.create(url))
.setRequestConfigCallback(config -> config
.setConnectTimeout(2000)
.setConnectionRequestTimeout(2000)
.setSocketTimeout(5000))
.build();
return new RestClientTransport(restClient, new JacksonJsonpMapper(objectMapper));
}
@Bean
public ElasticsearchClient elasticsearchClient(ElasticsearchTransport transport) {
return new ElasticsearchClient(transport);
}

这里复用 Boot 的 mapper,是为了让日期模块等配置保持一致。每次请求都重新创建客户端,会反复建立连接,也更容易忘记释放资源;因此它们都作为单例 Bean 使用。

application.yml默认连接 http://127.0.0.1:9200,应用监听 127.0.0.1:8080。它对应第一篇关闭认证、只绑定本机端口的练习环境,完整配置也限制为这个连接范围。

如果已有集群启用了认证与 TLS,需要按官方连接文档配置 HTTPS、CA 信任和认证信息。这与修改一个端口号不同,不要用跳过证书校验来代替正确的连接配置。

3. 文档对象与请求参数分别建模#

ES 返回的商品与用户提交的搜索条件,是两种不同的数据。把它们分开,可以避免为了接收一个筛选参数,就去改商品文档结构。

ProductDocument.java对应第二篇的字段:

public record ProductDocument(
long productId,
String title,
String description,
String brand,
String category,
int price,
int sales,
int stock,
String status,
OffsetDateTime createdAt) {
}

价格仍然是分,createdAt 使用能表达时区偏移的 OffsetDateTime。这个类描述搜索投影,不是 JPA 实体,也不意味着会自动创建 ES Mapping。索引仍要先按第二篇建立。

SearchInput.java描述输入条件。它会把空白关键词处理为空字符串,给缺省页码、页大小和排序设置默认值,再通过 Bean Validation 检查边界:

参数约定
keyword空白表示浏览;最多 200 字符
brand、category空白表示不筛选;各最多 100 字符
minPrice、maxPrice可省略;非负整数分;最小值不大于最大值
sortBy只接受后文列出的五种值
pageNo、pageSize默认 1、10;每页最多 100 条
分页窗口pageNo × pageSize <= 10000

窗口检查相当于 from + size <= 10000。要先挡住不合理的请求,再计算 from;不能把负页码或超大分页原样传给 ES。

4. 把 DSL 拆成查询、排序和展示选项#

完整实现见 ProductSearchService.java。本篇选择先用 Java 的 Map、List 表达已经学过的 DSL,再通过客户端的 withJson 读取为 SearchRequest。

这仍然使用官方 Java API Client;只是把查询结构与深层 lambda 调用分开,方便与第三篇的 JSON 对照。代价是字段名和 Map 结构缺少完整的编译期约束,因此示例测试会实际运行客户端解析和序列化过程。也可以改写成类型化 Builder,业务含义应保持一致。

查询决定哪些商品入选#

buildQuery 先构造过滤条件:上架状态总是必选,品牌、分类和价格根据参数追加。只有关键词非空时,才加标题的 match 查询。

下面是该方法中处理可选条件的关键代码;filters 和 bounds 都是当前请求内部创建的集合:

filters.add(term("status", "ON_SALE"));
if (!input.brand().isEmpty()) {
filters.add(term("brand", input.brand()));
}
if (!input.category().isEmpty()) {
filters.add(term("category", input.category()));
}
if (input.minPrice() != null) {
bounds.put("gte", input.minPrice());
}
if (input.maxPrice() != null) {
bounds.put("lte", input.maxPrice());
}
if (!bounds.isEmpty()) {
filters.add(Map.of("range", Map.of("price", bounds)));
}

term 是同一个类里的小方法,返回 Map.of("term", Map.of(field, value))。关键词部分使用 operator: "and",与前文一致;空关键词则省略 must,让状态和其他筛选条件决定浏览列表。

排序是业务白名单#

允许的五个值是 default、sales_desc、price_asc、price_desc、newest。默认模式有关键词时按 _score 降序,空关键词时按销量降序;所有模式最后追加 productId 升序,处理主要排序字段相同的情况。

在交给 withJson 的 JSON 中,排序统一使用完整对象形式,避免 _score 简写在这个版本的客户端解析器中失败:

{
"sort": [
{ "_score": { "order": "desc" } },
{ "productId": { "order": "asc" } }
]
}

上面是有关键词、默认排序时的顶层字段片段。用户参数只是选择已有规则,不能直接变成任意 ES 字段名。最后一种 newest 在本例按 createdAt 排列,语义是“最近创建”,不是“最近上架”。

请求构造只负责组装#

下面是 buildRequest 的主体。它调用的 buildQuery、buildSort 都已在完整 Service 中实现:

Map<String, Object> body = new LinkedHashMap<>();
body.put("from", (input.pageNo() - 1) * input.pageSize());
body.put("size", input.pageSize());
body.put("query", buildQuery(input));
body.put("sort", buildSort(input));
body.put("track_total_hits", true);
body.put("timeout", "2s");
if (!input.keyword().isEmpty()) {
body.put("highlight", Map.of(
"encoder", "html",
"pre_tags", List.of("<em>"),
"post_tags", List.of("</em>"),
"fields", Map.of("title", Map.of("number_of_fragments", 0))));
}
String json = objectMapper.writeValueAsString(body);
return new SearchRequest.Builder()
.index("products-read")
.allowPartialSearchResults(false)
.withJson(new StringReader(json))
.build();

这里序列化的是结构化数据,不是手工拼接用户输入的 JSON 字符串。关键词中即使出现引号,也由序列化器处理。

timeout: "2s" 是 ES 搜索执行的超时设置,连接和 Socket 超时是 HTTP 侧的设置,两者不能视为同一个端到端截止时间。返回以后仍然需要检查 timed_out 和失败分片。

5. 转换响应时,先判断它是不是完整答案#

执行搜索只需要一行:

SearchResponse<ProductDocument> response =
client.search(buildRequest(input), ProductDocument.class);

后面的结果转换分成两步。第一步检查响应:超时或分片失败时返回服务不可用;本例已经请求精确总数,因此还要确认 hits.total 存在且 relation=eq。遇到 gte 不能把它当作精确数量。

第二步再把每条命中转成页面对象:

List<SearchPage.Item> items = new ArrayList<>();
for (Hit<ProductDocument> hit : response.hits().hits()) {
ProductDocument product = hit.source();
if (product == null) {
throw new ResponseStatusException(
HttpStatus.BAD_GATEWAY, "搜索结果缺少商品内容");
}
List<String> fragments = hit.highlight().get("title");
String highlight = fragments == null || fragments.isEmpty()
? null : fragments.get(0);
items.add(new SearchPage.Item(
product.productId(), product.title(), highlight,
product.brand(), product.category(), product.price(), product.sales()));
}
return new SearchPage(total.value(), input.pageNo(), input.pageSize(), items);

total 是前一步已经检查过的总数对象。完整的 SearchPage.java返回 total、pageNo、pageSize 和 list。

商品的 title 始终保留原文,highlightTitle 只用于展示。没有高亮时,它为 null,页面回退到纯文本标题;不能把纯文本回退值当作未经编码的 HTML。存在高亮时,ES 使用 encoder: html 处理原文,前端仍应只接受约定的高亮标记。

连接失败与 ES 请求失败会被记录并转换为 HTTP 503;响应缺失必要内容则返回 HTTP 502。只有正常查询确实没有命中,才返回成功状态和空列表。这能让用户和监控都区分“没找到商品”与“这次搜索没有成功”。

6. Controller 只做入口,不再重复构造查询#

完整 Controller 如下:

package com.example.search;
import jakarta.validation.Valid;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/products")
public class ProductSearchController {
private final ProductSearchService service;
public ProductSearchController(ProductSearchService service) {
this.service = service;
}
@GetMapping("/search")
public SearchPage search(@Valid @ModelAttribute SearchInput input) {
return service.search(input);
}
}

@ModelAttribute 把 GET 查询参数绑定到输入对象,@Valid 在进入方法前执行约束检查。页码不是数字、未知排序值、价格上下限颠倒,都会以参数错误结束,不需要发一次 ES 查询再判断。

这样再看调用链,就能知道应该在哪一层修改需求:新增筛选项先改输入约定和查询构造;新增展示字段改文档和输出对象;修改连接策略只改配置类。

7. Java 写入和删除怎样使用#

写入操作单独放在 ProductDocumentWriter.java,避免与用户的查询入口混在一起。下面两个方法都包含在完整工程中:

public IndexResponse save(ProductDocument document) throws IOException {
return client.index(i -> i.index("products-write")
.requireAlias(true)
.id(Long.toString(document.productId()))
.document(document));
}
public DeleteResponse delete(long productId) throws IOException {
return client.delete(d -> d.index("products-write")
.id(Long.toString(productId)));
}

save 使用固定商品 ID;同 ID 再执行会替换文档,所以传入的是完整投影。它不是自动合并字段的局部更新。写入成功后也仍有 refresh 的可搜索延迟,验证时按第二篇的方法处理。

delete 用于理解客户端的物理删除调用,完整工程没有为它暴露 HTTP 接口。下架通常可以保留文档、改成 OFF_SALE;真正的源数据删除还涉及旧消息重放导致“复活”的问题。

这两个方法只是客户端操作练习,没有实现跨系统同步、外部版本或失败补偿。业务代码不能因为会调用 save,就把“改 MySQL 后顺手写 ES”当成可靠的同步方案。下一篇会专门补上这部分。

8. 用一次成功请求和一次错误请求验证#

启动服务后,在终端发送下面的请求。Windows PowerShell 如果把 curl 解释成别名,请使用 curl.exe:

curl --get "http://127.0.0.1:8080/api/products/search" --data-urlencode "keyword=蓝牙耳机" --data-urlencode "category=数码耳机" --data-urlencode "minPrice=10000" --data-urlencode "maxPrice=30000" --data-urlencode "sortBy=sales_desc" --data-urlencode "pageNo=1" --data-urlencode "pageSize=10"

沿用五条原始样本时,检查 total=2,list 中先是 1001、再是 1005,价格分别为 19900、25900。有关键词时应能看到 highlightTitle,但具体标记片段不要写死成某一种字符串。

接着发送一个不合法的页码:

curl -i "http://127.0.0.1:8080/api/products/search?pageNo=0"

应该得到 HTTP 400。再把关键词留空,默认列表应按销量返回 1003、1001、1005、1002;下架商品 1004 不出现。

工程里的测试覆盖了参数绑定、分页和价格校验、空关键词、默认相关性排序、带时区日期、高亮回退、超时与连接失败。它们使用模拟客户端验证 Java 行为;本机没有 ES 时,测试通过也不等于分词、实际命中和连接已经通过验证,仍要完成上面的真实请求。

上一篇:把商品搜索需求写成 Query DSL · 系列目录 · 下一篇:MySQL 数据同步与一致性

参考资料#

Share

If this article helped you, please share it with others!

Elasticsearch 从 0 到 1(四):用 Spring Boot 提供商品搜索接口
https://mizuki.mysqil.com/posts/elasticsearch-04-springboot-practice/
Author
梦幻晨风
Published at
2025-06-07
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents