開發程式的時候,常會需要讓程式能與使用者或其它程式互動,透過文字介面、圖形介面或是通訊協定標準,從外部取得資料來進行更進一步的處理。尤其是當使用者在使用我們的程式時,由於我們沒有辦法限制他們輸入的資料一定要符合程式設計的格式,程式很可能就會因錯誤的輸入而造成錯誤的輸出,甚至對整個系統的安全性造成威脅。所以通常我們在處理外部進來的資料時,會先檢查它們的格式後再進行處理。
Validators
「Validators」是筆者開發的套件,可以將使用者輸入的資料進行驗證並順便模型化(反序列化)。利用程序式巨集,在定義結構體的同時決定這個結構體要套用哪個驗證器(validator),以及設定相關的參數。
Crates.io
Cargo.toml
基本使用方法
[dependencies]
validators = "*"
use validators::prelude::*;
/*
#[derive(Validator)]
#[validator(validator_name)]
DEFINE_YOUR_STRUCT_HERE
*/
當我們替結構體添加#[validator(validator_name)]
屬性時,一個或多個於validators::traits
模組中的特性也會跟著被實作出來。它們可以用來進行驗證以及反序列化。
作為驗證器的結構體,必須要根據其是哪種驗證器以及驗證器的參數來定義它的組成欄位。例如,一個base32
的驗證器,結構體會長成這樣:struct(String)
;而一個base32_decoded
的驗證器,結構體會長成這樣:struct(Vec<u8>)
。
#[validator(validator_name)]
屬性不可以被用在結構體或是列舉中的欄位上。這個套件之所以會選擇使用程序式巨集來定義驗證器(結構體),而不是對每種驗證器的組態設定提供內建的結構體的原因是要讓可組態設定的驗證項目在程式執行階段不會有任何的開支(overhead),而且也可以提高編譯速度。
無標準函式庫(No Std)
有些驗證器,像是ip
、ipv4
、ipv6
需要依賴標準函式庫。如果不需要用到它們的話,可以關掉預設的特色,來讓這個套件可以在無標準函式庫的情況下被編譯。
[dependencies.validators]
version = "*"
default-features = false
features = ["derive", "base32"]
Serde框架支援
啟用serde
特色,來讓這個套件支援Serde框架。
[dependencies.validators]
version = "*"
features = ["serde"]
Rocket框架支援
啟用rocket
特色,來讓這個套件支援Rocket框架。
[dependencies.validators]
version = "*"
features = ["rocket"]
驗證器
base32
特性:ValidateString
、ValidateBytes
use validators::prelude::*;
#[derive(Validator)]
#[validator(base32(padding(Must)))]
pub struct Base32WithPadding(String);
assert!(Base32WithPadding::parse_string("GEZDGNBVGY3TQOI=").is_ok());
assert!(Base32WithPadding::parse_string("GEZDGNBVGY3TQOI").is_err());
base32_decoded
特性:ValidateString
、ValidateBytes
、CollectionLength
use validators::prelude::*;
#[derive(Validator)]
#[validator(base32_decoded(padding(Must)))]
pub struct Base32WithPaddingDecoded(Vec<u8>);
assert_eq!(b"123456789", Base32WithPaddingDecoded::parse_string("GEZDGNBVGY3TQOI=").unwrap().0.as_slice());
base64
特性:ValidateString
、ValidateBytes
use validators::prelude::*;
#[derive(Validator)]
#[validator(base64(padding(Must)))]
pub struct Base64WithPadding(String);
assert!(Base64WithPadding::parse_string("MTIzNDU2Nzg5MA==").is_ok());
assert!(Base64WithPadding::parse_string("MTIzNDU2Nzg5MA").is_err());
base64_decoded
特性:ValidateString
、ValidateBytes
、CollectionLength
use validators::prelude::*;
#[derive(Validator)]
#[validator(base64_decoded(padding(Must)))]
pub struct Base64WithPaddingDecoded(Vec<u8>);
assert_eq!(b"1234567890", Base64WithPaddingDecoded::parse_string("MTIzNDU2Nzg5MA==").unwrap().0.as_slice());
base64_url
特性:ValidateString
、ValidateBytes
use validators::prelude::*;
#[derive(Validator)]
#[validator(base64_url(padding(NotAllow)))]
pub struct Base64WithoutPaddingUrl(String);
assert!(Base64WithoutPaddingUrl::parse_string("PmR8hJhjgVNcB61zqhc_B2duZ7ld8Gy1GW2xSBVzeno").is_ok());
base64_url_decoded
特性:ValidateString
、ValidateBytes
、CollectionLength
use validators::prelude::*;
#[derive(Validator)]
#[validator(base64_url_decoded(padding(NotAllow)))]
pub struct Base64WithoutPaddingUrlDecoded(Vec<u8>);
assert_eq!([62, 100, 124, 132, 152, 99, 129, 83, 92, 7, 173, 115, 170, 23, 63, 7, 103, 110, 103, 185, 93, 240, 108, 181, 25, 109, 177, 72, 21, 115, 122, 122], Base64WithoutPaddingUrlDecoded::parse_string("PmR8hJhjgVNcB61zqhc_B2duZ7ld8Gy1GW2xSBVzeno").unwrap().0.as_slice());
boolean
特性:ValidateString
、ValidateChar
、ValidateSignedInteger
、ValidateUnignedInteger
、ValidateBoolean
use validators::prelude::*;
#[derive(Validator)]
#[validator(boolean)]
pub struct Boolean(bool);
assert_eq!(true, Boolean::parse_str("true").unwrap().0);
assert_eq!(false, Boolean::parse_str("f").unwrap().0);
assert_eq!(true, Boolean::parse_str("y").unwrap().0);
assert_eq!(false, Boolean::parse_str("no").unwrap().0);
assert_eq!(true, Boolean::parse_str("on").unwrap().0);
assert_eq!(false, Boolean::parse_str("off").unwrap().0);
assert_eq!(true, Boolean::parse_str("1").unwrap().0);
assert_eq!(true, Boolean::parse_char('t').unwrap().0);
assert_eq!(false, Boolean::parse_char('0').unwrap().0);
assert_eq!(true, Boolean::parse_isize(1).unwrap().0);
domain
特性:ValidateString
額外的方法: is_fully_qualified
、get_domain_non_fully_qualified
、to_uri_authority_string
use validators::prelude::*;
#[derive(Validator)]
#[validator(domain(ipv4(Allow), local(Allow), at_least_two_labels(Allow), port(NotAllow)))]
pub struct DomainWithoutPort(pub String);
assert!(DomainWithoutPort::parse_string("example.com").is_ok());
assert_eq!("xn--fiq228c.com", DomainWithoutPort::parse_string("中文.com").unwrap().0);
#[derive(Validator)]
#[validator(domain(ipv4(Allow), local(Allow), at_least_two_labels(Allow), port(Allow)))]
pub struct DomainAllowPort {
pub domain: String,
port: Option<u16>,
}
assert_eq!(Some(8080), DomainAllowPort::parse_string("example.com:8080").unwrap().port);
特性:ValidateString
額外的方法: to_email_string
use validators::prelude::*;
#[derive(Validator)]
#[validator(email(comment(Allow), ip(Allow), local(Allow), at_least_two_labels(Allow), non_ascii(Allow)))]
pub struct EmailAllowComment {
pub local_part: String,
pub need_quoted: bool,
pub domain_part: validators::models::Host,
pub comment_before_local_part: Option<String>,
pub comment_after_local_part: Option<String>,
pub comment_before_domain_part: Option<String>,
pub comment_after_domain_part: Option<String>,
}
assert!(EmailAllowComment::parse_string("(john)joke@example.com").is_ok());
#[derive(Validator)]
#[validator(email(comment(NotAllow), ip(Allow), local(Allow), at_least_two_labels(Allow), non_ascii(Allow)))]
pub struct EmailNotAllowComment {
pub local_part: String,
pub need_quoted: bool,
pub domain_part: validators::models::Host,
}
assert!(EmailNotAllowComment::parse_string("(john)joke@example.com").is_err());
host
特性:ValidateString
額外的方法: to_uri_authority_string
use validators::prelude::*;
#[derive(Validator)]
#[validator(host(local(Allow), at_least_two_labels(Must), port(Allow)))]
pub struct HostMustAtLeastTwoLabelsAllowPort {
pub host: validators::models::Host,
pub port: Option<u16>,
pub is_local: bool,
}
assert!(HostMustAtLeastTwoLabelsAllowPort::parse_string("example.com:8000").is_ok());
assert!(HostMustAtLeastTwoLabelsAllowPort::parse_string("example").is_err());
http_url
特性:ValidateString
use validators::prelude::*;
use validators_prelude::url;
#[derive(Validator)]
#[validator(http_url(local(Allow)))]
pub struct HttpURL {
url: url::Url,
is_https: bool,
}
assert!(HttpURL::parse_string("https://example.org/").is_ok());
assert!(HttpURL::parse_string("http://example.org/").is_ok());
assert!(HttpURL::parse_string("ftp://example.org/").is_err());
http_ftp_url
特性:ValidateString
use validators::prelude::*;
use validators_prelude::url;
#[derive(Validator)]
#[validator(http_ftp_url(local(Allow)))]
pub struct HttpFtpURL {
url: url::Url,
protocol: validators::models::Protocol,
}
assert!(HttpFtpURL::parse_string("https://example.org/").is_ok());
assert!(HttpFtpURL::parse_string("http://example.org/").is_ok());
assert!(HttpFtpURL::parse_string("ftp://example.org/").is_ok());
ip
特性:ValidateString
額外的方法: to_uri_authority_string
use std::net::IpAddr;
use validators::prelude::*;
#[derive(Validator)]
#[validator(ip(local(Allow), port(Allow)))]
pub struct IPAllowPort {
pub ip: IpAddr,
pub port: Option<u16>,
}
assert!(IPAllowPort::parse_string("127.0.0.1").is_ok());
assert!(IPAllowPort::parse_string("[::ffff:c000:0280]:8000").is_ok());
ipv4
特性:ValidateString
額外的方法: to_uri_authority_string
use std::net::Ipv4Addr;
use validators::prelude::*;
#[derive(Validator)]
#[validator(ipv4(local(Allow), port(NotAllow)))]
pub struct IPv4WithoutPort(pub Ipv4Addr);
assert!(IPv4WithoutPort::parse_string("127.0.0.1").is_ok());
ipv6
特性:ValidateString
額外的方法: to_uri_authority_string
use std::net::Ipv6Addr;
use validators::prelude::*;
#[derive(Validator)]
#[validator(ipv6(local(Allow), port(NotAllow)))]
pub struct IPv6WithoutPort(pub Ipv6Addr);
assert!(IPv6WithoutPort::parse_string("::ffff:c000:0280").is_ok());
assert!(IPv6WithoutPort::parse_string("[::ffff:c000:0280]").is_ok());
json
特性:ValidateString
、ValidateSignedInteger
、ValidateUnignedInteger
、ValidateNumber
、ValidateBoolean
、ValidateJsonValue
額外的方法: to_minified_json_string
、to_beautified_json_string
use validators::prelude::*;
#[derive(Validator)]
#[validator(json)]
pub struct JSONString(pub String);
#[derive(Validator)]
#[validator(json)]
pub struct JSONNumber(pub f64);
#[derive(Validator)]
#[validator(json)]
pub struct JSONBoolean(pub bool);
assert!(JSONString::parse_string("123").is_err());
assert!(JSONString::parse_string("\"123\"").is_ok());
assert!(JSONNumber::parse_u64(123).is_ok());
assert!(JSONBoolean::parse_bool(false).is_ok());
length
特性:ValidateString
、CollectionLength
use validators::prelude::*;
#[derive(Validator)]
#[validator(length(min = 1, max = 3))]
pub struct NonEmptyNotTooLongVec(pub Vec<u8>);
assert!(NonEmptyNotTooLongVec::parse_collection(vec![]).is_err());
assert!(NonEmptyNotTooLongVec::parse_collection(vec![0]).is_ok());
assert!(NonEmptyNotTooLongVec::parse_collection(vec![0, 1, 2, 3]).is_err());
line
特性:ValidateString
use validators::prelude::*;
#[derive(Validator)]
#[validator(line(char_length(trimmed_min = 1, min = 1, max = 1000)))] // `byte_length` can also be used
pub struct LineNotAllowEmpty(pub String);
assert!(LineNotAllowEmpty::parse_string("123").is_ok());
assert!(LineNotAllowEmpty::parse_string("123\0").is_err());
assert!(LineNotAllowEmpty::parse_string("123\n456").is_err());
assert!(LineNotAllowEmpty::parse_string(" ").is_err());
mac_address
特性:ValidateString
額外的方法:to_mac_address_string
use validators::prelude::*;
#[derive(Validator)]
#[validator(mac_address(case(Upper), separator(Allow(colon))))]
pub struct MacAddress(pub u64);
assert!(MacAddress::parse_string("080027B246C3").is_ok());
assert!(MacAddress::parse_string("08:00:27:B2:46:C3").is_ok());
separator
選項的預設值為Allow(colon)
。
number
特性:ValidateString
、ValidateNumber
use validators::prelude::*;
#[derive(Validator)]
#[validator(number(nan(NotAllow), range(NotLimited)))]
pub struct Double(pub f64);
assert!(Double::parse_string("123.456").is_ok());
assert!(Double::parse_string("NaN").is_err());
assert!(Double::parse_f32(123.4).is_ok());
#[derive(Validator)]
#[validator(number(nan(Allow), range(Inside(min = 0, max = 1.0))))]
pub struct SinglePercentage(pub f32);
assert!(SinglePercentage::parse_string("0").is_ok());
assert!(SinglePercentage::parse_string("1").is_ok());
assert!(SinglePercentage::parse_string("1.1").is_err());
assert!(SinglePercentage::parse_string("NaN").is_ok());
phone
特性:ValidateString
use validators::prelude::*;
use validators_prelude::phonenumber;
use std::collections::HashMap;
#[derive(Validator)]
#[validator(phone)]
pub struct InternationalPhone(pub phonenumber::PhoneNumber);
#[derive(Validator)]
#[validator(phone(TW))]
pub struct TWPhone(pub phonenumber::PhoneNumber);
#[derive(Validator)]
#[validator(phone(TW, US))]
pub struct TWorUSPhone(
pub HashMap<phonenumber::country::Id, phonenumber::PhoneNumber>,
);
assert!(InternationalPhone::parse_string("+886912345678").is_ok());
assert!(InternationalPhone::parse_string("0912345678").is_err());
assert!(InternationalPhone::parse_string("+14155552671").is_ok());
assert!(TWPhone::parse_string("+886912345678").is_ok());
assert!(TWPhone::parse_string("0912345678").is_ok());
assert!(TWPhone::parse_string("+14155552671").is_err());
assert!(TWorUSPhone::parse_string("+886912345678").is_ok());
assert!(TWorUSPhone::parse_string("0912345678").is_ok());
assert!(TWorUSPhone::parse_string("+14155552671").is_ok());
regex
特性:ValidateString
use validators::prelude::*;
use validators_prelude::regex;
use lazy_static::lazy_static;
use once_cell::sync::Lazy;
lazy_static! {
static ref RE_NON_ZERO_NUMBERS: regex::Regex = regex::Regex::new("^[1-9]+$").unwrap();
}
static RE_POKER: Lazy<regex::Regex> = Lazy::new(|| {
regex::Regex::new("^([AJQK1-9]|10)$").unwrap()
});
#[derive(Validator)]
#[validator(regex("^[0-9a-fA-F]+$"))]
pub struct Hex(pub String); // this compiles the regex every time
#[derive(Validator)]
#[validator(regex(RE_NON_ZERO_NUMBERS))]
pub struct NonZeroNumbers(pub String);
#[derive(Validator)]
#[validator(regex(RE_POKER))]
pub struct Poker(pub String);
assert!(Hex::parse_string("1Ab").is_ok());
assert!(Hex::parse_string("1AG").is_err());
assert!(NonZeroNumbers::parse_string("12345").is_ok());
assert!(NonZeroNumbers::parse_string("012345").is_err());
assert!(Poker::parse_string("1").is_ok());
assert!(Poker::parse_string("10").is_ok());
assert!(Poker::parse_string("J").is_ok());
assert!(Poker::parse_string("0").is_err());
semver
特性:ValidateString
use validators::prelude::*;
use validators_prelude::semver;
#[derive(Validator)]
#[validator(semver)]
pub struct SemVer(semver::Version);
assert!(SemVer::parse_string("0.0.0").is_ok());
assert!(SemVer::parse_string("0.0.0-beta.1").is_ok());
semver_req
特性:ValidateString
use validators::prelude::*;
use validators_prelude::semver;
#[derive(Validator)]
#[validator(semver_req)]
pub struct SemVerReq(semver::VersionReq);
assert!(SemVerReq::parse_string("0.0.0").is_ok());
assert!(SemVerReq::parse_string(">= 0.4").is_ok());
signed_integer
特性:ValidateString
、ValidateSignedInteger
use validators::prelude::*;
#[derive(Validator)]
#[validator(signed_integer(range(Inside(min = -1, max = 100))))]
pub struct Score(i8);
assert!(Score::parse_string("0").is_ok());
assert!(Score::parse_string("-2").is_err());
assert!(Score::parse_i8(4).is_ok());
#[derive(Validator)]
#[validator(signed_integer(range(Outside(min = 0, max = 0))))]
pub struct NonZeroShort(i16);
assert!(NonZeroShort::parse_i8(4).is_ok());
assert!(NonZeroShort::parse_i8(-4).is_ok());
assert!(NonZeroShort::parse_i8(0).is_err());
text
特性:ValidateString
use validators::prelude::*;
#[derive(Validator)]
#[validator(text(char_length(trimmed_min = 1, min = 1, max = 1000)))] // `byte_length` can also be used
pub struct TextNotAllowEmpty(pub String);
assert!(TextNotAllowEmpty::parse_string("123").is_ok());
assert!(TextNotAllowEmpty::parse_string("123\0").is_err());
assert!(TextNotAllowEmpty::parse_string("123\n456").is_ok());
assert!(TextNotAllowEmpty::parse_string(" ").is_err());
unsigned_integer
特性:ValidateString
、ValidateUnignedInteger
use validators::prelude::*;
#[derive(Validator)]
#[validator(unsigned_integer(range(Inside(min = 1, max = 100))))]
pub struct Count(u8);
assert!(Count::parse_string("5").is_ok());
assert!(Count::parse_string("0").is_err());
assert!(Count::parse_u8(4).is_ok());
url
特性:ValidateString
use validators::prelude::*;
use validators_prelude::url;
#[derive(Validator)]
#[validator(url)]
pub struct URL(pub url::Url);
assert!(URL::parse_string("https://example.org/").is_ok());
assert!(URL::parse_string("https:example.org").is_ok());
assert!(URL::parse_string("example:").is_ok());
uuid
特性:ValidateString
額外的方法:to_uuid_string
use validators::prelude::*;
#[derive(Validator)]
#[validator(uuid(case(Upper), separator(Allow(hyphen))))]
pub struct UUID(pub u128);
assert!(UUID::parse_string("A866664AF9D34DDE89CB182015FA4F41").is_ok());
assert!(UUID::parse_string("A866664A-F9D3-4DDE-89CB-182015FA4F41").is_ok());
separator
選項的預設值為Allow(hyphen)
。