Sapling Mononoke ScmQuery 服务架构解析：统一 Thrift 查询 API 的设计与实现

• 开发工具
• CLI
• 后端

ScmQuery 是 Sapling 仓库中 Mononoke 服务器体系内的一个 Thrift 服务，为读取源代码仓库提供统一查询 API——覆盖文件内容读取、提交历史查询、差异计算与仓库元数据检索等操作。本文基于 ARCHITECTURE.md 及其六个功能特性文档，结合仓库内 scsc 客户端的端到端测试代码，剖析该服务的组件划分、请求数据流、API 面与不变量约束，帮助读者掌握这套"统一仓库查询层"的架构思路与实现要点。

系统定位：为什么需要 ScmQuery

ScmQuery 是 Mononoke 服务器生态中的查询服务，核心目标是把对源代码仓库的只读查询能力收敛为一个统一的 Thrift 接口。无论底层仓库是 Mercurial（hg）还是 Git，客户端都可以通过同一套 ScmQueryService 接口完成"读文件、查历史、算 diff、取元数据"等操作，而无需关心底层仓库类型差异。

从系统职责看，它处于客户端与 Mononoke 核心 API 之间：

• 上游：接收 Thrift 请求（仓库名、scm_type、rev 格式、路径等参数）；
• 下游：通过 Mononoke API（RepoContext、ChangesetContext 等）完成实际查询；
• 输出：将 Mononoke 类型转换为 Thrift 响应类型返回给调用方。

这一设计与 Sapling 中其他服务的定位一致：服务端负责把 Mononoke 的领域模型翻译成稳定的、面向客户端的协议形态。

技术栈与组件划分

技术栈

从架构文档看，ScmQuery 采用如下技术栈：

其中 fb303 是 Meta 的标准服务治理框架（提供健康检查、计数指标等），ServiceFramework 负责把 Thrift 服务挂载到 Mononoke 服务器进程中。

三个核心组件

架构文档将服务拆分为三个职责清晰的组件：

1. thrift_handler
   • 职责：实现 ScmQueryService 与 ScmWriteService 两套 Thrift 接口；接收 Thrift 请求、校验参数、委托给核心查询逻辑。
   • 依赖：core、mononoke_api。
2. core
   • 职责：全部 scmquery 操作的核心业务逻辑——把 Thrift 请求类型翻译为 Mononoke API 调用，再把结果格式化为 Thrift 响应类型。
   • 依赖：mononoke_api。
3. server
   • 职责：服务器二进制装配——fb303、ServiceFramework、CLI 参数解析、repo factory 初始化；将 thrift_handler 与 Mononoke 仓库上下文（repo context）接好线。
   • 依赖：thrift_handler、mononoke_app。

这种"handler 薄校验 + core 业务翻译 + server 装配"的分层，与 Mononoke 其他服务（如 SCS）的惯用结构一致：handler 层保持轻薄，把可测试、可复用的查询逻辑下沉到 core。

请求数据流

一次典型的只读查询请求按照以下 7 步完成：

1. 客户端向 ScmQueryService 发送 Thrift 请求；
2. thrift_handler校验请求参数（repo 名、scm_type、rev 格式）；
3. thrift_handler调用 core 模块中的对应函数；
4. core通过 Mononoke API 把 repo 解析为RepoContext，把 rev 解析为ChangesetContext；
5. core执行具体操作（如路径查找、blame、diff）；
6. core将 Mononoke 类型转换为 Thrift 响应类型；
7. thrift_handler向客户端返回响应。

值得注意的关键转换发生在第 4 步：repo → RepoContext、rev → ChangesetContext。这是 core 层最核心的职责——它把 Thrift 世界中"字符串形态的仓库名与修订号"翻译成 Mononoke 领域模型，后续操作全部建立在两个 Context 之上。这也是为什么架构文档将"所有操作必须经由 MononokeAPI 库完成"列为首要不变量。

API 面：六大操作组

服务实现 ScmQueryService Thrift 接口（只读操作），按功能分为六组。以下结合 features 目录下的特性文档逐一展开。

1. 文件内容操作

对应 001-file-content-operations.md：

实现要点：

• cat_v2的返回内容应与 Mononoke 的file_contentAPI 一致；
• blame_v2需返回正确的逐行提交归属；
• 对不存在的路径抛出NoSuchPathException，对非法修订抛出BadRevException；
• 旧版cat/blame/ls方法应内部委托给对应的 v2 实现；
• 不在范围内：LFS 内容解析（按原样返回 LFS 指针）、Infinitepush 专属路径。

2. 提交查询操作

对应 002-commit-query-operations.md：

实现要点：

• log_v2需要尊重全部过滤参数：paths、dates、skip、limit、descendants_of_excluding；
• get_commits_between需正确沿 first-parent 血缘遍历；
• 旧版get_commit、log、get_commits委托给 v2 等价实现；
• ScmCommitProp标志位控制按需获取哪些可选字段（决定额外数据是否被抓取）。

3. Diff 与变更文件

对应 003-diff-and-changed-files.md：

实现要点：

• diff 计算基于 Mononoke 的 diff API，含 copy/rename 检测（get_changed_files在设置标志位时检测复制/重命名）；
• get_metadata_diff需包含准确的行数与文件类型信息；
• get_changed_paths_approx返回合理近似即可；
• 不在范围内：Infinitepush 的 diff 方法。

4. 仓库元数据

对应 004-repo-metadata.md：

实现要点：

• 分支/标签的枚举经由 Mononoke API 的 bookmark/tag 列表能力完成；
• 不在范围内：标签的创建/删除、分支创建（本服务只读）。

5. 修订关系

对应 005-revision-relationships.md：

实现要点：

• 依赖 Mononoke 的 changeset ancestry API 与跨仓库同步（cross-repo syncing）API；
• translate_revs需处理 hg ↔ globalrev 翻译；
• get_mirrored_revs需在已同步的仓库对之间工作；
• 不在范围内：设置新的仓库同步配置。

6. 文件定位

对应 006-file-location.md：

实现要点：

• 基于 Mononoke manifest 遍历与 basename 匹配；
• get_all_file_paths返回gzip 压缩、null 分隔的路径列表；
• 大型仓库需避免 OOM——尽量采用流式处理；
• 不在范围内：正则文件搜索、基于内容的搜索（grep）。

约束与不变量

架构文档明确列出三条约束，它们是本服务的"设计红线"：

1. 所有操作必须经由 MononokeAPI 库完成，禁止直接访问数据库。这是最重要的一条——它保证了查询逻辑与底层存储解耦，所有权限、缓存、语义都收敛在 Mononoke API 层。
2. 必须遵守限流（RateLimitedException）。高流量查询服务需要显式的限流信号，客户端应能识别并处理RateLimitedException。
3. 废弃方法（get_commit、log、get_commits）应内部委托给 v2 等价实现。v2 方法承担全部语义，旧接口只做兼容转发，避免同一逻辑的多份实现漂移。

客户端侧印证：scsc 的端到端测试

虽然本仓库不含 ScmQuery 服务的 thrift_handler/core/server 实现源码，但客户端侧有直接的端到端测试印证这套 API 面：scmqueryclient_test.rs。

该文件是 scsc（Source Control Service 命令行客户端）中的一个隐藏测试子命令scmqueryclient-test，用于对真实 SCS 服务端到端地练习scmqueryclient-rust库。它被SCSC_SCMQUERY_TEST_ENABLED环境变量门控，不出现在常规scsc --help输出中，也不可被生产 CLI 使用。

子命令目前覆盖四个方法，其参数结构恰好与本文前述 API 面一一对应：

scsc scmqueryclient-test cat_v2 --repo <repo> --rev <rev> --path <path> scsc scmqueryclient-test is_ancestor --repo <repo> --maybe-ancestor <A> --maybe-descendant <B> scsc scmqueryclient-test merge_base --repo <repo> --rev1 <A> --rev2 <B> scsc scmqueryclient-test get_generation --repo <repo> --rev <rev>

从源码实现看（对应 scmqueryclient_test.rs）：

• cat_v2构造scmquery_types::ScmCatParams { repo, scm_type, rev, path }，调用wrapper.cat_v2(&params)后把返回的字节直接写向标准输出；
• is_ancestor构造ScmIsAncestorParams { repo, scm_type, maybe_ancestor, maybe_descendant }；
• merge_base构造ScmMergeBaseParams { repo, scm_type, rev1, rev2 }，打印结果的hash字段；
• get_generation构造ScmGetGenerationParams { repo, scm_type, rev }，打印结果的generation字段。

几个值得注意的细节：

• 所有子命令都带--scm_type参数且默认值为hg，印证了架构文档中"统一 API 服务 hg 与 git 仓库"的设计，以及参数校验步骤（repo、scm_type、rev）的存在；
• 客户端通过SRClientConfig与ScmQueryClienttrait 封装连接配置，服务发现依赖-H/--host参数，并校验 Thrift 服务器身份（MONONOKE_INTEGRATION_TEST_EXPECTED_THRIFT_SERVER_IDENTITY），体现了服务治理（fb303/身份校验）在客户端侧的延伸；
• 文件头注释明确说明：每当有新方法被移植到 SCS-direct，就会在此增加对应的Method::<Method>变体、参数结构体与 match 分支，并配套一个针对小型 Mononoke fixture 仓库的.t测试——这说明该客户端测试是随 API 面扩展同步演进的"活文档"。

设计启示与总结

ScmQuery 架构文档虽短，但浓缩了 Mononoke 服务设计的几个关键决策，值得在自研查询服务时借鉴：

1. 协议与领域解耦：Thrift 类型（ScmCatParams 等）与 Mononoke 领域类型（RepoContext/ChangesetContext）由 core 层专职互译，使得协议演进（v1→v2）不影响底层查询逻辑。
2. 分层薄厚得当：thrift_handler 只管校验与转发，业务全部下沉 core，server 只做装配；三个组件依赖清晰（server → thrift_handler → core → mononoke_api），可独立测试。
3. 兼容策略明确：旧方法内部委托 v2，ScmCommitProp标志位按需取字段，既保兼容又控开销。
4. 读写分离：查询接口（ScmQueryService）与写接口（ScmWriteService）分开定义，本服务聚焦只读路径。
5. 红线不变量：禁止直连数据库、尊重限流、v2 收敛语义——三条不变量共同保证了服务在大流量与多仓库场景下的稳定性。

对于希望深入阅读的读者，建议从 ARCHITECTURE.md 入手，对照 features 目录下的六份特性文档逐组理解 API 语义，再通过 scmqueryclient_test.rs 的端到端测试把"服务端契约"与"客户端用法"串起来。

• 开发工具
• CLI
• 后端