搜索API接口对接指南

本文档为搜索服务的使用方提供完整的API对接指南，包括接口说明、请求参数、响应格式和使用示例。

目录

1. 快速开始
2. 接口概览
3. 搜索接口
4. 响应格式说明
5. 常见场景示例

---

快速开始

基础信息

• Base URL: http://your-domain:6002 或 http://120.76.41.98:6002
• 协议: HTTP/HTTPS
• 数据格式: JSON
• 字符编码: UTF-8
• 请求方法: POST（搜索接口）

最简单的搜索请求

curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "芭比娃娃"
  }'

curl示例：带过滤与分页

curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo-tenant",
    "query": "芭比娃娃 AND 配件",
    "size": 5,
    "from": 10,
    "filters": {
      "vendor_keyword": ["乐高", "孩之宝"]
    },
    "sort_by": "min_price",
    "sort_order": "asc"
  }'

curl示例：开启调试与分面

curl -X POST "http://localhost:6002/search/" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "demo-tenant",
    "query": "芭比娃娃",
    "facets": ["category_keyword", "vendor_keyword"],
    "min_score": 0.2,
    "debug": true
  }'

---

接口概览

接口	HTTP Method	Endpoint
搜索	POST	/search/
搜索建议（框架，暂未实现）	GET	/search/suggestions
获取文档	GET	/search/{doc_id}
健康检查	GET	/admin/health

---

搜索接口

接口信息

• 端点: POST /search/
• 描述: 执行文本搜索查询，支持多语言、布尔表达式、过滤器和分面搜索

请求参数

完整请求体结构

{
  "tenant_id": "string (required)",
  "query": "string (required)",
  "size": 10,
  "from": 0,
  "filters": {},
  "range_filters": {},
  "facets": [],
  "sort_by": "string",
  "sort_order": "desc",
  "min_score": 0.0,
  "debug": false,
  "user_id": "string",
  "session_id": "string"
}

参数详细说明

参数	类型	必填	默认值	说明
tenant_id	string	Y	-	租户ID，用于隔离不同站点或客户的数据
query	string	Y	-	搜索查询字符串，支持布尔表达式（AND, OR, RANK, ANDNOT）
size	integer	N	10	返回结果数量（1-100）
from	integer	N	0	分页偏移量（用于分页）
filters	object	N	null	精确匹配过滤器（见下文）
range_filters	object	N	null	数值范围过滤器（见下文）
facets	array	N	null	分面配置（见下文）
sort_by	string	N	null	排序字段名（如 min_price, max_price, title）
sort_order	string	N	"desc"	排序方向：asc（升序）或 desc（降序）
min_score	float	N	null	最小相关性分数阈值
debug	boolean	N	false	是否返回调试信息
user_id	string	N	null	用户ID（用于个性化，预留）
session_id	string	N	null	会话ID（用于分析，预留）

过滤器详解

1. 精确匹配过滤器 (filters)

用于精确匹配或多值匹配（OR 逻辑）。

格式:

{
  "filters": {
    "category_keyword": "玩具",                    // 单值：精确匹配
    "vendor_keyword": ["乐高", "孩之宝"],          // 数组：匹配任意值（OR）
    "product_type_keyword": "益智玩具"              // 单值：精确匹配
  }
}

支持的值类型:

• 字符串：精确匹配
• 整数：精确匹配
• 布尔值：精确匹配
• 数组：匹配任意值（OR 逻辑）

常用过滤字段:

• category_keyword: 类目
• vendor_keyword: 品牌/供应商
• product_type_keyword: 商品类型
• tags_keyword: 标签

2. 范围过滤器 (range_filters)

用于数值字段的范围过滤。

格式:

{
  "range_filters": {
    "min_price": {
      "gte": 50,    // 大于等于
      "lte": 200    // 小于等于
    },
    "max_price": {
      "gt": 100     // 大于
    },
    "create_time": {
      "gte": "2024-01-01T00:00:00Z"  // 日期时间字符串
    }
  }
}

支持的操作符:

• gte: 大于等于 (>=)
• gt: 大于 (>)
• lte: 小于等于 (
• lt: 小于 (

注意: 至少需要指定一个操作符。

常用范围字段:

• min_price: 最低价格
• max_price: 最高价格
• compare_at_price: 原价
• create_time: 创建时间
• update_time: 更新时间

3. 分面配置 (facets)

用于生成分面统计（分组聚合），常用于构建筛选器UI。

简单模式（字符串数组）:

{
  "facets": ["category_keyword", "vendor_keyword"]
}

高级模式（配置对象数组）:

{
  "facets": [
    {
      "field": "category_keyword",
      "size": 15,
      "type": "terms"
    },
    {
      "field": "min_price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100},
        {"key": "100-200", "from": 100, "to": 200},
        {"key": "200+", "from": 200}
      ]
    }
  ]
}

分面配置参数:

• field: 字段名（必填）
• size: 返回的分组数量（默认：10，范围：1-100）
• type: 分面类型，terms（分组统计）或 range（范围统计）
• ranges: 范围定义（仅当 type='range' 时需要）

布尔表达式语法

搜索查询支持布尔表达式，提供更灵活的搜索能力。

支持的操作符:

操作符	描述	示例
AND	所有词必须匹配	玩具 AND 乐高
OR	任意词匹配	芭比 OR 娃娃
ANDNOT	排除特定词	玩具 ANDNOT 电动
RANK	排序加权（不强制匹配）	玩具 RANK 乐高
()	分组	玩具 AND (乐高 OR 芭比)

操作符优先级（从高到低）:

1. () - 括号
2. ANDNOT - 排除
3. AND - 与
4. OR - 或
5. RANK - 排序

示例:

"芭比娃娃"                    // 简单查询
"玩具 AND 乐高"               // AND 查询
"芭比 OR 娃娃"                // OR 查询
"玩具 ANDNOT 电动"            // 排除查询
"玩具 AND (乐高 OR 芭比)"      // 复杂查询

---

响应格式说明

标准响应结构

{
  "results": [
    {
      "product_id": "12345",
      "title": "芭比时尚娃娃",
      "handle": "barbie-doll",
      "description": "高品质芭比娃娃",
      "vendor": "美泰",
      "product_type": "玩具",
      "tags": "娃娃, 玩具, 女孩",
      "price": 89.99,
      "compare_at_price": 129.99,
      "currency": "USD",
      "image_url": "https://example.com/image.jpg",
      "in_stock": true,
      "variants": [
        {
          "variant_id": "67890",
          "title": "粉色款",
          "price": 89.99,
          "compare_at_price": 129.99,
          "sku": "BARBIE-001",
          "stock": 100,
          "options": {
            "option1": "粉色",
            "option2": "标准款"
          }
        }
      ],
      "relevance_score": 8.5
    }
  ],
  "total": 118,
  "max_score": 8.5,
  "facets": [
    {
      "field": "category_keyword",
      "label": "category_keyword",
      "type": "terms",
      "values": [
        {
          "value": "玩具",
          "label": "玩具",
          "count": 85,
          "selected": false
        }
      ]
    }
  ],
  "query_info": {
    "original_query": "芭比娃娃",
    "detected_language": "zh",
    "translations": {
      "en": "barbie doll"
    }
  },
  "suggestions": [],
  "related_searches": [],
  "took_ms": 45,
  "performance_info": null,
  "debug_info": null
}

响应字段说明

字段	类型	说明
results	array	搜索结果列表（ProductResult对象数组）
results[].product_id	string	商品ID
results[].title	string	商品标题
results[].price	float	价格（min_price）
results[].variants	array	变体列表（SKU列表）
results[].relevance_score	float	相关性分数
total	integer	匹配的总文档数
max_score	float	最高相关性分数
facets	array	分面统计结果
query_info	object	查询处理信息
took_ms	integer	搜索耗时（毫秒）

ProductResult字段说明

字段	类型	说明
product_id	string	商品ID（SPU ID）
title	string	商品标题
handle	string	商品URL handle
description	string	商品描述
vendor	string	供应商/品牌
product_type	string	商品类型
tags	string	标签
price	float	价格（min_price）
compare_at_price	float	原价
currency	string	货币单位（默认USD）
image_url	string	主图URL
in_stock	boolean	是否有库存（任意变体有库存即为true）
variants	array	变体列表
relevance_score	float	相关性分数

VariantResult字段说明

字段	类型	说明
variant_id	string	变体ID（SKU ID）
title	string	变体标题
price	float	价格
compare_at_price	float	原价
sku	string	SKU编码
stock	integer	库存数量
options	object	选项（颜色、尺寸等）

---

常见场景示例

场景1：商品列表页搜索

需求: 搜索"玩具"，按价格从低到高排序，显示前20个结果

{
  "query": "玩具",
  "size": 20,
  "from": 0,
  "sort_by": "min_price",
  "sort_order": "asc"
}

场景2：带筛选的商品搜索

需求: 搜索"玩具"，筛选类目为"益智玩具"，价格在50-200之间

{
  "query": "玩具",
  "size": 20,
  "filters": {
    "category_keyword": "益智玩具"
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  }
}

场景3：带分面的商品搜索

需求: 搜索"玩具"，获取类目和品牌的分面统计，用于构建筛选器

{
  "query": "玩具",
  "size": 20,
  "facets": [
    "category_keyword",
    "vendor_keyword"
  ]
}

场景4：多条件组合搜索

需求: 搜索"玩具"，筛选多个品牌，价格范围，并获取分面统计

{
  "query": "玩具",
  "size": 20,
  "filters": {
    "vendor_keyword": ["乐高", "孩之宝", "美泰"]
  },
  "range_filters": {
    "min_price": {
      "gte": 50,
      "lte": 200
    }
  },
  "facets": [
    {
      "field": "category_keyword",
      "size": 15
    },
    {
      "field": "min_price",
      "type": "range",
      "ranges": [
        {"key": "0-50", "to": 50},
        {"key": "50-100", "from": 50, "to": 100},
        {"key": "100-200", "from": 100, "to": 200},
        {"key": "200+", "from": 200}
      ]
    }
  ],
  "sort_by": "min_price",
  "sort_order": "asc"
}

场景5：布尔表达式搜索

需求: 搜索包含"玩具"和"乐高"的商品，排除"电动"

{
  "query": "玩具 AND 乐高 ANDNOT 电动",
  "size": 20
}

场景6：分页查询

需求: 获取第2页结果（每页20条）

{
  "query": "玩具",
  "size": 20,
  "from": 20
}

---

---

其他接口

搜索建议（框架）

• 端点: GET /search/suggestions
• 描述: 返回搜索建议（自动补全/热词）。当前为框架实现，接口和响应格式已经固定，可平滑扩展。

查询参数

参数	类型	必填	默认值	描述
q	string	Y	-	查询字符串（至少 1 个字符）
size	integer	N	5	返回建议数量（1-20）
types	string	N	query	建议类型（逗号分隔）：query, product, category, brand

响应示例

{
  "query": "芭",
  "suggestions": [
    {
      "text": "芭比娃娃",
      "type": "query",
      "highlight": "<em>芭</em>比娃娃",
      "popularity": 850
    }
  ],
  "took_ms": 5
}

请求示例

curl "http://localhost:6002/search/suggestions?q=芭&size=5&types=query,product"

---

即时搜索（框架）

• 端点: GET /search/instant
• 描述: 边输入边搜索，采用轻量参数响应当前输入。底层复用标准搜索能力。

查询参数

参数	类型	必填	默认值	描述
q	string	Y	-	搜索查询（至少 2 个字符）
size	integer	N	5	返回结果数量（1-20）

请求示例

curl "http://localhost:6002/search/instant?q=玩具&size=5"

---

获取单个文档

• 端点: GET /search/{doc_id}
• 描述: 根据文档 ID 获取单个商品详情，用于点击结果后的详情页或排查问题。

路径参数

参数	类型	描述
doc_id	string	商品或文档 ID

响应示例

{
  "id": "12345",
  "source": {
    "title": "芭比时尚娃娃",
    "min_price": 89.99,
    "category_keyword": "玩具"
  }
}

请求示例

curl "http://localhost:6002/search/12345"

---

管理接口

健康检查

• 端点: GET /admin/health
• 描述: 检查服务与依赖（如 Elasticsearch）状态。

{
  "status": "healthy",
  "elasticsearch": "connected",
  "tenant_id": "tenant1"
}

---

获取配置

• 端点: GET /admin/config
• 描述: 返回当前租户的脱敏配置，便于核对索引及排序表达式。

{
  "tenant_id": "tenant1",
  "tenant_name": "Tenant1 Test Instance",
  "es_index_name": "search_tenant1",
  "num_fields": 20,
  "num_indexes": 4,
  "supported_languages": ["zh", "en", "ru"],
  "ranking_expression": "bm25() + 0.2*text_embedding_relevance()",
  "spu_enabled": false
}

---

索引统计

• 端点: GET /admin/stats
• 描述: 获取索引文档数量与磁盘大小，方便监控。

{
  "index_name": "search_tenant1",
  "document_count": 10000,
  "size_mb": 523.45
}

---

数据模型

商品字段

字段名	类型	描述
product_id	keyword	商品 ID（SPU）
sku_id	keyword/long	SKU ID（主键）
title	text	商品名称（中文）
en_title	text	商品名称（英文）
ru_title	text	商品名称（俄文）
category_keyword	keyword	类目（精确匹配）
vendor_keyword	keyword	品牌/供应商（精确匹配）
product_type_keyword	keyword	商品类型
tags_keyword	keyword	标签
min_price	double	最低价格
max_price	double	最高价格
compare_at_price	double	原价
create_time	date	创建时间
update_time	date	更新时间
in_stock	boolean	是否有库存
text_embedding	dense_vector	文本向量（1024 维）
image_embedding	dense_vector	图片向量（1024 维）

不同租户可自定义字段名称，但最佳实践是对可过滤字段建立 *_keyword 版本，对可排序字段显式建 keyword/数值映射。

---

附录

常用字段列表

过滤字段（使用 *_keyword 后缀）

• category_keyword: 类目
• vendor_keyword: 品牌/供应商
• product_type_keyword: 商品类型
• tags_keyword: 标签

范围字段

• min_price: 最低价格
• max_price: 最高价格
• compare_at_price: 原价
• create_time: 创建时间
• update_time: 更新时间

排序字段

• min_price: 最低价格
• max_price: 最高价格
• title: 标题（字母序）
• create_time: 创建时间
• update_time: 更新时间
• relevance_score: 相关性分数（默认）

支持的分析器

分析器	语言	描述
chinese_ecommerce	中文	基于 Ansj 的电商优化中文分析器
english	英文	标准英文分析器
russian	俄文	俄文分析器
arabic	阿拉伯文	阿拉伯文分析器
spanish	西班牙文	西班牙文分析器
japanese	日文	日文分析器

字段类型速查

类型	ES Mapping	用途
TEXT	text	全文检索
KEYWORD	keyword	精确匹配、聚合、排序
LONG	long	整数
DOUBLE	double	浮点数
DATE	date	日期时间
BOOLEAN	boolean	布尔值
TEXT_EMBEDDING	dense_vector	文本语义向量
IMAGE_EMBEDDING	dense_vector	图片语义向量