XERJ 的 ES API 兼容性测试:从 61.3% 到 100% 的兼容层验证之路
XERJ 的 ES API 兼容性测试:从 61.3% 到 100% 的兼容层验证之路
本篇技术指南围绕 XERJ 仓库中的 ES API 兼容性测试报告与测试套件展开,讲解 XERJ 如何通过 :9200 端口以 Elasticsearch 线协议对外提供服务,如何用「同一请求、双引擎对照」的方式量化兼容度,以及兼容层从 61.3% 通过率演进到 100% 的完整过程。读完本文,你将掌握 ES 兼容测试的搭建方法、31 项核心用例的判定逻辑、失败类型背后的源码原因,以及仓库内更深一层的 YAML 一致性测试门禁的使用方式。
背景:为什么 XERJ 需要一条 ES 兼容 API
XERJ 自身拥有原生 REST API(默认 :8080),同时提供了第二条监听在 es_compat_port(默认 9200)的 Elasticsearch 兼容层。它的存在目的非常直接:让现有 Elasticsearch 客户端(Kibana、elasticsearch-py、各类导出与监控工具)不改代码、只改地址就能继续工作。
从源码结构看,这套兼容层集中在 engine/crates/xerj-api/src/es_compat.rs,而路由注册位于 engine/crates/xerj-api/src/router.rs,其中可以看到:
PUT /:index/_mapping/GET /:index/_mapping/GET /:index/_settings等索引管理路由POST /:index/_search(同时支持 GET 携带 body)POST /:index/_bulk与全局POST /_bulkGET /、GET /_cluster/health、GET /_cat/indices等集群与可观测性路由
端口配置在 engine/crates/xerj-common/src/config.rs 中定义:rest_port 默认 8080,es_compat_port 默认 9200,且启动时校验两者与 gRPC 端口互不冲突。
兼容层还处理了客户端握手的细节:GET / 会返回 8.13.0 的版本号并携带 X-Elastic-Product: Elasticsearch 响应头——这是 Kibana 与官方客户端在愿意连接节点之前检查的两道握手门槛;对于 OpenSearch 系客户端,则按 User-Agent 识别并回报 distribution: "opensearch" 与 2.11.0 版本号(见 es_compat.rs 中的 resolve_compat_version)。
测试套件结构:31 项用例如何「双引擎对照」
兼容性的量化验证来自 engine/tests/es_api_compat_test.py,它是一个不依赖任何 ES 客户端库、只用 Python 标准库 http.client 写成的对照测试:
- 同时向 XERJ(
localhost:9800)与参考 ES(127.0.0.1:9300)发送完全相同的请求; - 先比较 HTTP 状态码(允许 200 与 201 等价,都是成功语义),再对响应体执行自定义
check断言; - 每个用例按
PASS/FAIL记录,最终汇总并自动写入engine/reports/{时间戳}_es_api_compat.md报告。
测试的夹具数据由 seed() 函数构造:100 篇文档,包含 title(text)、status(keyword,取值 active/draft/archived)、count(integer)、price(float)、tags(keyword)、created(date)六种字段,按 3 个模组分布内容,随后对双端执行 POST /_bulk 灌入并 _refresh,保证文档可被搜索。索引 mapping 则在 setup() 中先建好:单分片、零副本。
2026-04-15 的基准运行:61.3% 通过率与 12 项失败
关联文档 engine/reports/2026-04-15T21-43-49_es_api_compat.md 记录了一次 31 项用例的运行结果:
| Metric | Count |
|---|---|
| PASSED | 19 |
| FAILED | 12 |
| Total | 31 |
| Pass rate | 61.3% |
值得注意的细节是:12 项失败中,有 11 项双方 HTTP 状态码都是 200,只是响应体内容检查不过;只有 POST /_bulk 是 xerj=200、es=400 的状态码差异。这意味着失败并非「接口 500/404」级别的崩溃,而是「返回了 ES 形状的 JSON,但命中结果与参考 ES 不一致」——这正是兼容层测试最容易暴露、也最隐蔽的一类问题。
失败清单如下:
- 查询 DSL 失败(5 项):
term query、match query、range query、bool query、exists query - 聚合失败(6 项):
terms agg、stats agg、avg agg、min/max agg、value_count agg、histogram agg - Bulk API 失败(1 项):
POST /_bulk,xerj=200 而 es=400
查询类失败的判定逻辑在测试脚本中非常直观,例如 term query 的 check 是 x["hits"]["total"]["value"] > 0——即 XERJ 对 {"term": {"status": "active"}} 返回了 0 命中,而参考 ES 能命中。这说明当时兼容层的查询解析/执行链路对 keyword 精确查询、全文 match、范围、布尔组合与 exists 的语义处理仍不完整。
失败根因的源码视角:查询 DSL 与聚合的解析链路
从源码看,查询 DSL 的解析入口是 engine/crates/xerj-query/src/parser.rs 中的 parse_query(见 parser.rs#L381),它按顶层键分发:
"match"→parse_match"term"→parse_term"range"→parse_range"exists"→parse_exists"ids"→parse_ids"bool"→parse_bool
同一文件内还有大量针对每种查询的单元测试(如 term 的 {"value": ..., "boost": 1.5} 形式、range 的 gte/lt 边界、bool 的 must/must_not/filter 组合),这些测试确认了查询 AST 的语义设计。2026-04-15 基准运行中查询类集体失败,从代码结构推断,更可能是当时引擎侧对 keyword 字段的倒排/词典匹配、分析器链或 hits.total 计算尚未与查询执行器打通,而非解析器不认识这些查询类型。
聚合失败同理。6 类聚合(terms/stats/avg/min/max/value_count/histogram)在 es_compat.rs 中聚合请求的解析与多索引合并 等处有专门实现(merge_single_bucket_agg、merge_metric_agg、merge_bucket_agg),但基准运行显示当时聚合响应里 aggregations 为空或桶数为 0,check 断言(buckets 长度 > 0、count > 0)自然失败。
POST /_bulk 的状态码差异则指向一个更具体的问题:测试脚本注释里写着「Send a proper NDJSON bulk body (not body=None which was the bug)」——说明此前某版本的测试用例本身以 body=None 发送 /_bulk,导致 ES 返回 400 而 XERJ 宽容地返回 200。这提醒我们:对照测试中的「参考端 400」也可能是测试夹具的 bug,而不是兼容层的缺陷。修正后的手工 bulk 用例改为携带 Content-Type: application/x-ndjson 的两行 NDJSON 体,双端均返回 200。
演进轨迹:61.3% → 100%
同一目录下留有多份按时间戳命名的后续报告,记录了兼容层的修复进程:
2026-04-15T21-43-26:19 通过 / 12 失败,61.3%2026-04-15T23-26-13:27 通过 / 4 失败,87.1%(bool、exists、6 类聚合修复;term/match/range 仍失败,bulk 仍为夹具问题)2026-04-15T23-36-17:29 通过 / 2 失败,93.5%(仅剩 match query 的 xerj total=0 与 bulk 状态码差异)2026-04-16T08-10-37:31 通过 / 0 失败,100.0%
其中 2026-04-15T23-36-17 报告给出了一个非常有价值的失败样本:match query — check failed (xerj total=0, es total=34)——XERJ 对 {"match": {"title": "search"}} 返回 0 命中,而 ES 命中 34 篇。这正是 text 字段全文检索语义缺失的典型症状,与 term(keyword 精确匹配)失败属于两条独立的修复线。到次日 08:10 的运行,31 项全部通过,说明 text 分析、keyword 匹配与聚合链路均已补齐。
需要说明的是,这份演进只是快照式见证,不构成性能或质量承诺;但作为兼容层开发过程的客观记录,它展示了「对照测试驱动修复」的工程方法。
更深一层的门禁:ES REST API YAML 一致性套件
31 项 Python 对照测试之外,仓库还维护了一套规模大得多的兼容性套件:engine/tests/es-compat-yaml/。它是 Elasticsearch 官方 rest-api-spec YAML 测试的精选子集(202 个文件),按 aggregations/、bulk/、cluster/、search/、scroll/、vectors/ 等目录组织,加上 XERJ 自写的 AI 原生用例。
运行器是 engine/tests/es-compat-yaml/src/main.rs,一个 Rust 二进制:
# 跑整个 search 目录
es-yaml-runner --url http://localhost:9200 --dir yaml/search
# 只跑单个文件
es-yaml-runner --url http://localhost:9200 --file yaml/bulk/10_basic.yml
它解析 YAML 中的 --- 分段:首个段为可选 setup,其后每个段是命名用例,包含 do(HTTP 动作,如 indices.create、bulk、search)与断言步骤(match、length、is_true、is_false、gte、lte)。一个典型的 term 查询用例见 yaml/search/171_term_query.yml,它甚至覆盖了空字符串 keyword 与 case_insensitive 参数这类边界行为。
该套件在 CI 中的门禁逻辑值得特别注意:运行器以退出码 1 表示有失败(见 main.rs#L92-L98 的注释——「CI 的 0 失败门禁消费这个退出码,否则回归的 PR 也会显示绿色,曾让 PR #23 在 1360→1345 通过数下降时仍然 SUCCESS」)。按仓库文档,一次完整运行可达到 1,371 / 1,374 用例通过(3 项跳过,门禁约束的是「0 失败」而非通过总数),并且明确说明运行器不校验错误行为(catch: 期望不生效),只走裸 HTTP、不在 CI 中驱动真实 ES 客户端库。
已知语义差异:调用成功但字节不同
兼容层文档(landing/docs/api-es-compat.html 与 landing/docs/migration-from-es.html)明确列举了「接口返回 ES 响应形状、但细节字节是 XERJ 自己的」几处差异,迁移时断言到细节的客户端需要留意:
- Scroll 是有界快照而非游标:
_search?scroll=在打开时就把全量结果物化进上下文,上限为 10,000 篇文档;查询的精确总数超过上限会被400 illegal_argument_exception拒绝,而不是分页后静默截断。elasticsearch-py的helpers.scan()、reindex 内部与多数导出工具都属于「整索引滚动」场景。替代路径是对唯一排序键使用search_after,该路径无上限。注意_id按字典序排序,"1000" < "999",游标必须从上一页最后一个sort值原样取出。 - BM25 分数是 XERJ 自己的:排序顺序符合查询意图,但精确
_score浮点值与 ES 不同,且会随后台合并移动集合统计而变化——与两个 ES 小版本之间的内部差异同类。断言精确分数的测试需要放宽。 - 默认
_source是紧凑形态:省略_source时引擎生成的<field>_vector与<field>_vector_chunks伴生字段不返回;显式_source: true才返回。 _cat表头:_cat/indices?v只输出数据行、无列头行,但列顺序与 ES 一致,位置解析仍可用、表头解析不可用。
如何复现:自己跑一遍兼容性对照
由于仓库是只读的,这里说明查看与运行方式,不改动仓库内容:
- 查看历史报告:直接阅读 engine/reports/ 目录下多份
*_es_api_compat.md,观察 61.3% → 87.1% → 93.5% → 100% 的演进; - 运行 Python 对照套件:需要本机同时有 XERJ(默认
localhost:9800,可在配置中调整端口)与参考 ES(默认127.0.0.1:9300),然后执行 engine/tests/es_api_compat_test.py,它会在engine/reports/生成新的时间戳报告;测试结束会清理索引与别名; - 运行 YAML 一致性套件:
cd engine/tests/es-compat-yaml && cargo run -- --url http://localhost:9200 --dir yaml/search(需先构建es-yaml-runner),或按 Cargo.toml 的依赖列表准备环境; - 手工冒烟:对照 api-es-compat.html 的 bulk 示例,用
curl直接向:9200发送 NDJSON bulk 与查询请求,比对响应形状。
小结
ES API 兼容层是 XERJ「让现有 ES 客户端无缝接入」的落地形态,而它是否名副其实,取决于一套可重复的对照验证体系。仓库提供了两个层次:31 项双引擎 Python 对照测试(覆盖集群、索引、文档 CRUD、查询、聚合、bulk、delete_by_query、别名)与 200+ 文件级的 ES 官方 YAML 一致性套件(CI 中以 0 失败为门禁)。2026-04-15 的 61.3% 基准报告则忠实地记录了兼容层尚未成熟时的真实状态——查询与聚合集体失败、bulk 出现夹具性状态码差异——随后在同一目录的后续报告中,通过率逐次爬升并最终达到 100%。对于准备迁移的团队,建议以「先跑套件、再验客户端依赖的具体行为」为原则:套件证明线协议的形状,而生产切换前仍需对自己依赖的每一个接口做一次双端 diff。