xerj 的 Elasticsearch API 兼容性测试:31 项 REST 接口对照验证与 100% 通过之路

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

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 返回的结果是否一致?

为此,仓库维护了两套互补的验证手段:

  1. HTTP 级双引擎对照测试:脚本 engine/tests/es_api_compat_test.py 同时向 xerj(localhost:9800)和真实 ES 实例(127.0.0.1:9300)发起同一请求,比较状态码与响应内容,并把结果写成带时间戳的 Markdown 报告存入 engine/reports/。
  2. 引擎级 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 语义是通配符解析不到目标就 404 index_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 等边界差异,就能把「换引擎」的风险压缩到一个可量化的验证动作里。

登录后查看全文
xerj