Rust / 系统课时
格式化代码
格式化代码
本课解决团队代码排版不一致的问题。你将安装并运行 rustfmt,用 rustfmt.toml 固定项目规则,再用检查模式阻止未格式化代码进入仓库,同时区分“自动改写”和“只检查”两种工作方式。
学习目标
- 使用
cargo fmt格式化当前包或整个工作空间 - 在项目中配置稳定、可复用的 rustfmt 规则
- 用检查模式验证格式,并处理常见失败
检查 rustfmt 是否可用
rustfmt 通常随 Rust 工具链以组件形式安装。先在项目目录执行版本检查,确认 rustfmt 与 cargo fmt 都能被调用。
rustfmt --version
cargo fmt --version预期输出如下,具体版本号和提交信息可能不同。
rustfmt <VERSION>
rustfmt <VERSION>如果命令不存在,可执行 rustup component add rustfmt 安装组件。使用 rustup 管理多个工具链时,应在项目实际使用的工具链中安装,例如 rustup component add rustfmt --toolchain stable。
格式化项目代码
假设 src/main.rs 中存在以下可运行代码,虽然语法正确,但空格、换行和缩进不统一。
fn main(){let values=vec![10,20,12];let total:i32=values.iter().sum();println!("sum = {total}");}在项目根目录运行格式化,再启动程序验证行为没有变化。
cargo fmt
cargo run --quiet预期输出如下。cargo fmt 成功时通常不打印内容,程序输出由示例代码产生。
sum = 42格式化后的 src/main.rs 会变为更稳定、可读的结构。
fn main() {
let values = vec![10, 20, 12];
let total: i32 = values.iter().sum();
println!("sum = {total}");
}cargo fmt 默认处理当前包的库目标和二进制目标。工作空间包含多个成员时,使用 cargo fmt --all 统一处理,避免只格式化当前成员。
固定项目格式化规则
在项目根目录创建 rustfmt.toml。配置文件应提交到版本库,使本地开发、编辑器保存和持续集成使用同一套规则。
max_width = 100
hard_tabs = false
tab_spaces = 4
newline_style = "Unix"
use_small_heuristics = "Default"这些配置把普通行宽限制为 100 个字符,统一使用四空格缩进和 Unix 换行符。优先使用稳定选项;某些仅支持 nightly 的配置在 stable 工具链下会被忽略或产生警告。修改配置后重新执行 cargo fmt --all 即可生效。
只检查而不修改文件
提交前或持续集成中不应自动改写仓库文件,而应检查格式是否合格。下面的命令在格式正确时输出标记;发现差异时,rustfmt 会返回非零退出状态。
cargo fmt --all -- --check && echo FORMAT_OK预期输出如下。
FORMAT_OK若检查失败,先在本地运行 cargo fmt --all,查看版本控制差异,再重新执行检查。CI 与本地应使用相同 Rust 工具链,否则不同版本的 rustfmt 可能产生细微格式差异。
处理边界与常见问题
rustfmt 只负责代码布局,不检查业务逻辑、类型错误或性能问题。格式化完成后仍应继续运行编译、测试和 Clippy。
遇到 component 'rustfmt' is unavailable 时,先确认当前工具链,再安装对应组件。遇到某段代码不希望自动调整时,可以谨慎使用 #[rustfmt::skip],但它会降低全局一致性,只适合宏输入、生成式代码等确有必要的局部场景。
编辑器开启“保存时格式化”后,也应保留命令行检查。编辑器负责即时反馈,cargo fmt --all -- --check 才是可在所有开发环境和 CI 中重复执行的统一验收标准。
本课总结
cargo fmt会改写文件,cargo fmt --all -- --check只检查并用退出状态表示结果rustfmt.toml应放在项目根目录并提交到版本库- rustfmt 解决排版一致性,不能替代编译、测试和静态检查
下一课预告
下一课将运行 Clippy,识别可疑写法、冗余逻辑和常见性能问题,并把警告提升为可用于持续集成的质量门槛。