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 ");