xerj 的 Elasticsearch API 兼容性测试:31 项 REST 接口对照验证与 100% 通过之路
xerj 的 Elasticsearch API 兼容性测试:31 项 REST 接口对照验证与 100% 通过之路
xerj 是一个以「Elasticsearch 兼容」为对外契约的搜索引擎:它通过 9200 端口暴露 ES 8.x 线格式的 REST API,让现有 ES 客户端、Kibana、Logstash 可以直接换地址接入。本文以仓库内实际生成的兼容性测试报告 engine/reports/2026-04-15T23-33-02_es_api_compat.md 为核心,结合其测试脚本与源码实现,逐项拆解 31 个对照测试的判定逻辑、失败案例的根因,以及 xerj 如何从 61.3% 通过率走到 100%。读完你可以完整理解这套兼容性验证体系,并在本地复跑全部测试。
兼容性测试在验证什么
xerj 的定位决定了它的兼容层不是「支持一部分常见接口」这么简单,而是要回答一个可量化的问题:面对同一份请求,xerj 和真实 Elasticsearch 返回的结果是否一致?
为此,仓库维护了两套互补的验证手段:
- HTTP 级双引擎对照测试:脚本 engine/tests/es_api_compat_test.py 同时向 xerj(
localhost:9800)和真实 ES 实例(127.0.0.1:9300)发起同一请求,比较状态码与响应内容,并把结果写成带时间戳的 Markdown 报告存入 engine/reports/。 - 引擎级 Rust 一致性套件:engine/crates/xerj-engine/tests/es_compat_tests.rs(共 2446 行)把官方 ES YAML 测试语义翻译成对引擎的直接 Rust 调用,覆盖 Index API、Search API、Bulk API、Delete API、Count API、Cluster/health API。
两套测试共享同一份索引与文档数据:api_compat_test 索引带 6 个字段的 mapping(title text、status keyword、count integer、price float、tags keyword、created date),种子阶段通过 /_bulk 写入 100 条文档,再 _refresh 强制可见,保证两侧在完全相同的语义环境下被比对。
31 项测试的完整构成
以目标报告 2026-04-15T23-33-02_es_api_compat.md 为例,31 项测试按 API 面分为八组:
| 分组 | 测试项 | 报告结果 |
|---|---|---|
| Cluster APIs | GET /、GET /_cluster/health、GET /_cat/indices |
3/3 通过 |
| Index Management | PUT index with mapping、GET /{index}、GET /{index}/_mapping、GET /{index}/_settings |
4/4 通过 |
| Document CRUD | GET /_count、GET /{index}/_doc/{id}、PUT /{index}/_doc/{id}、DELETE /{index}/_doc/{id} |
4/4 通过 |
| Search | match_all size=0、match_all size=10、term、match、range、bool、exists、ids、sort by count、_source filtering |
7/10 通过 |
| Aggregations | terms、stats、avg、min/max、value_count、histogram | 6/6 通过 |
| Bulk API | POST /_bulk |
失败 |
| Delete by query | POST /_delete_by_query |
通过 |
| Aliases | POST /_aliases add、GET /test_alias/_count |
2/2 通过 |
这 31 项不是随机挑选的,而是覆盖了 ES 客户端日常最常用、最能决定「换引擎后还能不能继续跑」的接口面:集群可观测、索引生命周期、文档增删改查、查询 DSL 主流子句、聚合家族、批量写入、按查询删除与别名切换。
测试脚本的判定逻辑
理解报告里每个 PASS/FAIL 的含义,需要先读懂 es_api_compat_test.py 的核心函数 test()(第 44 行起):
def test(name, method, path, body=None, check=None, headers=None):
"""Run a request against both engines, compare."""
xs, xj, xd = req(*XERJ, method, path, body, headers) # xerj 侧
es, ej, ed = req(*ES, method, path, body, headers) # ES 侧
passed = True
# 1) 状态码比对:200 与 201 视为等价(都算成功)
if xs != es:
if not ({xs, es} <= {200, 201}):
passed = False
notes.append(f"status: xerj={xs} es={es}")
# 2) 自定义断言:由调用方传入的 check 回调决定内容一致性
if check and xj is not None:
check_result = check(xj, ej)
if check_result is not None and not check_result:
passed = False
notes.append(f"check failed (xerj total={xval}, es total={eval_})")
...
results.append((name, status, xs, es, detail))
这套判定规则有两个值得注意的细节:
- 状态码允许 200/201 互认。例如
PUT /{index}/_doc/{id}在 xerj 返回 200、ES 返回 201 时仍判定 PASS——两者在 ES 语义里都是写入成功(ES 对新建文档返回 201 Created),报告的 ES HTTP 列如实记录,但不计入失败。 - 内容一致性由每项的 check 回调决定,且失败时自动提取两侧
hits.total.value写入 Notes,这正是报告中(xerj total=0, es total=34)这类诊断信息的来源。例如 term query 的断言是x["hits"]["total"]["value"] > 0:只要 xerj 搜出 0 条而 ES 搜出 34 条,就立刻暴露「xerj 对这批种子数据压根没检索到结果」的问题。
脚本末尾 write_report()(第 274 行起)自动统计 PASS/FAIL/TOTAL,计算通过率,并把完整运行日志一并写入报告,生成 ### Summary、## Results、## Failures、## Log 四段结构。
报告实例解读:87.1% 那一轮的 4 个失败
目标报告记录的是一次通过率为 87.1%(27 PASS / 4 FAIL)的运行。四个失败逐项分析:
| 失败项 | 现象 | 判定原因 |
|---|---|---|
term query |
xerj=200, es=200 | check failed (xerj total=0, es total=34) |
match query |
xerj=200, es=200 | check failed (xerj total=0, es total=34) |
range query |
xerj=200, es=200 | check failed (xerj total=0, es total=40) |
POST /_bulk |
xerj=200, es=400 | status: xerj=200 es=400 |
三个查询类失败有一个共同特征:HTTP 状态码两侧都是 200,但 xerj 的命中数恒为 0。对照种子数据(100 条文档中 status: "active" 约 34 条、title 含 "search" 约 34 条、count 落在 [100,500) 的 40 条),可以推断这两轮运行中 xerj 侧写入后的文档并未进入可检索状态——match_all 能命中而 term/match/range 命中 0,属于典型的分词/倒排索引与写入可见性问题,而不是查询 DSL 解析失败(否则会直接 4xx)。
POST /_bulk 的失败则暴露了另一个典型问题:测试脚本早期版本用 body=None 调 /_bulk,即向 ES 发送了没有 NDJSON 实体的请求,ES 依规范返回 400,而 xerj 此时宽容地返回了 200。这不是 xerj 实现缺陷,而是「宽容度不一致」——从 ES 客户端视角看,一个该被拒绝的畸形请求被静默接受了。测试脚本为此专门在 Bulk API 段写明了注释 # Send a proper NDJSON bulk body (not body=None which was the bug),并改为手工构造规范的两行 NDJSON(action 行 + 文档行)。
从 61.3% 到 100%:报告序列记录的修复轨迹
engine/reports/ 下保留了同一天内多轮运行的报告,它们本身就是一份完整的排障时间线:
| 报告时间 | 通过率 | 失败数 | 状态 |
|---|---|---|---|
| 2026-04-15T21-43-26 | 61.3% | 12 | 查询类 + 全部聚合 + bulk 失败 |
| 2026-04-15T23-26-13 | 87.1% | 4 | term/match/range + bulk |
| 2026-04-15T23-33-02 | 87.1% | 4 | term/match/range + bulk(目标文档) |
| 2026-04-15T23-36-17 | 93.5% | 2 | match + bulk |
| 2026-04-16T01-53-47 | 96.8% | 1 | match |
| 2026-04-16T02-10-43 | 100.0% | 0 | 全绿 |
| 2026-04-16T03-08-13 | 100.0% | 0 | 全绿 |
| 2026-04-16T08-10-37 | 100.0% | 0 | 全绿 |
早期 61.3% 那一轮,term、match、range、bool、exists、以及全部六项聚合集体失败,说明当时查询解析或索引可见性存在系统性问题;随着 87.1% → 93.5% → 96.8% 逐轮收敛,剩余的失败项逐个被消灭(term、range 修复后,match 仍残留,最终在 100% 轮全部消除)。同一天的 8 份报告相互印证,展示了「HTTP 对照测试 → 定位差异 → 修复 → 复测」的闭环,这也是把测试报告留在仓库里的价值所在。
兼容层源码级纵深
报告验证的是行为,行为则来自 engine/crates/xerj-api/src/router.rs 中 build_es_compat_router 注册的路由表与 engine/crates/xerj-api/src/es_compat.rs(逾 4.6 万行)里的处理器实现:
// engine/crates/xerj-api/src/router.rs
.route("/", get(es_compat::es_info))
.route("/_cluster/health", get(es_compat::cluster_health))
.route("/_cat/indices", get(es_compat::cat_indices))
.route("/_bulk", post(es_compat::global_bulk))
.route("/:index/_count", get(es_compat::count_index))
.route("/_search", post(es_compat::search_all))
.route("/:index/_search", post(es_compat::search))
.route("/:index/_bulk", post(es_compat::bulk_ops))
.route("/:index/_delete_by_query", post(es_compat::delete_by_query))
.route("/_aliases", post(es_compat::post_aliases).get(es_compat::get_aliases))
报告中的每个测试项都能在路由表中找到对应条目。几个关键处理器的实现要点:
search(es_compat.rs 第 9757 行):直接对应报告里 10 项 Search 测试。它通过Box::pin包装search_impl的巨型 future(源码注释明确说明这是 load-bearing 的做法,防止 wrapper 内联复制第二份 async 状态导致栈溢出),并接入脚本故障捕获机制,把 Painless 脚本超限映射为结构化错误响应。global_bulk(es_compat.rs 第 17342 行):即报告的POST /_bulk测试项。它解析 URL 上的_source/_source_includes/_source_excludes参数并转换为引擎能消费的_source过滤形状,随后委托process_bulk_body处理 NDJSON 流。post_aliases(es_compat.rs 第 22237 行):对应POST /_aliases add测试。它先解析通配符add.index再应用动作——源码注释记录了历史 bug:早期版本把通配符文本直接当作别名目标,导致POST /_aliases对.xerj-memory-*这类命名空间返回acknowledged: true却留下悬空别名;现在 ES 语义是通配符解析不到目标就 404index_not_found_exception。delete_by_query(es_compat.rs 第 27911 行):支持把查询扇出到多索引别名的每个成员(别名过滤条件会 AND 进查询),先做一次前置校验使畸形 body 立即 400,再按wait_for_completion参数决定同步执行还是注册为可轮询的异步任务。
HTTP 请求在兼容层的完整调用链在 engine/README.md 中有官方描述:
HTTP Request
→ xerj-api (Axum handler, es_compat.rs)
→ xerj-query parse_request() — raw JSON → SearchRequest (QueryNode tree)
→ Engine::get_index() — looks up named index
→ Index::search()
→ memtable scan (in-memory BM25 via FtsMemtable)
→ segment scan (on-disk FTS via FtsIndexReader + BM25)
→ doc_matches_query() for term-level / geo queries
→ run_aggs() for aggregations
→ apply_source_filter(), apply_highlight()
→ SearchResult → JSON response
这解释了报告的覆盖面为何恰好落在 Search 与 Aggregations 上:这两组测试验证的正是从 DSL 解析到 BM25 打分、聚合执行再到响应序列化的整条链路。
此外,仓库还维护着一套更深层的 conformance runner——engine/tests/es-compat-yaml(212 个 .yml 文件),按 engine/README.md 的说明,这是把官方 ES YAML 测试套件翻译为引擎级断言的地方,与 Rust 套件 es_compat_tests.rs 共同构成比 HTTP 对照更细粒度的语义验证层。
兼容性边界:报告之外必须知道的事实
对照报告只证明「这些接口行为一致」,不代表无限兼容。仓库文档明确划定的边界包括:
- 兼容承诺的测试基准:官方文档 landing/docs/api-es-compat.html 写明「What the compatibility promise is tested against — ES version, conformance suite, clients」统一在迁移指南的 compatibility boundary 一节说明。
- 不支持的调用返回结构化错误:
not_supported_yet,而不是 500,保证客户端能识别「暂不支持」与「服务故障」的区别。 - scroll 是有限快照而非游标:
_search?scroll=会在打开时物化整个结果集,超过 10,000 文档的快照窗口直接以400 illegal_argument_exception拒绝(不会静默截断);需要读取任意大结果集应改用search_after+ 唯一排序键,该路径无上限。这是指向导出/备份工具时最重要的一个差异。 rerank是 xerj 的私有扩展:它是_search请求体里 ES 没有的顶层键,把问题与窗口内命中文本发送给第三方相关性判分器重排命中;未配置 provider 时请求返回 503,且 scroll、size: 0等场景会被 400 拒绝。- 引擎差异:从源码看,xerj 是本地单节点引擎,
/_cluster/health的节点数在非集群模式下恒为 1;其文档 ID 使用 UUID(36 字符带连字符),而 ES 自动生成的是 URL-safe base64 的 22 字符 ID——es_compat_tests.rs的注释明确说明只断言「非空且形似合法」,不要求与 ES 字节级一致。
在本地复跑这套测试
测试脚本 engine/tests/es_api_compat_test.py 是纯 Python 标准库实现(http.client + json),不依赖第三方包,按 __main__ 直接执行:
# 1. 启动 xerj(ES 兼容端口默认 9200;测试脚本固定连 localhost:9800,
# 可通过 --bind 与端口配置调整,见 engine/xerj.default.toml 的
# es_compat_port / rest_port)
# 2. 启动一个参考 Elasticsearch 实例于 127.0.0.1:9300
# 3. 运行对照测试
python3 engine/tests/es_api_compat_test.py
脚本会自动在 engine/reports/ 下生成 YYYY-MM-DDTHH-MM-SS_es_api_compat.md 报告(路径由第 14 行的 REPORT_DIR 计算,落在测试文件所在目录的上一级 reports/ 中),并实时打印每项 PASS/FAIL。执行完毕后对照报告的 ## Summary 与 ## Failures 即可判断当前构建的兼容状态;若想检查更深层的语义一致性,可再运行 Rust 套件:
cd engine && cargo test -p xerj-engine --test es_compat_tests
测试脚本对运行环境有明确前提:需要一台可达的参考 ES(报告头部固定记录 xerj: localhost:9800 与 ES: 127.0.0.1:9300),没有参考集群时脚本无法给出对照结论——这一点在评估结果时务必注意。
结语
engine/reports/ 下的 ES API 兼容性报告是一份「可复现、可追溯、可演进」的工程资产:31 项测试覆盖从集群健康到聚合统计的完整接口面,双引擎同请求对照的判定规则让每个差异都变成可定位的 (xerj total=N, es total=M),而同一日期的多轮报告则忠实记录了兼容性从 61.3% 收敛到 100% 的修复轨迹。对于计划把现有 ES 客户端迁到 xerj 的团队,先用这套测试确认自己的核心调用面,再对照 landing/docs/api-es-compat.html 中列出的接口清单与 scroll/rerank 等边界差异,就能把「换引擎」的风险压缩到一个可量化的验证动作里。