深入解析 Hyperswitch 的 router 主 crate：目录布局、双二进制架构与 Feature 切换机制

Hyperswitch（开源、可组合的支付平台）是一个由多个 Rust crate 组成的 workspace，而 router 是其中承担核心职责的主 crate：它定义了 API 端点、编排支付/退款/客户/支付方法等业务流程、加载全部运行时配置，并对外产出 router 与 scheduler 两个可执行程序。本文以 crates/router/README.md 为骨架，逐层对照当前仓库的实际源码，说明该 crate 的目录布局设计意图、各子目录的真实职责、Cargo feature 开关体系，以及集成测试的组织方式，帮助读者在不读完整个代码库的前提下建立对 Hyperswitch 主进程的完整心智模型。

1. router：整个项目的主 crate

crates/router/README.md 开篇只有一句话，却定下了这个 crate 的地位：

Main crate of the project.（项目的主 crate）

从 crates/router/Cargo.toml 可以确认这一点。包元数据部分声明了 crate 名称与定位（第 2-6 行）：

[package]
name = "router"
description = "Modern, fast and open payment router"
version = "0.2.0"
edition.workspace = true
default-run = "router"

值得注意的是文件末尾声明了两个二进制入口（第 345-351 行）：

[[bin]]
name = "router"
path = "src/bin/router.rs"

[[bin]]
name = "scheduler"
path = "src/bin/scheduler.rs"

也就是说，crates/router 这一个 crate 编译后同时产出两个进程：

• router（crates/router/src/bin/router.rs）：同步 API 服务进程，基于 actix-web 对外暴露全部支付相关 REST 端点；
• scheduler（crates/router/src/bin/scheduler.rs）：异步任务/轮询进程，处理后台任务（如交易状态轮询、重试、邮件发送等），依赖独立的 crates/scheduler crate 提供的调度框架。

这种“一 crate 双二进制”的布局意味着两个进程共享同一套配置加载、类型定义与领域模型代码，天然保证了进程间数据契约的一致性。

2. 官方文档给出的目录树布局

README 的核心内容是一张文件树（tree -L 3 -d 生成的初始版本），描述了 router crate 的设计蓝图：

├── src                        : source code
│   ├── configs                : config loading
│   ├── connector              : various connector (gateway) specific transformations implementations.
│   │   ├── adyen              : adyen connector
│   │   └── stripe             : stripe connector
│   ├── core                   : the core router / orchestrator code. All common code/flow should exist here. only minimal code in connector implementations.
│   │   ├── customers          : ?
│   │   ├── payment_methods    : ?
│   │   ├── payments           : ?
│   │   └── refunds            : ?
│   ├── routes                 : the API endpoints exposed by router. currently uses actix_web.
│   ├── scheduler              : ?
│   │   └── types              : ?
│   ├── services               : ?
│   │   └── redis              : ?
│   ├── types                  : the objects/API type definitions
│   │   ├── api                 : the router API
│   │   └── storage             : definitions for using DB/Storage. Currently uses Diesel.
│   └── utils                  : utilities
└── tests                      : unit and integration tests

文档在树中明确写入了三条关键设计原则，值得逐条理解：

1. core 是唯一的“重逻辑”区域——“the core router / orchestrator code. All common code/flow should exist here. only minimal code in connector implementations.” 即所有通用的业务编排都应放在 core，connector 实现里只允许保留最小化的胶水代码。这条原则直接决定了后续章节里 src/core 与 connector 的职责边界。
2. routes 只做 API 暴露，且当前使用 actix-web 框架（这一点与 crates/router/Cargo.toml 中 actix-web = "4.11.0" 的依赖相互印证）。
3. types 分层：api 子目录定义对外 API 类型，storage 子目录定义数据库/存储相关类型（当时使用 Diesel，现在依然如此，diesel = { version = "2.2.10", features = ["postgres"] }）。

文档本身也诚实地标注了 FIXME（“此表应由脚本生成，或引入 smoke test 校验其与真实结构一致”），并留了不少 ?。因此下面几节会结合当前仓库的实际源码，把这张蓝图“填充”完整，并指出布局随代码演进而发生的真实变化。

3. 对照当前源码：目录树的实际形态

当前 crates/router/src 下的一级模块为：analytics.rs、compatibility、configs、connector、consts、core、db、events、routes、services、types、utils、workflows 等，与文档蓝图高度一致。逐个子目录看：

3.1 src/core：业务编排的核心

crates/router/src/core 印证了文档中“所有通用流程都在这里”的原则。目录中可看到与文档树中 customers / payment_methods / payments / refunds 四个占位符对应的真实模块，外加大量后续演进出来的业务能力：

• 文档已列出的四大核心：payments.rs 与 payments/、refunds.rs、customers.rs、payment_methods.rs 与 payment_methods/；
• 支付前置与恢复：fraud_check/（欺诈检查）、routing/（智能路由）、revenue_recovery/（收入恢复，对应 v2 特性）、pm_auth/（支付方法鉴权）；
• 账户与密钥体系：api_keys.rs、user/、user_role/、encryption.rs、unified_connector_service/、unified_authentication_service/；
• 平台能力：blocklist/（黑名单）、disputes/（拒付）、mandate/（代扣授权）、webhooks/（事件与 Webhook）、tokenization.rs、three_ds_decision_rule/（3DS 决策规则）、offer_engine/、payment_link/、payouts/ 等；
• 基础设施类：configs.rs、health_check.rs、metrics.rs、errors.rs。

3.2 src/connector：连接器实现的“外迁”

文档树里 src/connector 下画着 adyen、stripe 两个子目录，代表“各支付网关的转换实现”。但当前仓库中，crates/router/src/connector 目录下只剩 utils.rs 一个文件——真正的连接器实现已经整体迁出到独立的 crates/hyperswitch_connectors crate（包含数百个 .rs 文件），由 router 通过依赖引入（crates/router/Cargo.toml 中 hyperswitch_connectors = { version = "0.1.0", path = "../hyperswitch_connectors", default-features = false }）。

这个演化恰好强化了文档那句设计原则：连接器代码与主路由解耦后，src/connector/utils.rs 只保留通用工具，网关特定的请求转换（connector transformers）全部落在 hyperswitch_connectors 中，而 connector-template/ 目录还为新增连接器提供了模版权板。对读者的启示是：阅读 router 时遇到“网关特定行为”，应顺着 hyperswitch_connectors 去找，而不是在 src/connector 里找。

3.3 src/scheduler：从目录到独立 crate

文档树中 src/scheduler 标注为 ?，且其下还有 types 子目录。在当前仓库中，调度器的框架实现（任务注册、分布式锁、执行器）已经独立为 crates/scheduler crate，而 router crate 保留了对它的依赖与 scheduler 二进制入口（见第 1 节的 [[bin]] 声明）。从源码结构看，src 下不再存在独立的 scheduler 目录，蓝图中的这一项最终以“crate 化”的形式兑现——这也是大型 Rust workspace 中常见的重构方向：把可复用的框架代码从业务 crate 中抽离。

3.4 src/routes：API 端点层

crates/router/src/routes 对应文档中“the API endpoints exposed by router. currently uses actix_web”。目录中的模块与 core 大致一一对应：payments/、refunds.rs、customers.rs、payment_methods.rs、webhooks.rs、health.rs、disputes/、mandates.rs、routing.rs、process_tracker.rs、revenue_recovery_redis.rs 等。

路由的总装配点在 crates/router/src/routes/app.rs（约 3500 行）。从文件头部可以看到它按 feature 有条件地引入各路由模块，例如：

#[cfg(feature = "payouts")]
use super::payouts::*;
#[cfg(feature = "v2")]
use super::proxy;
#[cfg(all(feature = "oltp", feature = "v2"))]
use super::refunds;
#[cfg(feature = "olap")]
use super::routing;

这说明 API 端点的注册本身就是 feature 驱动的：不同编译配置下，router 暴露的端点集合不同（详见第 5 节）。app.rs 负责把 payments、customers、webhooks 等 Scope 挂到 actix 的 App 上，形成统一的 URL 前缀树。

3.5 src/types 与 src/utils

• crates/router/src/types 完全兑现了文档蓝图：api/（对外 API 类型的补充定义）、storage/（存储层类型）、domain.rs（领域对象）、transformers.rs（API 对象与存储对象之间的转换）、connector_transformers.rs（与连接器侧请求/响应互转的 trait 定义）；
• src/utils 存放通用工具函数；
• 此外，文档未列出的 configs/、db/、events/、compatibility/、workflows/ 是后续演进新增的模块，其中 configs/ 是本文第 4 节的重点。

3.6 tests：单元与集成测试

文档树末尾的 tests : unit and integration tests 对应 crates/router/tests 目录。当前的集成测试文件覆盖主要业务面：

• payments.rs 与 payments2.rs（支付主流程）
• refunds.rs、customers.rs、payouts.rs
• webhooks.rs、services.rs、health_check.rs、cache.rs
• connectors/ 子目录（按连接器的集成测试）、integration_demo.rs

dev-dependencies 中引入了 test_utils（crates/test_utils crate）、wiremock、serial_test 等，说明集成测试依赖本地测试工具 crate 与 HTTP mock。

4. src/configs：配置加载体系

文档树把 src/configs 标注为 “config loading”。当前实现由四个模块组成：

• crates/router/src/configs/settings.rs：配置结构体的定义与反序列化；
• crates/router/src/configs/defaults.rs：默认值；
• crates/router/src/configs/validations.rs：配置合法性校验；
• crates/router/src/configs/secrets_transformers.rs：密钥类配置（如数据库密码）的 KMS 解密转换。

配置以 TOML 文件承载，Cargo 依赖中的 config = { version = "0.14.1", features = ["toml"] } 负责解析。仓库提供了完整的参考配置 config/config.example.toml（1500+ 行，注释明确其为“列出全部可用配置项的参考文件”），其中与 router 服务直接相关的片段如：

# Server configuration
[server]
port = 8080
host = "127.0.0.1"
workers = 10                                 # 处理请求的 worker 线程数（默认取物理 CPU 数）
shutdown_timeout = 30                        # actix-server 优雅停机宽限时间（秒）
request_body_limit = 32_768                  # HTTP 请求体上限，默认 32kB
keep_alive = 5                               # Keep-alive 超时（秒）
client_request_timeout = 5000                # 客户端请求超时（毫秒）

# HTTPS Server Configuration
[server.tls]
port = 8081
host = "127.0.0.1"
private_key = "/path/to/private_key.pem"
certificate = "/path/to/certificate.pem"

# 连接支付网关用的代理配置；不需要代理时不要定义这些字段
[proxy]
idle_pool_connection_timeout = 90
bypass_proxy_hosts = "localhost, cluster.local"

本地开发则通常直接使用 config/development.toml。配置项与 src/configs/settings.rs 中的结构体一一对应，例如 [server] 各字段会作用到 actix 的 HttpServer（worker 数、优雅停机、body 上限等），[server.tls] 则只有启用 tls feature 时才会编译进二进制。

5. Feature 开关：一个 crate，多种形态

router crate 的一个显著工程特征是用 Cargo features 控制编译形态。crates/router/Cargo.toml 第 12 行开始声明了完整的 feature 矩阵，核心几组如下：

[features]
default = ["common_default", "v1", "redis-rs"]
common_default = [
    "kv_store", "stripe", "oltp", "olap", "accounts_cache",
    "dummy_connector", "payouts", "payout_retry", "retry",
    "frm", "tls", "partial-auth", "km_forward_x_request_id",
    "external_services/superposition",
]
olap  = [ "hyperswitch_domain_models/olap", "storage_impl/olap",
          "scheduler/olap", "api_models/olap", "dep:analytics" ]
oltp  = [ "storage_impl/oltp" ]
v1    = [ "common_default", "api_models/v1", "diesel_models/v1",
          "hyperswitch_domain_models/v1", "storage_impl/v1", "..." ]
v2    = [ "common_default", "api_models/v2", "diesel_models/v2",
          "hyperswitch_domain_models/v2", "storage_impl/v2",
          "revenue_recovery", "scheduler/v2", "..." ]
release = [ "stripe", "email", "accounts_cache", "kv_store", "vergen",
            "external_services/aws_kms", "external_services/aws_s3",
            "keymanager_mtls", "keymanager_create", "encryption_service",
            "dynamic_routing", "payout_retry", "deja" ]

可以归纳出四个维度的开关：

1. API 版本维度：v1 与 v2 分别向下传递到 api_models、diesel_models、storage_impl、hyperswitch_connectors 等几乎所有一方 crate——这是 Hyperswitch 双 API 版本并存、同一二进制按 feature 裁剪的根基（第 3.4 节 app.rs 中 #[cfg(feature = "v2")] 等代码即由此而来）；
2. 存储维度：oltp（主数据库存储）与 olap（分析存储，附带 analytics 依赖）对应 OLTP/OLAP 双库架构；
3. 能力维度：payouts、frm（欺诈风控）、dynamic_routing、revenue_recovery、dummy_connector（测试用假连接器，会同时向 euclid、payment_methods、hyperswitch_connectors 等传递同名 feature）等；
4. 部署形态维度：tls 启用 actix-web 的 rustls 支持，partial-auth 允许信任 x-merchant-id 请求头以省去逐请求鉴权开销（Cargo.toml 中有专门注释说明该 feature 语义），而 release 组合了 KMS/AWS S3/加密服务/动态路由等生产依赖。

默认 feature（common_default + v1 + redis-rs）意味着 cargo run 直接得到的是 v1 API、带 Redis（redis-rs 客户端实现，另有 fred 可选实现）、含 TLS 的完整开发形态。

6. 关键运行时依赖速览

从 crates/router/Cargo.toml 的依赖清单还能读出 router 进程的技术栈轮廓：

• Web 框架：actix-web 4.11、actix-cors、actix-multipart；
• 数据库：diesel 2.2（postgres 特性）+ bb8 连接池 + async-bb8-diesel；
• 异步运行时：tokio 1.48（multi-thread）；
• 外部通信：reqwest 0.11（rustls-tls）、rdkafka（Kafka 事件流）、unified-connector-service-client（gRPC 统一连接器服务客户端）；
• 安全：argon2、jsonwebtoken、openidconnect、totp-rs、rustls、ring/blake3/hkdf（哈希与密钥派生）；
• 一方 crate：hyperswitch_domain_models（领域模型）、storage_impl（存储实现）、hyperswitch_connectors（连接器）、euclid（决策规则引擎）、kgraph_utils、events、external_services 等，router 通过 feature 把这些 crate 的能力“点亮”后组装成完整服务。

7. 小结

crates/router/README.md 用一张简洁的目录树确立了 router crate 的分层契约：routes 暴露 API、core 承载全部通用编排、connector 只留最小胶水、types 分层定义 API 与存储类型、configs 负责配置加载、tests 覆盖单元与集成测试。对照当前仓库源码可以看到这张蓝图既被完整保留（core 的业务模块、routes 的端点组织、types 的 api/storage 划分、tests 的按业务面切分），也在两处发生了结构性演化：连接器实现整体外迁到 hyperswitch_connectors crate、调度框架独立为 scheduler crate；同时 Cargo feature 体系（v1/v2、oltp/olap、release 等）使同一份 router 源码能够按 API 版本、存储形态与部署环境裁剪出不同二进制。对需要修改或阅读 Hyperswitch 主路由代码的开发者来说，这条“README 蓝图 → 实际目录 → feature 开关”的对照路径，就是最省力的导航地图。