32 个版本 (20 个破坏性更新)
新版本 0.20.0 | 2024 年 8 月 22 日 |
---|---|
0.19.1 | 2024 年 7 月 14 日 |
0.18.2 | 2024 年 4 月 16 日 |
0.18.1 | 2024 年 1 月 16 日 |
0.1.0 | 2017 年 10 月 5 日 |
在 Rust 模式 中排名第 25
每月下载量 946,987 次
用于 892 个crate(245 个直接使用)
30KB
180 行
Rust 类型化构建器
创建一个编译时验证的构建器
use typed_builder::TypedBuilder;
#[derive(TypedBuilder)]
struct Foo {
// Mandatory Field:
x: i32,
// #[builder(default)] without parameter - use the type's default
// #[builder(setter(strip_option))] - wrap the setter argument with `Some(...)`
#[builder(default, setter(strip_option))]
y: Option<i32>,
// Or you can set the default
#[builder(default=20)]
z: i32,
}
按任意顺序构建
Foo::builder().x(1).y(2).z(3).build();
Foo::builder().z(1).x(2).y(3).build();
省略可选字段(标记为 #[default]
的字段)
Foo::builder().x(1).build()
但您不能省略非可选参数 - 否则无法编译
Foo::builder().build(); // missing x
Foo::builder().x(1).y(2).y(3); // y is specified twice
功能
- 用于生成构建器模式的自定义 derive。
- 能够使用
#[builder(setter(into))
来注释字段,使其设置器可以接受Into
值。 - 在调用
.build()
之前,对所有字段进行编译时验证。 - 对每个字段只进行一次设置的编译时验证。
- 能够使用
#[builder(default)]
来注释字段,使其可选并在用户未设置时指定默认值。 - 为
.builder()
方法生成简单的文档。 - 可自定义
.build()
方法的名称和可见性。
限制
- 当您未设置字段或将字段描述为实际问题作为弃用警告,而不是主要错误时,构建将出现错误。
- 生成的构建器类型具有丑陋的内部名称和许多泛型参数。它不是用于传递和执行花哨的构建器技巧,而是为了更简洁的对象创建语法(具有命名参数和可选参数的构造函数)。
- 因此,所有构建器方法都是按值调用,并且构建器不可克隆。这避免了确定字段是否可克隆的麻烦...
- 如果您需要一个可以传递的构建器,请查看 derive-builder。它的API与typed-builder不冲突,因此您可以在同一类型上实现它们。
冲突
TypedBuilder
接受任意Rust代码作为#[builder(default = ...)]
,但其他自定义 derive proc-macro 包可能尝试使用较旧的限制来解析它们,这些限制只允许使用字面量。为了解决这个问题,请使用#[builder(default_code = "...")]
代替。
替代方案 - 以及为什么 typed-builder 更好
- derive-builder - 在运行时执行所有检查,返回一个需要您解包的
Result
。 - safe-builder-derive - 这一个在编译时进行检查 - 通过为构建器的每个可能状态生成一个类型。Rust 可以删除死代码,但您的构建时间仍然会呈指数增长。typed-builder 是通过泛型参数编码构建器的状态,因此 Rust 只会生成您实际使用的路径。
许可
根据您的选择,许可协议为以下之一
- Apache License,版本 2.0(《LICENSE-APACHE》或 http://www.apache.org/licenses/LICENSE-2.0)
- MIT 许可证(《LICENSE-MIT》或 http://opensource.org/licenses/MIT)
。
贡献
除非您明确说明,否则您提交给工作以包含在内的任何贡献,根据 Apache-2.0 许可证定义,应按上述方式双重许可,不附加任何额外条款或条件。
依赖项
~250–690KB
~16K SLoC