优化 #[sqlx::test] 的重编译时间

背景

在 Rust 生态系统中，sqlx 是一个广泛使用的异步 SQL 工具包，它通过过程宏（proc macros）在编译期处理 SQL 查询和数据库迁移，从而提供类型安全和零运行时开销的优势。然而，这种“编译期完成一切”的设计在某些场景下会带来显著的性能代价，特别是在集成测试套件庞大时。

作者曾参与 Rust 语言官方项目 bors（一个用于合并请求队列的机器人）的重写工作。bors 拥有庞大的集成测试套件，自 2026 年 1 月部署以来运行稳定。尽管测试覆盖率很高，但作者发现本地开发体验受到严重影响：每次代码更改后，测试套件的重编译时间长达 8-10 秒。经过性能剖析（profiling），作者发现瓶颈主要源于 sqlx::test 宏生成的代码量过大，导致编译器处理负担过重。

核心内容

性能瓶颈的排查

作者首先对 bors 的构建时间进行了剖析，排除了其他干扰因素：

1. 调试信息生成：虽然耗时，但作者需要保留调试信息以便单步调试，因此未将其作为优化目标。
2. 链接时间：由于调试信息庞大（最终二进制文件约 220 MiB），lld 链接器耗时约 1 秒。若使用 wild 链接器可缩短至 200 毫秒，但这并非主要瓶颈。
3. sqlx::test 宏的编译：这是主要的性能杀手。

即使在不连接数据库的情况下（通过设置 SQLX_OFFLINE=1 离线编译），仅执行 touch <test-file> && time cargo test --no-run 这样的无操作变更，重编译仍需约 7.5 秒。

根本原因：宏生成的代码膨胀

#[sqlx::test] 属性宏的作用是在测试执行前创建新数据库、运行迁移并注入连接池。为了实现这一功能，宏会在编译期读取磁盘上的迁移文件，解析、验证并计算哈希值。

虽然读取和解析迁移文件本身很快，但宏生成的输出代码极其庞大。对于每个使用 #[sqlx::test] 的测试，宏会将所有迁移的文本内容和校验和（以字节数组形式）内联生成到 Rust 源代码中，作为常量存在。

生成的代码结构大致如下：

args.migrator(&::sqlx::migrate::Migrator {
    migrations: ::std::borrow::Cow::Borrowed(&[
        ::sqlx::migrate::Migration {
            version: 20240517094752i64,
            description: ::std::borrow::Cow::Borrowed("create build"),
            migration_type: ::sqlx::migrate::MigrationType::ReversibleUp,
            sql: ::std::borrow::Cow::Borrowed("CREATE TABLE ..."),
            no_tx: false,
            checksum: ::std::borrow::Cow::Borrowed(&[193u8, 202u8, ...]),
        },
        // ... 更多迁移
    ]),
});

在 bors 项目中，存在约 350 个 sqlx 测试和 30 个迁移文件。这意味着每个测试函数旁边都内联了所有 30 个迁移的完整定义。

• 数据验证：当作者删除 29 个迁移文件，仅保留 1 个时，重编译时间从 ~7.5 秒降至 ~5 秒。
• 代码体积：cargo expand 的输出从 32 MiB 锐减至 6 MiB。编译额外的 26 MiB Rust 代码显然不是免费的。
• 宏执行开销：在过程宏执行期间，使用 quote crate 将迁移描述数据转换为 TokenStream 也消耗了可观的时间。

这种性能衰退是渐进式的。随着测试和迁移数量的增加，重编译时间缓慢爬升，往往在后期才变得难以忍受。作者尝试了编译器中实验性的过程宏缓存功能，但因生成的代码量过大，缓存带来的收益微乎其微。

解决方案探讨

作者最初考虑通过更紧凑的形式表示校验和字节数组来减少生成代码的大小，但意识到只要每个测试都内联所有迁移，代码膨胀就无法根除。

随后，作者尝试修改 sqlx，将迁移的加载从编译期移至运行期：

• 方法：过程宏不再内联迁移数据，而是生成调用运行时函数的代码。
• 伪代码对比：
  • 优化前：quote! { Migrator { migrations: #migrations } } （#migrations 是展开后的巨大常量数组）
  • 优化后：quote! { Migrator { migrations: ::sqlx::generate_migrations() } }
• 效果：重编译时间降至 ~5 秒，cargo expand 输出降至 ~6 MiB，且测试执行时间未受明显影响。
• 缺点：测试不再自包含（self-contained），因为迁移数据需要在运行时从磁盘加载。

现有替代方案

在 sqlx 的 Discord 社区中，作者询问了优化建议。有趣的是，社区指出 sqlx 实际上已经支持一种避免代码膨胀的机制：通过指定一个包含迁移变量的路径，让所有测试共享同一个迁移定义，而不是在每个测试中内联。

实现方式：

// 宏生成迁移，我们将其存储在一个单一变量中
const MIGRATOR: sqlx::migrate::Migrator = sqlx::migrate!();

// 每个测试引用该变量，而不是在源代码旁边内联所有迁移
#[sqlx::test(migrator = "crate::MIGRATOR")]
async fn test_1(pool: sqlx::PgPool) {}

这种方式既避免了代码膨胀，又保持了编译期的类型检查优势，是处理大型迁移套件更优的工程实践。

关键要点

• 编译期开销累积：sqlx 的过程宏在编译期生成大量内联代码。当测试数量多且迁移文件复杂时，生成的代码体积会急剧膨胀，导致 rustc 编译时间显著增加。
• 渐进式性能退化：这种性能问题具有隐蔽性。随着项目迭代，迁移和测试的增加会导致重编译时间缓慢但持续地变长，严重影响开发效率。
• 离线编译并非免死金牌：即使使用 SQLX_OFFLINE=1 避免数据库连接，宏仍需处理迁移文件的解析和代码生成，因此离线编译并不能解决代码膨胀带来的编译慢问题。
• 运行时加载 vs 共享变量：
  • 将迁移加载移至运行时可以大幅减少编译时间，但牺牲了测试的自包含性。
  • 使用 #[sqlx::test(migrator = "path::to::const")] 共享迁移常量是更推荐的方案，它平衡了编译性能和代码结构。
• 宏缓存的局限性：对于生成代码量巨大的过程宏，编译器层面的宏缓存优化效果有限，因为生成代码本身的编译成本远高于宏执行成本。

意义与影响

这篇文章揭示了 Rust 生态中过程宏（Proc Macros）在提供便利性和类型安全的同时，可能带来的隐性性能成本。对于依赖 sqlx 等重型宏库的大型项目，开发者需要警惕“代码膨胀”对构建速度的影响。

1. 工程实践指导：对于拥有大量数据库迁移和集成测试的项目，应避免在每个测试中内联所有迁移。采用共享迁移常量的方式（如 sqlx::migrate!() 配合 #[sqlx::test(migrator = ...)]）是优化构建时间的有效手段。
2. 工具链优化启示：sqlx 等库的维护者应关注宏生成代码的大小，考虑提供运行时加载选项或更高效的代码生成策略，以改善大型项目的