xerj 的 Elasticsearch API 兼容性测试:31 项接口矩阵、失败定位与 100% 通过之路

原创2026-10-16 18:46:272,147 阅读
文章标签:人工智能搜索引擎本地部署后端MCP 服务

xerj 的 Elasticsearch API 兼容性测试:31 项接口矩阵、失败定位与 100% 通过之路

本篇技术指南围绕 xerj 仓库中的一份真实测试报告 2026-04-15T23-28-36_es_api_compat.md 展开:它记录了一次对 xerj 的 ES 兼容 API 与真实 Elasticsearch 集群的逐项对拍测试,31 项接口中有 27 项通过、4 项失败,通过率 87.1%。读完本文,你将掌握这套兼容性测试的完整方法、测试矩阵的构成、失败项的根因分析,以及 xerj 如何在次日将通过率推进到 100%,并理解兼容层在源码层面的实现原理——包括端口 9200 的监听、版本号广告、501 结构化拒绝等设计。

为什么需要"ES API 兼容性测试"

xerj 的核心承诺之一是"Elasticsearch 兼容"——让现有的 ES 客户端(Kibana、Logstash、elasticsearch-py、各类导出工具)只改一个 URL 就能继续工作。这在架构上意味着:xerj 必须用自己的 Rust 引擎,在 HTTP 层"翻译"出 ES 8.x 的线协议(wire format),包括路由、请求体、响应 JSON 形状乃至错误信封。

兼容不是"能响应就行",而是"与 ES 行为一致"。为此,仓库内置了一个对拍式测试套件 es_api_compat_test.py:对同一请求同时发给 xerj 与一个真实 ES 集群,比较 HTTP 状态码和响应内容,把结果写成带时间戳的报告。这份 2026-04-15 的报告就是该套件的输出之一(报告的生成逻辑见 write_report 函数)。

从源码结构看(es_compat.rs 模块头部注释明确写着 "Elasticsearch-compatible REST API handlers (port 9200)"),兼容层作为独立的 Axum 路由器挂载在 9200 端口上,与原生 REST API(8080)和 gRPC(8081)并行存在——三者端口互不相同是配置校验的硬性约束(见 config.rs)。

测试环境与执行方式

报告头部记录了对拍双方:

角色 地址 说明
xerj localhost:9800 被测节点,ES 兼容端口
Elasticsearch 127.0.0.1:9300 参照实现,用于行为对齐

测试脚本中对应常量为 XERJ = ("localhost", 9800)、ES = ("127.0.0.1", 9300)、INDEX = "api_compat_test"(见 es_api_compat_test.py)。值得说明的是:脚本里 ES 地址端口是 9300,这与仓库中 battle_real.sh 之类脚本使用的 9200 不同——说明测试集群的 ES 实例被配置为在非标准端口提供服务,避免与 xerj 的 9200 监听端口冲突。

测试的核心机制是 req() 与 test() 两个函数(es_api_compat_test.py):

  • req() 用标准库 http.client 向目标发送 HTTP 请求,统一返回 (status, json, raw) 三元组;
  • test() 把同一请求分别发给 xerj 和 ES,先比较状态码,再执行可选的 check 回调对响应内容做断言;
  • 状态码判定有例外规则:200 与 201 视为等价(都表示成功),这正是后续 PUT /{index}/_doc/{id} 测试在 xerj=200、ES=201 时仍判 PASS 的原因;
  • 断言失败时,报告会自动带上 hits.total.value 字段用于调试(见 es_api_compat_test.py),这就是失败记录里 "xerj total=0, es total=34" 这类信息的来源。

测试流程按组执行:Cluster APIs → Index Management → Document CRUD → Search → Aggregations → Bulk → Delete by query → Aliases,最后清理索引。数据准备阶段会向两端各批量灌入 100 条文档并强制 _refresh,保证后续搜索类断言基于可见数据(seed 函数)。

31 项测试矩阵:每一组在测什么

报告中的 31 项测试覆盖了 ES 客户端最常用的接口面。按报告 Log 的分组整理如下:

集群类(3 项)

  • GET /:根路径信息(版本、集群名、tagline),客户端连接校验的第一站
  • GET /_cluster/health:集群健康状态
  • GET /_cat/indices:索引列表(?format=json 形式)

索引管理(4 项)

  • PUT index with mapping:带 settings 与 mappings 建索引
  • GET /{index}、GET /{index}/_mapping、GET /{index}/_settings:读取索引元数据

文档 CRUD(4 项)

  • GET /_count:文档计数(断言 ≥100)
  • GET /{index}/_doc/{id}:按 ID 取文档(断言 found=true)
  • PUT /{index}/_doc/{id}:按 ID 写文档
  • DELETE /{index}/_doc/{id}:按 ID 删文档

搜索(10 项)

  • match_all size=0 / size=10:全量匹配与分页
  • term query、match query、range query、bool query、exists query、ids query:六种核心查询 DSL
  • sort by count:字段排序
  • _source filtering:源字段裁剪

聚合(6 项)

  • terms agg、stats agg、avg agg、min/max agg、value_count agg、histogram agg:六种最常用聚合

批量与运维(4 项)

  • POST /_bulk:NDJSON 批量写入
  • POST /_delete_by_query:按查询删除
  • POST /_aliases add + GET /test_alias/_count:别名管理及通过别名计数

测试数据设计也有讲究:100 条文档的 title 在 "search"、"indexing"、"analysis" 三个词间循环,status 在 active/draft/archived 间循环,count 为 i*10——这样 term、match、range 各有稳定的命中集(34、34、40),与失败报告中记录的数字一一对应。

失败项深度分析:4 个 FAIL 说明了什么

报告的 Failures 一节清晰列出了 4 个失败:

测试 xerj ES 现象
term query 200 200 check failed(xerj total=0, es total=34)
match query 200 200 check failed(xerj total=0, es total=34)
range query 200 200 check failed(xerj total=0, es total=40)
POST /_bulk 200 400 status: xerj=200 es=400

前三个失败的共同特征是:HTTP 状态码一致(都是 200),但 xerj 返回的命中数为 0。结合更早一份报告 2026-04-15T21-43-26_es_api_compat.md(当时 12 项失败,bool/exists 和全部 6 个聚合也失败),可以推断这是测试脚本演进中的阶段性问题——比如种子数据尚未对 xerj 生效、刷新时序、或搜索解析层的缺口。到 23:28 这份报告时,bool/exists 与全部聚合已经恢复 PASS,剩下的 3 个查询类失败是同类问题的残余。

第四个失败 POST /_bulk 性质不同:xerj 返回 200 而 ES 返回 400。这正是脚本注释里点破的 bug——早期版本把 bulk 请求体传成了 body=None(见 es_api_compat_test.py 的注释 "Send a proper NDJSON bulk body (not body=None which was the bug)")。ES 对空体/错误格式返回 400,而 xerj 容忍了它,于是出现状态码分歧。测试脚本随后改为手动构造合法的 NDJSON bulk 请求体并单独记录 PASS——这解释了为何同一份报告里既有 FAIL 行又有手工 PASS 的 Log 行。

从 87.1% 到 100%:修复路径与终局报告

第二天上午的报告 2026-04-16T08-10-37_es_api_compat.md 给出了最终结果:31/31 全部 PASS,通过率 100.0%。

对比两份报告可以还原修复路径:

  1. term / match / range 查询返回 0 命中:随后的报告全部恢复 PASS,说明这些查询在兼容层与引擎的搜索路径上已经打通。该路径在源码中的对应实现是 router.rs 注册的 /:index/_search(POST/GET 双方法)→ es_compat::search 处理器,再经 xerj_query::parse_request(es_compat.rs)解析 ES 查询 DSL 后交给引擎执行。
  2. POST /_bulk 状态码分歧:这是测试脚本自身的 bug 而非产品缺陷,修正请求体后即通过。产品端的 bulk 入口在 router.rs(/_bulk → global_bulk)与 router.rs(/:index/_bulk → bulk_ops)。

值得强调的是,兼容性验收不只靠这一个 Python 脚本。仓库中还有两类更重的验证:一是 es-compat-yaml 目录下 214 个 YAML 用例(对应 ES 官方的 YAML REST 测试风格);二是 battle_real.sh 这样的"真人对打"脚本——对同一批 curl 命令分别打到 ES 与 xerj,逐项比对 _id、result、_source、计数与耗时。多层验证共同构成了兼容承诺的证据链。

兼容层的源码级设计:不止"能响应"

从 es_compat.rs(4.6 万行级的主实现文件)可以提炼出兼容层几个关键设计决策:

版本号广告:默认伪装成 ES 8.13.0

客户端在连接时都会请求 GET / 并读取 version.number 来决定走哪套行为分支。xerj 的 EsVersion 默认值 广告 8.13.0(lucene_version 报 9.10.0、minimum_wire_compatibility_version 报 7.17.0),并保证 tagline 严格等于 "You Know, for Search"——源码注释指出这是客户端硬断言字段。集群名固定为 xerj,UUID 使用稳定伪值 xerj-cluster-0000-...(responses.rs)。

OpenSearch 客户端自动识别

兼容层还处理了 OpenSearch 系的客户端:通过 User-Agent 头判断调用方是否属于 OpenSearch 生态(opensearch-py、opensearch-js 等),若是则返回带 distribution: "opensearch" 字段的版本块,版本号回落到经实证验证的 2.11.0(见 es_compat.rs 的详细注释)。也可通过 --compat-version / --compat-distribution 显式覆盖。

结构化的 501:拒绝也要符合 ES 错误信封

报告对应的早期版本用"返回 200 + 假成功体"来敷衍未实现端点,这是极差的客户端体验。后续引入的 stub.rs 提供 not_implemented_yet() 帮助函数:返回 501 Not Implemented,错误体为 ES 形状的 {"error": {"type": "not_implemented_exception", ...}, "status": 501},并附带 Retry-After: 0 头防止客户端按时钟重试。每个拒绝都会说明该功能计划落地的里程碑版本(见 stub.rs)。

两个扩展点:rerank 与有界 scroll

兼容层不是僵硬的镜像,文档 api-es-compat.html 明确列出两个 xerj 特有行为:

  • rerank 扩展:_search 请求体顶部可携带 rerank 块,把 top-N 命中的文本送到第三方相关性裁判重新排序——这是 ES 没有的键,也是唯一在搜索时把文档文本发往节点外的功能(需运维显式配置 [rerank] 密钥后才生效);
  • scroll 是有界快照:_search?scroll= 在开卷时就把整个结果集物化进 scroll 上下文,上限为 10,000 条;精确总数超限的查询会被 400 拒绝(illegal_argument_exception)而不是静默截断。超大规模导出建议改用 search_after + 唯一排序键的无界路径。

如何在自己的环境复现这套测试

复现步骤(对应 es_api_compat_test.py 的硬编码约定):

  1. 启动一个真实 Elasticsearch,监听 127.0.0.1:9300;
  2. 启动 xerj,并让 ES 兼容端口监听 localhost:9800(测试脚本写死了这两个地址;生产默认端口见下);
  3. 执行 python3 engine/tests/es_api_compat_test.py;
  4. 脚本自动在 engine/reports 下生成 {时间戳}_es_api_compat.md 报告。

日常部署中,xerj 的 ES 兼容端口默认是 9200(<a href="https://link.gitcode.com/i/075f4d257f6f9c6b59d1c48edbb5ab7a" target="_blank">server] es_compat_port = 9200,见 [xerj.default.toml),与原生 REST 的 8080、gRPC 的 8081 隔离。最小启动配置是(engine/README.md):

[server]
data_dir = "/var/lib/xerj"
es_compat_port = 9200

[auth]
enabled = false   # 注意:默认是 true,此处是显式关闭,仅限可信网络/本地开发

也可以直接 ./xerj --data-dir ./data --insecure 启动开发节点,然后:

curl -X PUT http://localhost:9200/my-index
curl -X PUT http://localhost:9200/my-index/_doc/1 \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello","content":"World"}'
curl -X POST http://localhost:9200/my-index/_search \
  -H 'Content-Type: application/json' \
  -d '{"query":{"match":{"content":"world"}}}'

在 api-es-compat.html 中可查到完整的 ES 兼容端点清单(建索引、增删改查文档、bulk、scroll、delete_by_query、cluster health、cat 系列等),以及"未支持调用返回结构化 501"的边界约定。

小结:兼容性是用对拍测出来的

xerj 的 ES API 兼容不是一句口号,而是一套可重复执行的证据链:以真实 ES 为参照的对拍脚本(es_api_compat_test.py)、逐日留痕的报告(engine/reports 下的多份 *_es_api_compat.md)、214 个 YAML 用例(es-compat-yaml)、以及 battle 系列脚本。2026-04-15 的 87.1%(27/31)到次日 100%(31/31)的变化,既记录了测试脚本自身(bulk 请求体)的修正,也记录了查询与聚合路径的补齐。对打算把现有 ES 客户端指向 xerj 的团队而言,这套报告就是"哪些能用、边界在哪"的最直接依据。

登录后查看全文
xerj