nutype

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/greyblake/nutype/master/art/rust_nutype_inverted.png"> <source media="(prefers-color-scheme: light)" srcset="https://yellow-cdn.veclightyear.com/ab5030c0/977c3a97-0764-4618-945a-562e8e2c1fe0.png"> <img width="300" alt="Rust Nutype Logo" src="https://yellow-cdn.veclightyear.com/ab5030c0/977c3a97-0764-4618-945a-562e8e2c1fe0.png"> </picture> </p> <h2 align="center">具有保证的新类型。</h2> <p align="center"> <a href="https://github.com/greyblake/nutype/actions/workflows/ci.yml" rel="nofollow"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/b23cc796-7700-40ca-bc5f-e893732465a8.svg" alt="Nutype 构建状态"></a> <a href="https://docs.rs/nutype" rel="nofollow"><img src="https://yellow-cdn.veclightyear.com/ab5030c0/77d04dc4-3d3b-43d0-81f3-e4ea727bff13.svg" alt="Nutype 文档"></a> <a href="https://github.com/greyblake/nutype/discussions"><img src="https://img.shields.io/github/discussions/greyblake/nutype"/></a> <p>

Nutype 是一个过程宏，它允许在常规的新类型模式基础上添加额外的约束，如_清理_和_验证_。生成的代码使得在不通过检查的情况下实例化值变得不可能。即使使用 serde 反序列化也是如此。

• 快速开始
• 内部类型 (String | 整数 | 浮点数 | 其他)
• 自定义 (清理器 | 验证器)
• 使用案例
• 使用 new_unchecked 绕过约束
• 特性标志
• 支持乌克兰军队
• 类似项目

快速开始

use nutype::nutype;

// 定义新类型 Username
#[nutype(
    sanitize(trim, lowercase),
    validate(not_empty, len_char_max = 20),
    derive(Debug, PartialEq, Clone),
)]
pub struct Username(String);

// 我们可以通过 `::try_new()` 获取 Username 的值。
// 注意 Username 持有一个经过清理的字符串
assert_eq!(
    Username::try_new("   FooBar  ").unwrap().into_inner(),
    "foobar"
);

// 不可能获得一个无效的 Username
// 注意我们还根据验证规则隐式生成了 `UsernameError` 枚举。
assert_eq!(
    Username::try_new("   "),
    Err(UsernameError::NotEmptyViolated),
);
assert_eq!(
    Username::try_new("TheUserNameIsVeryVeryLong"),
    Err(UsernameError::LenCharMaxViolated),
);

更多信息请参见：

• 示例
• 测试

内部类型

可用的清理器、验证器和可派生的特征由内部类型决定，内部类型分为以下几类：

• 字符串
• 整数（u8、u16、u32、u64、u128、i8、i16、i32、i64、i128、usize、isize）
• 浮点数（f32、f64）
• 其他任何类型

字符串

目前字符串内部类型仅支持 String（拥有所有权的）类型。

字符串清理器

清理器	描述	示例
trim	移除首尾空白字符	trim
lowercase	将字符串转换为小写	lowercase
uppercase	将字符串转换为大写	uppercase
with	自定义清理器。接收 String 并返回 String 的函数或闭包	with = |mut s: String| { s.truncate(5); s }

字符串验证器

验证器	描述	错误变体	示例
len_char_min	字符串的最小长度（以字符计，非字节）	LenCharMinViolated	len_char_min = 5
len_char_max	字符串的最大长度（以字符计，非字节）	LenCharMaxViolated	len_char_max = 255
not_empty	拒绝空字符串	NotEmptyViolated	not_empty
regex	使用正则表达式验证格式。需要 regex 特性。	RegexViolated	regex = "^[0-9]{7}$" 或 regex = ID_REGEX
predicate	自定义验证器。接收 &str 并返回 bool 的函数或闭包	PredicateViolated	predicate = |s: &str| s.contains('@')

正则表达式验证

要求：

• 启用 nutype 的 regex 特性。
• 你必须显式包含 regex 作为依赖项。

使用正则表达式有多种方式。

可以直接在原地定义正则表达式：

#[nutype(validate(regex = "^[0-9]{3}-[0-9]{3}$"))]
pub struct PhoneNumber(String);

或者可以使用 std::sync::LazyLock 定义:

use regex::Regex;

static PHONE_NUMBER_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new("^[0-9]{3}-[0-9]{3}$").unwrap());

#[nutype(validate(regex = PHONE_NUMBER_REGEX))]
pub struct PhoneNumber(String);

或者可以使用 lazy_static 定义:

use lazy_static::lazy_static;
use regex::Regex;

lazy_static! {
    static ref PHONE_NUMBER_REGEX: Regex = Regex::new("^[0-9]{3}-[0-9]{3}$").unwrap();
}

#[nutype(validate(regex = PHONE_NUMBER_REGEX))]
pub struct PhoneNumber(String);

或者 once_cell:

use once_cell::sync::Lazy;
use regex::Regex;

static PHONE_NUMBER_REGEX: Lazy<Regex> =
    Lazy::new(|| Regex::new("[0-9]{3}-[0-9]{3}$").unwrap());

#[nutype(validate(regex = PHONE_NUMBER_REGEX))]
pub struct PhoneNumber(String);

字符串可派生的特征

以下特征可以为基于字符串的类型派生: Debug, Clone, PartialEq, Eq, PartialOrd, Ord, FromStr, AsRef, Deref, From, TryFrom, Into, Hash, Borrow, Display, Default, Serialize, Deserialize。

整数

整数内部类型有: u8, u16,u32, u64, u128, i8, i16, i32, i64, i128, usize, isize。

整数净化器

净化器	描述	示例
with	自定义净化器	with = |raw| raw.clamp(0, 100)

整数验证器

验证器	描述	错误变体	示例
less	独占上界	LessViolated	less = 100
less_or_equal	包含上界	LessOrEqualViolated	less_or_equal = 99
greater	独占下界	GreaterViolated	greater = 17
greater_or_equal	包含下界	GreaterOrEqualViolated	greater_or_equal = 18
predicate	自定义谓词	PredicateViolated	predicate = |num| num % 2 == 0

整数可派生的特征

以下特征可以为基于整数的类型派生: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, FromStr, AsRef, Deref, Into, From, TryFrom, Hash, Borrow, Display, Default, Serialize, Deserialize。

浮点数

浮点数内部类型有: f32, f64。

浮点数净化器

净化器	描述	示例
with	自定义净化器	with = |val| val.clamp(0.0, 100.0)

浮点数验证器

验证器	描述	错误变体	示例
less	独占上界	LessViolated	less = 100.0
less_or_equal	包含上界	LessOrEqualViolated	less_or_equal = 100.0
greater	独占下界	GreaterViolated	greater = 0.0
greater_or_equal	包含下界	GreaterOrEqualViolated	greater_or_equal = 0.0
finite	检查是否为NaN和无穷大	FiniteViolated	finite
predicate	自定义谓词	PredicateViolated	predicate = |val| val != 50.0

浮点数可派生的特征

以下特征可以为基于浮点数的类型派生: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, FromStr, AsRef, Deref, Into, From, TryFrom, Hash, Borrow, Display, Default, Serialize, Deserialize。

如果验证规则保证排除了 NaN，也可以派生 Eq 和 Ord。 这可以通过应用 finite 验证来实现。例如:

#[nutype(
    validate(finite),
    derive(PartialEq, Eq, PartialOrd, Ord),
)]
struct Size(f64);

其他内部类型和泛型

对于任何其他类型，可以使用 with 定义自定义净化器，使用 predicate 定义自定义验证:

use nutype::nutype;

#[nutype(
    derive(Debug, PartialEq, AsRef, Deref),
    sanitize(with = |mut guests| { guests.sort(); guests }),
    validate(predicate = |guests| !guests.is_empty() ),
)]
pub struct GuestList(Vec<String>);

也可以使用泛型:

#[nutype(
    sanitize(with = |mut v| { v.sort(); v }),
    validate(predicate = |vec| !vec.is_empty()),
    derive(Debug, PartialEq, AsRef, Deref),
)]
struct SortedNotEmptyVec<T: Ord>(Vec<T>);

让 wise_friends = SortedNotEmptyVec::try_new(vec!["Seneca", "Zeno", "Plato"]).unwrap(); assert_eq!(wise_friends.as_ref(), &["Plato", "Seneca", "Zeno"]); assert_eq!(wise_friends.len(), 3);

let numbers = SortedNotEmptyVec::try_new(vec![4, 2, 7, 1]).unwrap(); assert_eq!(numbers.as_ref(), &[1, 2, 4, 7]); assert_eq!(numbers.len(), 4);

自定义净化器

你可以使用 with 选项设置自定义净化器。 自定义净化器是一个接收内部类型值所有权并返回净化后值的函数或闭包。

例如，这个

#[nutype(sanitize(with = new_to_old))]
pub struct CityName(String);

fn new_to_old(s: String) -> String {
    s.replace("New", "Old")
}

等同于下面这个:

#[nutype(sanitize(with = |s| s.replace("New", "Old") ))]
pub struct CityName(String);

并且工作方式相同:

let city = CityName::new("New York");
assert_eq!(city.into_inner(), "Old York");

自定义验证器

类似地,也可以定义自定义验证器,但验证函数接收一个引用并返回 bool。 可以将其视为一个谓词。

#[nutype(validate(predicate = is_valid_name))]
pub struct Name(String);

fn is_valid_name(name: &str) -> bool {
    // 一种验证第一个字符是否大写的巧妙方法
    name.chars().next().map(char::is_uppercase).unwrap_or(false)
}

实用技巧

派生 Default

#[nutype(
    derive(Default),
    default = "Anonymous",
)]
pub struct Name(String);

为浮点类型派生 Eq 和 Ord

使用 nutype 可以在设置了 finite 验证的情况下派生 Eq 和 Ord。 finite 验证确保有效值排除了 NaN。

#[nutype(
    validate(finite),
    derive(PartialEq, Eq, PartialOrd, Ord),
)]
pub struct Weight(f64);

使用 new_unchecked 突破限制

虽然不推荐,但可以通过启用 new_unchecked crate 特性并用 new_unchecked 标记类型来绕过限制:

#[nutype(
    new_unchecked,
    sanitize(trim),
    validate(len_char_min = 8)
)]
pub struct Name(String);

// 是的,你被迫在这里使用 `unsafe`,所以每个人都会指责你。
let name = unsafe { Name::new_unchecked(" boo ".to_string()) };

// `name` 违反了净化和验证规则!!!
assert_eq!(name.into_inner(), " boo ");

特性标志

• arbitrary - 启用 arbitrary::Arbitrary 的派生。
• new_unchecked - 启用不安全的 ::new_unchecked() 函数的生成。
• regex - 允许在基于字符串的类型上使用 regex = 验证。注意:你的 crate 也必须在其依赖项中明确包含 regex。
• serde - 与 serde crate 的集成。允许派生 Serialize 和 Deserialize trait。
• schemars08 - 允许派生 schemars crate 的 JsonSchema trait。注意目前不遵守验证规则。
• std - 默认启用。使用 default-features = false 禁用。

什么时候 nutype 适合你?

• 如果你喜欢 newtype 模式,并且你喜欢利用 Rust 类型系统来强制业务逻辑正确性的想法。
• 如果你想使用类型系统来保持不变量。
• 如果你是 DDD 的粉丝,nutype 是一个很好的助手,可以使你的领域模型更具表现力。
• 你想快速原型开发而不牺牲质量。

什么时候 nutype 不那么好?

• 你过于关心编译时间(nutype 依赖于大量使用过程宏)。
• 你认为元编程太过隐式魔法。
• IDE 可能在为你提供关于过程宏的提示方面不太有帮助。
• nutype 的设计可能会强制你运行不必要的验证(例如在从数据库加载数据时),如果你追求极致性能,这可能会产生负面影响。

支持乌克兰军队

今天我住在柏林,我有幸过着身体安全的生活。 但我是乌克兰人。我人生的前25年我在 哈尔科夫 度过, 那是乌克兰第二大城市,距离俄罗斯边境60公里。今天 我家乡城市约三分之一被俄罗斯人摧毁。 我的父母、亲戚和朋友不得不在地下室生活了一个多月,以躲避炮火和空袭。

他们中的一些人设法撤离到了欧盟。其他一些人试图在哈尔科夫过"正常生活",完成日常工作。 还有一些人现在正在前线,每一秒都在冒着生命危险保护其他人。

我鼓励你向 Serhiy Prytula 慈善基金会 捐款。 只需选择你喜欢的项目并捐款。这是最知名的基金会之一,你可以观看一部关于它的 小纪录片。 你对乌克兰军队的贡献就是对我平静的贡献,这样我就可以花更多时间开发这个项目。

谢谢你。

类似项目

• prae - 一个非常相似的 crate，旨在解决同样的问题，但采用略微不同的方法。
• bounded-integer - Rust 的有界整数。
• refinement - 方便创建类型安全的细化类型（基于泛型）。
• semval - Rust 的语义验证。
• validator - Rust 结构体的简单验证（由宏驱动）。

许可证

MIT © Serhii Potapov