Rust / 系统课时

格式化代码

格式化代码

本课解决团队代码排版不一致的问题。你将安装并运行 rustfmt,用 rustfmt.toml 固定项目规则,再用检查模式阻止未格式化代码进入仓库,同时区分“自动改写”和“只检查”两种工作方式。

学习目标

  • 使用 cargo fmt 格式化当前包或整个工作空间
  • 在项目中配置稳定、可复用的 rustfmt 规则
  • 用检查模式验证格式,并处理常见失败

检查 rustfmt 是否可用

rustfmt 通常随 Rust 工具链以组件形式安装。先在项目目录执行版本检查,确认 rustfmt 与 cargo fmt 都能被调用。

bash
rustfmt --version
cargo fmt --version

预期输出如下,具体版本号和提交信息可能不同。

text
rustfmt <VERSION>
rustfmt <VERSION>

如果命令不存在,可执行 rustup component add rustfmt 安装组件。使用 rustup 管理多个工具链时,应在项目实际使用的工具链中安装,例如 rustup component add rustfmt --toolchain stable。

格式化项目代码

假设 src/main.rs 中存在以下可运行代码,虽然语法正确,但空格、换行和缩进不统一。

rust
fn main(){let values=vec![10,20,12];let total:i32=values.iter().sum();println!("sum = {total}");}

在项目根目录运行格式化,再启动程序验证行为没有变化。

bash
cargo fmt
cargo run --quiet

预期输出如下。cargo fmt 成功时通常不打印内容,程序输出由示例代码产生。

text
sum = 42

格式化后的 src/main.rs 会变为更稳定、可读的结构。

rust
fn main() {
    let values = vec![10, 20, 12];
    let total: i32 = values.iter().sum();
    println!("sum = {total}");
}

cargo fmt 默认处理当前包的库目标和二进制目标。工作空间包含多个成员时,使用 cargo fmt --all 统一处理,避免只格式化当前成员。

固定项目格式化规则

在项目根目录创建 rustfmt.toml。配置文件应提交到版本库,使本地开发、编辑器保存和持续集成使用同一套规则。

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 会返回非零退出状态。

bash
cargo fmt --all -- --check && echo FORMAT_OK

预期输出如下。

text
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,识别可疑写法、冗余逻辑和常见性能问题,并把警告提升为可用于持续集成的质量门槛。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

格式化代码

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通