NoSQL 与搜索 / 系统课时
商品搜索接口实现
商品搜索接口实现
本课把“关键词、分类、价格、库存、高亮和分页”合并成一个可落地的商品搜索接口。完成后,你能把前端查询条件稳定地转换为 Elasticsearch DSL,并返回统一、可分页且带高亮片段的结果。
学习目标
- 设计商品搜索接口的请求参数和返回结构
- 用
bool查询组合全文检索与精确过滤 - 正确处理分页、高亮、空条件和边界参数
接口目标与查询链路
接口可以设计为 GET /api/products/search,接收 keyword、categoryId、minPrice、maxPrice、inStock、page 和 size。其中关键词进入评分查询,分类、价格和库存进入过滤条件,避免无关条件参与相关性计算。

建议使用从 1 开始的页码,并在后端限制 size 的最大值,例如 100。这样既符合前端习惯,也能避免一次请求拉取过多文档。
构建核心搜索请求
下面的请求演示全部条件同时存在时的 Elasticsearch DSL。将 <PORT> 替换为实际 Elasticsearch 端口;实际接口应按参数是否为空动态添加条件,而不是把空值写入查询。
curl -X POST "http://localhost:<PORT>/products/_search" -H "Content-Type: application/json" -d '{
"from": 0,
"size": 20,
"_source": ["id", "name", "subtitle", "brandName", "categoryId", "price", "stock"],
"query": {
"bool": {
"must": [
{
"multi_match": {
"query": "无线耳机",
"fields": ["name^3", "subtitle^2", "brandName"],
"type": "best_fields"
}
}
],
"filter": [
{ "term": { "categoryId": "1001" } },
{ "range": { "price": { "gte": 100, "lte": 500 } } },
{ "range": { "stock": { "gt": 0 } } }
]
}
},
"highlight": {
"pre_tags": ["<em>"],
"post_tags": ["</em>"],
"fields": {
"name": {},
"subtitle": {}
}
},
"sort": [
"_score",
{ "sales": { "order": "desc" } }
]
}'预期结果
HTTP 200
{
"hits": {
"total": { "value": <TOTAL>, "relation": "eq" },
"hits": [
{
"_source": {
"id": "<ID>",
"name": "<PRODUCT_NAME>",
"subtitle": "<SUBTITLE>",
"brandName": "<BRAND_NAME>",
"categoryId": "1001",
"price": <PRICE>,
"stock": <STOCK>
},
"highlight": {
"name": ["<em>无线耳机</em><OTHER_TEXT>"]
}
}
]
}
}<TOTAL>、<ID>、<PRICE>、<STOCK> 等值会随索引数据变化。_source 只包含声明字段;命中关键词的 name 或 subtitle 会出现在 highlight 中。
must 中的 multi_match 会影响 _score,字段后的 ^3、^2 表示权重。filter 只判断是否满足条件,通常可缓存,也不会改变相关性得分。排序先按 _score,再用销量打破同分结果。
后端参数转换规则
后端组装 DSL 时应遵循“有值才添加”的原则。关键词为空时可使用 match_all,分类为空时不添加 term,价格只传下限或上限时分别生成 gte 或 lte。
分页换算公式为 from = (page - 1) * size。当 page < 1 时修正为 1;当 size < 1 时使用默认值;当 size > 100 时截断为 100。普通列表页适合 from/size,超过约一万条的深分页应改用 search_after。
高亮字段可能不存在,因此返回对象要同时保留 _source.name 与 highlight.name。前端优先展示高亮值,没有高亮片段时再回退到原字段。
验收与常见错误
先分别验证只有关键词、只有过滤条件、全部条件和完全空条件四种请求。还要确认价格边界、无库存商品、最后一页以及超大页码不会导致接口异常。
常见错误是把分类和库存写进 must,导致无意义的评分计算;把 page 直接当作 from;或直接拼接用户输入生成 JSON。正确做法是使用客户端构建器或安全序列化,并在接口层限制页码、页大小和可查询字段。
本课总结
- 全文检索放入评分查询,分类、价格和库存放入过滤条件
- 分页、高亮和空参数都应在后端统一规范化
- 搜索接口必须同时验证结果正确性与边界行为
下一课预告
下一课将实现搜索词补全、品牌与分类聚合、价格区间统计,并处理筛选条件回显与聚合计数之间的关系。