Skip to content

旋武社区

Main Navigation 首页下载

快速上手

课程学习

规则规范

在线体验工具旋武项目资讯关于我们

Sidebar Navigation

Rust 编程规范

1 概述

1.1 背景

1.2 目标与适用范围

1.3 总体原则

1.4 条款组织方式

2 代码风格

2.1 命名

P.NAM.01 标识符命名应符合阅读习惯

G.NAM.01 应使用统一的命名风格

G.NAM.02 类型转换函数命名宜遵循所有权语义

2.2 格式与注释

G.CMT.01 公开的 API 需要文档注释

G.CMT.02 文件头注释应包含版权说明

P.CMT.01 注释跟代码一样重要，应按需注释

P.FMT.01 代码格式应保持统一

G.FMT.01 `extern` 外部函数应显式指定 ABI 标识

3 编程实践

3.1 常量

G.CNS.01 常量类型不应具有内部可变性

G.CNS.02 宜使用标准库中的预定义常量

3.2 数据类型

G.TYP.01 数值字面量要添加明确的类型标识

P.TYP.01 合理选择算术转换方式

3.2.1 布尔

G.TYP.BOL.01 不宜使用块表达式作为控制表达式

G.TYP.BOL.02 不宜将布尔变量和布尔字面量进行比较

G.TYP.BOL.03 && 和 || 操作符的右侧操作中不应包含副作用

3.2.2 字符

G.TYP.CHR.01 整数到字符的类型转换应注意有效范围

3.2.3 数字

G.TYP.INT.01 整数类型的算数运算，宜使用checked, saturating_, overflowing_, wrapping_ 为前缀的方法

3.2.4 数组

G.TYP.SLC.01 宜使用迭代器而非下标遍历切片和数组

G.TYP.SLC.02 应保证数组索引在有效范围内

3.2.5 结构体与枚举

G.TYP.SCT.01 外部使用的自定义类型宜实现常见 `trait`

3.2.6 字符串

G.TYP.STR.01 在实现`Display`trait 时不应调用`to_string() `方法

3.2.7 智能指针

G.TYP.PTR.01 `Rc` 、 `Arc` 、 `Box` 不应相互嵌套使用

3.3 表达式与流程控制

G.CTF.01 宜优先使用模式匹配而非判断后再取值

G.CTF.02 在 Match 分支的 Guard 语句中不要使用带有副作用的条件表达式

G.CTF.03 循环或递归必须安全退出

G.EXP.01 避免复合条件表达式永远为 `true` 或 `false`

G.EXP.02 用括号明确表达式的操作顺序，避免过分依赖默认优先级

3.4 函数与闭包

G.FUD.01 内存拷贝代价大的参数应按地址传递

G.FUD.02 可能出错的函数，应保证用户不可忽略返回值

3.5 泛型与 trait

G.TRA.01 在实现相等性、排序和散列类 trait 时，应保证一致性

G.TRA.02 宜实现 `From` 而不是 `Into`

3.6 错误处理

G.ERR.01 应正确处理返回类型 `Option` 和 `Result`

3.7 模块

G.MOD.01 导入模块中的类型或函数时，应避免直接使用通配符

3.8 宏

3.8.1 声明宏

G.MAC.DCL.01 编写宏匹配规则时，宜遵从匹配范围从小至大的顺序

P.MAC.DCL.01 定义和使用声明宏时，应保证卫生性

3.8.2 过程宏

P.MAC.PRO.01 定义和使用过程宏时，应保证卫生性

G.MAC.PRO.011 定义和使用过程宏时，应保证卫生性

4 安全实践

4.1 Unsafe 函数和 trait

P.SAF.UNS.01 Unsafe 代码应仅在需要的场景下使用

G.SAF.UNS.01 禁止将外部可控数据作为加载动态库的参数

4.2 FFI

P.SAF.FFI.01 在 FFI 边界上传递数据应注意内存安全管理

P.SAF.FFI.02 应正确处理 FFI 调用的返回值和输出参数

P.SAF.FFI.03 应优先选用 RAII 方式管理外部资源

G.SAF.FFI.01 FFI 边界应确保字符串参数正确传递和使用

G.SAF.FFI.02 在 FFI 调用的场景下，应确保跨边界数据的内存布局兼容

G.SAF.FFI.03 禁止调用 C 不可重入函数

G.SAF.FFI.04 禁止使用外部内存不安全函数

4.3 并发并行

P.SAF.MTH.01 并发场景下应避免数据竞争和死锁

G.SAF.ASY.01 避免在异步处理过程中包含阻塞操作

G.SAF.MTH.01 多线程场景下，对于共享的标量类型数据，宜使用对应的原子类型

4.4 内存与指针

G.SAF.MEM.01 应校验内存申请函数的输入参数和返回值

G.SAF.MEM.02 Unsafe 模式下，使用指针及内存地址时应确保有效性

G.SAF.MEM.03 Unsafe 模式下，应正确释放申请的内存

G.SAF.MEM.04 内存中的敏感信息使用完毕后应立即清零

5 附录

附录A Rustfmt 配置与模板

附录B Clippy 配置与模板

参考资料

内容导航

Rust 编程规范

旋武社区

发表于：2024-05-08

最后更新于:

Pager

下一页1.1 背景

旋武社区是由开放原子开源基金会（OpenAtom Foundation）旗下的专项社区