pyruts
一个面向 Rust 工程实践的 proc_macro 工具集
简介
pyruts 是一个 Rust proc_macro 工具集,一站式提供构建器派生、FFI 安全包装、错误传播与字典字面量等常用模式的宏实现。所有代码在编译期展开,零运行时开销——proc_macro 本身不引入任何运行时依赖。
API 设计严格对齐 derive_builder、anyhow、maplit 等世界一流库,迁移成本极低;FFI 包装宏 c_wrap! 将 unsafe 边界收敛到一处,生成的代码经 miri 验证内存安全;测试覆盖每个宏的所有属性组合,CI 同时跑 test + clippy + miri + fmt 四道关。
- 零运行时开销:proc_macro 在编译期展开,运行时只见生成代码
- API 对齐主流生态:
Builder对标derive_builder,ensure!/bail!/throw!对标anyhow,dict!/btree_dict!对标maplit - unsafe 隔离:
c_wrap!自动生成safe_<name>包装,把 FFI 风险面收敛到生成代码一处 - 完整测试:每个宏配独立测试文件,覆盖必填/可选/默认/泛型/校验等所有路径
30 秒上手
写给 Python 用户的极简速查:三个示例覆盖构造、字典与错误处理,每段附 Python 等价代码。
1. 构造结构体
use Builder;
// Python: Config(name="alice", age=30)
// 推荐 (make! 宏, 即将支持):
// let c = make!(Config { name: "alice", age: 30 });
// 等价 (builder, 当前可用):
let c = builder
.with_name
.with_age
.build
.unwrap;
2. 创建字典
use dict;
use HashMap;
// Python: {"a": 1, "b": 2}
let m: = dict! ;
3. 错误处理
use ;
安装
[]
= "0.1"
特性总览
| 宏 | 类型 | 用途 | 对标库 |
|---|---|---|---|
Builder |
derive | 为结构体生成链式构造器 | derive_builder |
c_wrap! |
function-like | 包装 extern "C" 块,生成 safe_<name> 安全函数 |
(原创,无直接对标) |
ensure! |
function-like | 条件断言,失败时立即返回错误 | anyhow::ensure! |
bail! |
function-like | 立即返回格式化错误 | anyhow::bail! |
throw! |
function-like | bail! 语义别名 |
anyhow::bail! |
dict! |
function-like | 字面量构造 HashMap(with_capacity 预分配) |
maplit::hashmap! |
btree_dict! |
function-like | 字面量构造 BTreeMap |
maplit::btreemap! |
set! |
function-like | 字面量构造 HashSet(with_capacity 预分配) |
maplit::hashset! |
btree_set! |
function-like | 字面量构造 BTreeSet |
maplit::btreeset! |
make! |
function-like | 一行构造结构体 (Python Type(...) 风格) |
- |
Builder 宏
#[derive(Builder)] 为命名字段结构体生成 XxxBuilder 链式构造器,支持泛型、where 子句、生命周期。
字段级属性
| 属性 | 含义 | 示例 |
|---|---|---|
#[builder(default)] |
未设置时用 Default::default() |
#[builder(default)] count: u32 |
#[builder(default = "expr")] |
未设置时用字符串解析的表达式 | #[builder(default = "42u32")] count: u32 |
#[builder(each = "name")] |
Vec<T> 字段,每次调用 name(v) 追加元素 |
#[builder(each = "item")] items: Vec<String> |
#[builder(setter = "name")] |
自定义 setter 方法名 | #[builder(setter = "age")] age: u32 |
#[builder(setter(into))] |
显式声明 setter 接受 impl Into<T>(语法糖,默认即此行为) |
#[builder(setter(into))] name: String |
#[builder(setter(strip_option))] |
Option<T> 字段仅生成接受 T 的 setter,不再生成 with_xxx_option |
#[builder(setter(strip_option))] nick: Option<String> |
#[builder(skip)] |
跳过字段,不生成 setter,build 时用 Default |
#[builder(skip)] created_at: u64 |
结构体级属性
| 属性 | 含义 | 示例 |
|---|---|---|
#[builder(validate = "fn")] |
build 完成后调用 fn(&Self) -> Result<(), String> 进行业务校验 |
#[builder(validate = "check_range")] |
#[builder(field_defaults(...))] |
为所有字段设置默认配置,单字段可覆盖;支持 default/default = "expr"/skip/skip = bool/setter(into)/setter(strip_option) 子选项 |
#[builder(field_defaults(default = "0u32", skip = false))] |
#[builder(builder_type(derive = "..."))] |
给生成的 XxxBuilder 附加 #[derive(...)] 属性,逗号分隔多项 |
#[builder(builder_type(derive = "Clone, Debug"))] |
#[builder(setter(strip_option))] |
应用到所有 Option<T> 字段(同字段级语义,可由字段级 setter(strip_option = false) 覆盖) |
#[builder(setter(strip_option))] |
#[builder(setter(prefix = "..."))] |
控制 setter 方法名前缀(默认 "with_",设 "" 则 setter 名 = 字段名,更贴近 Python 关键字参数风格) |
#[builder(setter(prefix = ""))] |
泛型支持
- 自动透传泛型参数与
where子句到XxxBuilder<T, ...> - 多泛型参数、生命周期、
T: Clone + Default等约束均支持 validate函数需手动泛型化并与 struct 约束对齐
生成的 API
| 项 | 签名 | 说明 |
|---|---|---|
XxxBuilder |
pub struct XxxBuilder<T> { ... } |
与原 struct 同泛型,实现 Default |
Xxx::builder() |
-> XxxBuilder<T> |
入口构造器(已 Default::default()) |
XxxBuilder::new() |
-> Self |
等价 Default::default() |
with_<field>(v) |
mut self, value: impl Into<T> -> Self |
普通 setter,字段上文档透传到 setter |
with_<field>_option(opt) |
mut self, value: Option<T> -> Self |
仅 Option<T> 字段生成,直接覆盖 |
<each_name>(v) |
mut self, value: impl Into<T> -> Self |
仅 each 字段生成,追加元素 |
build(self) |
-> Result<Xxx<T>, String> |
必填校验 + validate 钩子 |
try_build(self) |
-> Result<Xxx<T>, String> |
build 别名 |
字段处理规则:
Option<T>字段:builder 内直接存Option<T>(不双层嵌套),缺省即None- 非
Option非each字段:builder 内用Option<T>包装,缺省触发必填错误 each字段:builder 内直接存Vec<T>,缺省即空Vecskip字段:不存于 builder,build时用Default::default()
性能优化
Builder派生宏在编译期展开,运行时仅见生成代码;可测开销来自Option包装与必填校验,工程实践中可忽略- 容器宏
dict!/set!使用HashMap::with_capacity(N)/HashSet::with_capacity(N)预分配容量(N = 字面量元素数),避免插入过程中多次 rehash btree_dict!/btree_set!保持BTreeMap::new()/BTreeSet::new()(BTree 系无with_capacity方法)
示例 1:基础用法(必填 + 可选 + 默认)
use Builder;
let c = builder
.with_name
.with_age
.with_email // 可选, 也可省略
.build
.unwrap;
assert_eq!;
assert_eq!;
// 缺必填字段时返回 Err, 错误信息包含字段名
let err = builder.with_name.build.unwrap_err;
assert!;
示例 2:validate 钩子 + each + default = "expr"
use Builder;
let v = builder
.with_name
.with_age
.tag
.tag
.build
.unwrap;
assert_eq!;
assert_eq!;
// 校验失败: age 越界
let err = builder
.with_name
.with_age
.build
.unwrap_err;
assert!;
示例 3:泛型 + where 子句 + 生命周期
use Builder;
let g: = builder
.with_a
.with_b
.build
.unwrap;
// where 子句
let g: = builder
.with_data
.build
.unwrap;
// 泛型 + 生命周期
let x = 42i32;
let g: = builder
.with_reference
.with_value
.build
.unwrap;
assert_eq!;
示例 4:setter(strip_option) — 简化 Option 字段 API
Option<T> 字段默认会同时生成 with_xxx(impl Into<T>) 与 with_xxx_option(Option<T>) 两个 setter。若只想暴露前者(内部自动包 Some),用 setter(strip_option) 抑制后者。
use Builder;
let u = builder
.with_name
.with_nick // 直接传 &str, 内部包 Some
.build
.unwrap;
assert_eq!;
// nick 未设置时缺省为 None
let u2 = builder.with_name.build.unwrap;
assert!;
示例 5:field_defaults — 字段级默认配置
struct 级 field_defaults(...) 为所有字段设置默认配置,单字段可用 #[builder(...)] 覆盖。覆盖规则:字段级 Some(_) 优先,字段级未设置时回退到 struct 级。
use Builder;
let x = builder.build.unwrap;
assert_eq!; // field_defaults 的 default
assert_eq!; // 字段级覆盖
assert_eq!; // skip → Default::default()
示例 6:builder_type(derive = "...") — 给 Builder 附加 derive
默认 XxxBuilder 只实现 Default。需要 Clone / Debug 等能力时,用 builder_type(derive = "...") 附加 #[derive(...)],逗号分隔多项。
use Builder;
let b = builder.with_host.with_port;
let _cloned = b.clone; // Builder 现在实现 Clone
println!; // Builder 现在实现 Debug
示例 7:setter(prefix = "...") — 自定义 setter 前缀
默认 setter 名为 with_<field>。设 prefix = "" 后 setter 名直接等于字段名,调用形式更接近 Python 关键字参数;也可用任意前缀如 set_ 对齐 Java 风格。
use Builder;
// setter 名直接是字段名, 更接近 Python: Config(name="alice", age=30)
let c = builder.name.age.build.unwrap;
assert_eq!;
assert_eq!;
c_wrap! 宏
c_wrap! 包装 extern "C" { ... } 块:原样输出链接声明,并为每个 C 函数生成 safe_<name> 安全包装函数,自动处理 *const c_char 转换和 buffer 模式。
行为说明
- 原样输出
extern "C" { ... }块(保留 FFI 链接声明) - 为每个函数生成
pub fn safe_<name>(...) -> ...:unsafe块收敛到生成代码内部,调用者无需写unsafe*const c_char参数 → 接收&str,内部CString转换(检测内部 NUL)*const c_char返回值 → 自动转String(CStr借用,不接管所有权)(*mut c_char, usize)参数对 → buffer 模式,safe 函数省略这两个参数,内部分配 4KB buffer 调用,返回String- 末尾兜底 NUL,防止 C 函数漏写 NUL 导致越界读
参数类型转换规则
| C 函数签名 | safe 函数签名 | 转换策略 |
|---|---|---|
fn foo(x: i32) -> i32 |
fn safe_foo(x: i32) -> i32 |
原样透传 |
fn foo(s: *const c_char) -> i32 |
fn safe_foo(s: &str) -> i32 |
CString::new(s) → .as_ptr() |
fn foo() -> *const c_char |
fn safe_foo() -> String |
CStr::from_ptr → .to_str().unwrap_or_default().to_owned() |
fn foo(buf: *mut c_char, len: usize) -> usize |
fn safe_foo() -> String |
内部分配 4KB buffer,末尾兜底 NUL,CStr 转 String |
fn foo(p: *const c_char, buf: *mut c_char, len: usize) |
fn safe_foo(p: &str) -> String |
普通参数 + buffer 对混合 |
fn foo() -> () |
fn safe_foo() |
无返回值,直接调用 |
fn foo(s: Option<*const c_char>) |
fn safe_foo(s: Option<&str>) |
可空指针,Some 时按 &str 转换 |
fn foo(arr: *const *const c_char) |
fn safe_foo(arr: &[&str]) |
字符串数组 |
长度类型识别:usize / u64 / u32 / isize / i64 / i32 / size_t 均视为 buffer 长度参数。
示例 1:*const c_char 参数与返回值
use c_wrap;
use c_char;
// 用 #[no_mangle] Rust fn 模拟 C 函数
pub extern "C"
pub extern "C"
c_wrap!
// 生成的 safe_my_greet() -> String, safe_my_echo(&str) -> String
assert_eq!;
assert_eq!;
// CString::new 检测内部 NUL, panic 信息含参数名
// safe_my_echo("a\0b"); // panic: CString::new failed for `s` (interior NUL byte)
示例 2:buffer 模式
use c_wrap;
use c_char;
pub extern "C"
// 带 prefix 的混合签名: (普通 *const c_char) + (buffer 对)
pub extern "C"
c_wrap!
// buffer 对被省略, safe 函数只接收普通参数
assert_eq!;
assert_eq!;
// 即使 C 函数返回 i32, buffer 模式下 safe_ 仍返回 String
ensure! / bail! / throw!
对标 anyhow 生态的三个错误传播宏,返回 Err(format!(...).into()),与任何 From<String> 的错误类型兼容。
| 宏 | 语义 | 等价展开 |
|---|---|---|
ensure!(cond, msg, args...) |
条件断言,!cond 时返回错误 |
if !(cond) { return Err(format!(msg, args...).into()); } |
bail!(msg, args...) |
立即返回错误 | return Err(format!(msg, args...).into()); |
throw!(msg, args...) |
bail! 别名 |
同 bail! |
示例
use ;
assert_eq!;
assert!;
assert!; // bail! 触发
短路求值
ensure! 条件为 true 时,错误消息参数不求值:
use ensure;
use Cell;
let called = new;
assert!;
assert!;
assert!;
assert!;
dict! / btree_dict! / set! / btree_set!
用 k: v, k: v, ... 或 k => v, k => v, ... 语法构造 HashMap / BTreeMap,用 v, v, ... 语法构造 HashSet / BTreeSet,对标 maplit。
- key 自动
.into()(仅dict!/btree_dict!):适配&str → String等场景 - value / set 元素原样保留:不调用
.into() with_capacity预分配:dict!/set!使用HashMap::with_capacity(N)/HashSet::with_capacity(N)(N = 字面量元素数),避免插入时多次 rehash;btree_dict!/btree_set!因 BTree 系无with_capacity方法,保持new()- trailing comma:四个宏均支持末尾逗号
- 内部变量
__dict_map_inner/__set_inner:避免污染用户作用域 - 双语法(仅
dict!/btree_dict!)::原生风格,=>maplit 风格,二者等价
示例
use ;
use ;
// dict! — 原生 : 语法
let m: = dict! ;
assert_eq!;
// dict! — maplit 风格 => 语法 (与 : 等价)
let m: = dict! ;
// btree_dict! — 自动按 key 排序
let m: = btree_dict! ;
let keys: = m.keys.copied.collect;
assert_eq!;
// 空字典
let empty: = dict! ;
assert!;
// value 原样保留 (不 .into())
let m: = btree_dict! ;
// set! — HashSet 字面量, with_capacity 预分配
let s: = set! ;
assert_eq!;
assert!;
// btree_set! — BTreeSet 字面量, 自动按值排序
let s: = btree_set! ;
let vals: = s.iter.collect;
assert_eq!;
// 空集合
let empty: = set! ;
assert!;
基准测试
benches/bench_main.rs 使用 criterion 对 9 个维度做对比,运行 cargo bench 即可:
| 基准组 | 对比项 | 说明 |
|---|---|---|
dict_vs_hashmap_from |
dict! vs HashMap::from([...]) |
10 entry 字面量构造 |
btree_dict_vs_btreemap_from |
btree_dict! vs BTreeMap::from([...]) |
10 entry 字面量构造 |
builder_vs_direct |
Builder::builder()...build() vs 直接字面量 |
3 字段构造 |
make_vs_builder_vs_direct |
make! vs Builder 链式 vs 直接字面量 |
make! 语法糖开销 |
dict_merge_vs_manual |
dict!(base; ...) vs 手动 extend vs 从零构造 |
字典合并开销 |
set_vs_hashset_from |
set! vs HashSet::from([...]) vs 手动 insert |
with_capacity 影响 |
builder_setter_prefix |
with_xxx vs xxx vs set_xxx |
setter 前缀 (期望零开销) |
builder_strip_option |
默认 vs setter(strip_option) |
Option 字段开销 |
field_defaults_vs_individual |
field_defaults vs 逐字段 default |
配置方式 (期望零开销) |
实测结果(Windows / criterion 0.5 / 100 样本均值)
| 基准组 | 函数 | 耗时 (ns) |
|---|---|---|
dict_vs_hashmap_from |
dict_macro_10 |
880.6 |
hashmap_from_10 |
952.2 | |
btree_dict_vs_btreemap_from |
btree_dict_macro_10 |
1166.4 |
btreemap_from_10 |
901.9 | |
builder_vs_direct |
builder_construct |
137.4 |
direct_construct |
128.7 | |
make_vs_builder_vs_direct |
make_macro |
67.3 |
builder_chain |
76.6 | |
direct_literal |
60.7 | |
dict_merge_vs_manual |
dict_macro_merge |
293.2 |
manual_merge |
187.9 | |
dict_from_scratch_3 |
173.3 | |
set_vs_hashset_from |
set_macro_5 |
188.8 |
hashset_from_5 |
206.6 | |
manual_insert_5 |
274.8 | |
builder_setter_prefix |
prefix_with |
40.7 |
prefix_empty |
39.5 | |
prefix_set |
40.2 | |
builder_strip_option |
default_option |
50.6 |
strip_option |
47.8 | |
field_defaults_vs_individual |
field_defaults |
0.23 |
individual_defaults |
0.36 |
关键结论
零开销特性(编译期展开,运行时无差异):
setter(prefix):三种前缀(with_/""/set_)性能持平(39-41 ns),方法名在编译期决定,不影响运行时field_defaultsvs 逐字段default:均为亚纳秒级(0.2-0.4 ns,约 1 cycle),编译器将常量构造完全折叠,两种配置方式生成等价代码setter(strip_option):默认(50.6 ns)与strip_option(47.8 ns)几乎相同,仅少生成一个_optionsetter 方法,运行时执行路径一致
有可测开销的特性:
make!宏(67.3 ns)vs 直接字面量(60.7 ns):make!展开为builder().with_xxx().build().expect(),多了Option包装与必填校验,约 11% 开销;与Builder链式(76.6 ns)持平甚至略快(单表达式更易内联)dict!(base; ...)合并(293.2 ns):显著慢于手动extend(187.9 ns)与从零构造(173.3 ns)。原因:宏为支持base为表达式(而非仅变量),创建新HashMap并extend(base)复制,多一次分配与拷贝。若base已是变量,手动let mut m = base; m.insert(...)更快set!宏(188.8 ns)比HashSet::from(206.6 ns)略快(约 9%),两者都with_capacity预分配;手动insert无预分配最慢(274.8 ns)Builder链式(137.4 ns)vs 直接字面量(128.7 ns):约 7% 开销,源于Option包装与必填校验
所有 proc_macro 特性在编译期展开,运行时只见生成代码。配置类属性(
prefix/field_defaults/strip_option)经实测确认零运行时开销;仅make!(语法糖,调用 builder)与dict!(base;)(额外拷贝)有可测开销,但均在工程可接受范围。
运行单组基准:
Python → Rust 迁移对照
下表把 Python 常见写法逐一映射到 pyruts 等价用法,便于从 Python 迁移或对照学习。make! 与 dict!(base; ...) 为规划中语法,未实现前请用右侧的 builder() / 手动 extend 等价写法。
| Python | pyruts Rust | 说明 |
|---|---|---|
Config(name="a", age=30) |
make!(Config { name: "a", age: 30 }) 或 Config::builder().with_name("a").with_age(30).build().unwrap() |
结构体构造 |
{"a": 1, "b": 2} |
dict! { "a" => 1, "b" => 2 } 或 dict! { "a": 1, "b": 2 } |
字典字面量 |
{**base, "new": 1} |
dict!(base; "new" => 1) |
字典合并 |
{"a", "b"} (set) |
set! { "a", "b" } |
集合字面量 |
assert x > 0, "msg" |
ensure!(x > 0, "msg"); |
断言 |
raise ValueError("msg") |
bail!("msg"); |
抛出错误 |
try: ... except: ... |
let r = func()?; 或 match func() { Ok(_) => ..., Err(e) => ... } |
错误处理 |
class Config: ... |
#[derive(Builder)] struct Config { ... } |
类定义 |
@dataclass |
#[derive(Builder, Default)] struct Config { ... } |
数据类 |
__post_init__ |
#[builder(validate = "fn")] |
构造后校验 |
field(default=0) |
#[builder(default)] 或 #[builder(default = "0")] |
默认值 |
field(default_factory=list) |
#[builder(default = "Vec::new()")] |
默认工厂 |
Optional[str] = None |
field: Option<String> + #[builder(default)] |
可选字段 |
List[int] + append |
Vec<i32> + #[builder(each = "item")] |
列表追加 |
Config(name="a").rename("bob") |
#[builder(setter = "rename")] |
方法重命名 |
迁移提示
- 静态类型 vs 动态类型:Rust 是静态类型,Python 是动态类型。pyruts 不能消除类型标注,但
#[derive(Builder)]把样板代码压到一行 derive,配setter(into)让&str自动转String,体验接近 Python 关键字参数。 - Result vs 异常:Rust 没有异常,错误用
Result<T, E>表达。ensure!/bail!是函数内return Err(...)的语法糖,不是 throw,跨函数传播必须靠?或显式match。 - Option vs None:Rust 没有
None字面量,可空值用Option<T>。Builder 的Option<T>字段缺省即None,无需显式= None,调用方未 set 即得None。 - dict! vs dict literal:Rust 没有 dict 字面量,
dict!宏提供:与=>两种语法,key 自动.into()适配&str → String,with_capacity预分配避免 rehash。 - 所有权 vs GC:Rust 没有 GC,所有权与生命周期必须显式管理。
c_wrap!生成的safe_<name>把unsafe收敛到生成代码内部,owned/free模式自动 RAII 释放,避免手动free漏调。
设计哲学
- 零运行时开销:proc_macro 在编译期展开,不引入任何运行时类型或 trait object
- 向后兼容:所有生成 API 用绝对路径(
::std::...),避免与用户use冲突;宏语义版本化,新增属性不破坏旧代码 - 最小依赖:仅依赖
syn/quote/proc-macro2三件套,dev-dependencies 仅libc与criterion - unsafe 隔离:
c_wrap!把 FFIunsafe收敛到生成代码内部,调用者只调safe_<name>;buffer 模式末尾兜底 NUL,防御 C 函数漏写 - API 一致性:宏命名与语义严格对齐
anyhow/derive_builder/maplit,降低学习成本
MSRV
最低支持 Rust 1.70。CI 在 1.70 与 stable 双版本上跑测试。
License
MIT OR Apache-2.0,任选其一。