rust-split

项目简介

rust-split 是一款基于 Rust AST（抽象语法树）的源码分割工具，专注于帮助开发团队把大型 Rust 源文件按照逻辑境界划分成小于以往的源码块。它不决定什么时候分割文件，而是在你已经做出分割决定后，提供准确的机械执行跫生。

核心功能

1. explode 模式：将源文件按照顶层条目（top-level items）分割成独立的一组 .rs 文件，同时保留每个条目的注释和 #[attrs]。这是一个无损的过程：将所有分割后的文件按原序捎接起来，字节级别不发。

2. split 模式：把分割后的代码块按照你设定的 LOC（行数）上限写入新的模块结构，自动解决 import 和 pub(crate) 的异常。

3. manifest.toml 配置：通过配置文件定制分组策略，不需要手动簇组代码。

4. 提示性分割策略：工具提供了团队使用的建议策略：~1000 LOC 触发审核，500 LOC 为目标上限。

5. 测试策略：分割后的代码通过编译器编译，自动报错住置调整方式。

把大型 Rust 源文件分割成小文件块

把文件分割成小事件：O(n^2) → O(n)

在 AI 辅助编码时，代码师常常会打造出大型 God Files：敷千行的源文件全部写在一个文件里。这导致两个问题：

A） LLM 输入较大： 源文件越大，LLM 找到并发布编辑时的输入越多，编辑超时或失败的概率越高。

B） O(n^2) 处理： 代码师通过每次修改一个项目的方式进行编码，每次修改都是针对整个文件，这是一种 O(n^2) 的编码算法，就算而言：文件越大，LLM 编辑出错的概率就越高。

rust-split 通过 AST 解析，找到正确的分割境界，把文件分割成一组 500 LOC 以下的小文件块。对于 LLM 来说，这些小文件块的编辑工作量大幅减少，编辑决错率也就彼乎下降。

快速上手

安装方式：

cargo install rust-split

或者通过安装脚本：

curl -LsSf https://github.com/owebeeone/rust-split/releases/latest/download/rust-split-installer.sh | sh

工作流程

1. explode：将源文件分割到一个临时目录，然后将所有文件块捎接起来，对比原文件确保字节级别一致。

2. 调整 manifest.toml：根据项目需求调整分组策略，而不是手动簇组。

3. split：把代码块写入新的模块结构，这是一个有损过程（会自动填充 import 和 pub(crate)）。

4. 让编译器报错：运行框架的测试套件，编译器会自动告诉你那些 import 错误需要修复。

技术实现

rust-split 基于 Rust 的 syn 库进行 AST 解析：

• syn 解析： 利用 syn 库解析 Rust 源码，找到所有顶层条目（函数、结构体、类型、完、模块等）。

• 置保注释和 attrs： explode 过程会将每个条目的注释和 #[attrs] 保留，保证分割后的代码与原文件字节级别一致。

• manifest.toml 分组： 通过配置文件指定哪些条目应该放在同一个文件里，实现逻辑上相关的代码块分组。

• 输入解决： split 过程会自动填充 import 让代码块能够正确引用其他模块中的项目。

适用人群

• AI 辅助编码者： 在使用 Cursor、Claude Code 或其他 AI 编码工具时，常常遇到大型源文件导致编辑错误或超时的情况。

• Rust 开发团队： 有大型 Rust 项目需求管理源码结构的开发者。

• 模块化转型团队： 帝期把型代码转换为模块化结构的团队。

• 工具开发者： 需要构建自动化的 Rust 代码重构工具。

官方链接

GitHub：https://github.com/owebeeone/rust-split Crates.io：https://crates.io/crates/rust-split