πΊπΏ uz-types
Rust loyihalari (ayniqsa O'zbekiston domeniga oid backend tizimlar) uchun qat'iy tiplangan (strongly typed), xavfsiz va qayta ishlatiladigan value object kutubxonasi.
Oddiy String o'rniga Passport, Pinfl, PhoneNumber kabi tiplardan foydalanasiz β qiymat tipga faqat validatsiyadan o'tib kiradi, keyin esa u bilan ishlash xavfsiz.
use *;
let passport = parse.unwrap;
assert_eq!; // trim + katta harf avtomatik
let phone = parse.unwrap;
assert_eq!; // ajratuvchilar tozalandi
let pinfl = parse_strict.unwrap;
assert_eq!; // rasmiy checksum + struktura tekshirildi
Mundarija
- Imkoniyatlar
- O'rnatish va feature'lar
- Tezkor boshlash
- Asosiy g'oya: ikki qatlamli validatsiya
- Tiplar
- Xatolar bilan ishlash
- serde integratsiyasi
- sqlx integratsiyasi
- Cheklovlar
- MSRV va semver
- Rivojlantirish
- Litsenziya
Imkoniyatlar
| Nima beradi | |
|---|---|
| Qat'iy tiplash | Passport, Pinfl, PhoneNumber, EmailAddress, BirthDate, Id<Tag>, NumId<Tag>, AccessToken, RefreshToken, ClientId, ClientSecret |
| Yagona konstruktor yo'li | parse(), FromStr, TryFrom, serde Deserialize, sqlx Decode β hammasi bitta validatsiya yo'lidan o'tadi. Validatsiyani chetlab o'tib tip yaratib bo'lmaydi |
| Ikki qatlamli validatsiya | parse() β hech qachon o'zgarmaydigan struktura; parse_strict() β o'zgaruvchan qoidalar (operator kodlari ro'yxati, PINFL checksum) |
| Aniq xatolar | Har bir tipning o'z error enum'i (PassportError, PinflError, β¦); umumiy TypeError ? orqali avtomatik yig'iladi |
| Xavfsiz sirlar | Token tiplarida Display yo'q, Debug yashirilgan, taqqoslash constant-time; sirni faqat expose_secret() ochadi |
| Minimal allocation | String dan yaratishda qo'shimcha allocation yo'q (normalizatsiya in-place); &str dan β bitta |
| Opt-in integratsiyalar | serde, sqlx (Postgres/MySQL/SQLite), zeroize β faqat feature yoqilganda kompilyatsiya bo'ladi |
| Xavfsiz kod | #![deny(unsafe_code)], panic yo'llari yo'q (property-based testlar bilan qulflangan) |
O'rnatish va feature'lar
[]
= "0.18"
Yoki kerakli feature'lar bilan:
[]
= { = "0.18", = ["serde", "sqlx-postgres"] }
| Feature | Default | Nima yoqadi | Qo'shimcha dependency |
|---|---|---|---|
date |
β | BirthDate, DateFormat, Pinfl::birth_date() |
chrono |
id |
β | Id<Tag>, NumId<Tag>, JobId, SessionId, RequestId |
uuid |
serde |
Serialize / Deserialize barcha tiplar uchun (sirlar β faqat Deserialize) |
serde |
|
sqlx |
Type / Encode / Decode β driver'ga bog'liq emas |
sqlx |
|
sqlx-postgres |
sqlx + PgHasArrayType (Vec<T>, = ANY($1)) |
sqlx/postgres |
|
zeroize |
Sir tiplari Drop da xotirani nolga to'ldiradi |
zeroize |
|
serialize-secrets |
Sir tiplari uchun Serialize (masalan, auth-servis token javobi) |
serde |
Qoida: tiplar default'da bor, integratsiyalar β siz tanlaysiz. Faqat Passport kerak bo'lgan servis chrono/uuid ni ham xohlamasa:
= { = "0.18", = false }
Tezkor boshlash
use *;
Asosiy g'oya: ikki qatlamli validatsiya
Har bir qoida ikki turdan biriga kiradi:
| Qatlam | Nima tekshiradi | O'zgaradimi? | Qayerda |
|---|---|---|---|
| Struktura | uzunlik, belgilar, prefiks, kalendar sanasi | Hech qachon | parse() |
| Registry / biznes | operator kodi ro'yxatda bormi, PINFL nazorat raqami to'g'rimi | Ha, vaqt-vaqti bilan | is_*() metodlar va parse_strict() |
Nega shunday? Agar operator kodlari ro'yxati parse() ichida bo'lsa, yangi kod ajratilganda yangi foydalanuvchilar rad etiladi, tuzatish uchun esa crate relizi va barcha servislarni deploy qilish kerak β DB yoki Kafka'dagi eski yozuvlar ham o'qilmay qoladi. Shuning uchun:
use *;
// Struktura o'tadi β 998 + 9 raqam. Bu qiymat DB'dan yoki event'dan kelgan bo'lishi mumkin.
let phone = parse.unwrap;
assert!;
// Registratsiya formasida qat'iylik kerak β parse_strict
assert_eq!;
Qisqa qoida: DB/Kafka/ichki chegara β parse(); foydalanuvchi kiritgan ma'lumot β parse_strict().
Tiplar
Passport
O'zbekiston pasporti yoki ID-kartasi seriyasi va raqami: 2 ta lotin harfi + 7 ta raqam.
use ;
let p = parse.unwrap;
assert_eq!; // trim, ichki bo'sh joy olib tashlandi, katta harf
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
Faqat format tekshiriladi β seriya amaldagi ro'yxatga kiradimi, bu tekshirilmaydi (ZZ0000000 ham qabul qilinadi).
Pinfl (JShShIR)
14 raqamli shaxsiy identifikatsiya raqami. Struktura rasmiy hujjatga asoslangan (Vazirlar Mahkamasining 2022-yil 12-apreldagi 177-son qarori):
| Raqamlar | Ma'nosi |
|---|---|
| 1 | jins va asr: 1,2 β 1800-yillar; 3,4 β 1900-yillar; 5,6 β 2000-yillar (toq β erkak, juft β ayol) |
| 2β7 | tug'ilgan sana DDMMYY |
| 8β10 | tug'ilgan hudud kodi |
| 11β13 | tartib raqami |
| 14 | nazorat raqami: birinchi 13 raqam 7,3,1,7,3,1,β¦ vaznlar bilan ko'paytirilib qo'shiladi, mod 10 |
use ;
// parse β faqat struktura (14 raqam). DB'dan o'qish, event'lar uchun.
let p = parse.unwrap;
assert!;
assert_eq!;
assert_eq!;
assert_eq!; // (yil, oy, kun)
assert_eq!;
assert_eq!;
// parse_strict β struktura + checksum + jins/asr belgisi + sana strukturasi
assert!;
assert_eq!;
assert_eq!;
// `date` feature bilan: haqiqiy kalendar sanasi sifatida
let birth_date = p.birth_date.unwrap;
assert_eq!;
PhoneNumber
O'zbekiston telefon raqami. Ichkarida har doim 998 + 9 raqam (+ siz, 12 raqam).
use ;
// Bo'sh joy, `-`, `(`, `)` va boshidagi `+` β hammasi tozalanadi
for input in
let phone = parse.unwrap;
assert_eq!;
assert_eq!;
assert_eq!;
assert!; // 71 β Toshkent shahar kodi
assert!; // hudud kodlari oralig'ida (60..=79)
assert_eq!;
assert_eq!;
assert_eq!;
Ma'lum kodlar PhoneNumber::MOBILE_CODES (slice) va PhoneNumber::REGIONAL_CODES (60..=79) konstantalarida. Ro'yxat eskirsa ham parse() ishlayveradi β faqat is_known_operator() / parse_strict() ta'sirlanadi.
EmailAddress
local-part@domain.tld, lowercase saqlanadi. Faqat ASCII manzillar.
use ;
let e = parse.unwrap;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!; // TLD yo'q
assert_eq!; // bo'sh label
assert!;
Tekshiriladigan qoidalar: local-part bo'sh emas va 64 belgidan uzun emas, . bilan boshlanmaydi/tugamaydi, .. yo'q, faqat RFC 5322 ruxsat bergan belgilar; domain kamida ikki label, har label [a-z0-9-], - bilan boshlanmaydi/tugamaydi, TLD kamida 2 ta harf; umumiy uzunlik β€ 254.
BirthDate (feature date)
Tug'ilgan sana: MIN_YEAR (1900) dan keyin va kelajakda emas (UTC bo'yicha ertangi kungacha yon beriladi β UTC+14 gacha bo'lgan mintaqalar uchun).
use ;
use NaiveDate;
let d = parse.unwrap; // YYYY-MM-DD
let same = parse_with_format.unwrap;
assert_eq!;
assert_eq!;
assert_eq!;
// Deterministik (testlanadigan) variantlar β "bugun" tashqaridan beriladi
let today = from_ymd_opt.unwrap;
assert_eq!;
assert_eq!;
assert_eq!;
age() va parse() tizim soatidan (UTC) foydalanadi; age_at(), parse_with_format_at(), from_naive_date_at() β deterministik. Kelajak tekshiruvi monoton: bir marta qabul qilingan sana keyinchalik hech qachon rad etilmaydi, shuning uchun saqlangan ma'lumotni qayta o'qish (replay) xavfsiz.
Id<Tag> va NumId<Tag> (feature id)
Tipli identifikatorlar. Tag β faqat compile-time belgisi: Id<Job> ni Id<Session> o'rniga berib bo'lmaydi.
use ;
// O'z tag'ingizni o'zingiz e'lon qilasiz β crate'ga PR kerak emas
pub type OrderId = ;
pub type LegacyOrderId = ; // eski tizimlardagi raqamli ID (BIGINT)
let a = now_v7; // vaqt bo'yicha tartiblangan β DB primary key uchun
let b = new_v4; // tasodifiy
assert_ne!;
assert_eq!;
assert_eq!;
let legacy = parse.unwrap;
assert_eq!;
assert_eq!;
assert_eq!; // raqam UUID emas
// Tayyor alias'lar: JobId, SessionId, RequestId
let job = now_v7;
assert!;
Id<Tag>β istalgan RFC 9562 UUID'ni qabul qiladi (hyphenated, simple, braced, urn). Versiya cheklovi kerak bo'lsaversion()bilan tekshiring.Id<Tag>JSON'da har doim string,NumId<Tag>β har doim integer. DB'da mos ravishdaUUIDvaBIGINT.- Ikkala tip ham
Copy,Eq,Ord,Hash,Send + SyncβTagqanday bo'lishidan qat'i nazar.
Sir tiplari: AccessToken, RefreshToken, ClientSecret
Sir tiplari tasodifan oshkor bo'lmasligi uchun tip darajasida cheklangan:
| Sir tiplari | ClientId (sir emas) |
|
|---|---|---|
Display ({}, .to_string()) |
β compile error | β |
Debug ({:?}) |
AccessToken([REDACTED]) |
β ochiq |
as_str(), AsRef<str>, into_inner() |
β | β |
| Qiymatga kirish | faqat expose_secret() |
as_str() |
== |
constant-time (subtle) |
oddiy |
| serde | Deserialize β
; Serialize faqat serialize-secrets feature'da |
ikkalasi β |
| sqlx | β (token DB'da saqlanmasligi kerak) | β |
zeroize feature |
Drop da xotira tozalanadi |
β |
use ;
let token = parse.unwrap;
assert_eq!; // logga tushmaydi
assert_eq!; // yagona ochiq yo'l
assert_eq!;
assert!;
let client_id = parse.unwrap;
assert_eq!; // ClientId β oddiy tip
MAX_TOKEN_LEN (8 KiB) β mantiqiy chegara, xotira DoS'idan himoya emas: String bu tekshiruvga kelguncha allaqachon ajratilgan bo'ladi. Body-limit HTTP qatlamida turishi kerak.
Xatolar bilan ishlash
Har bir parse() o'zining aniq error tipini qaytaradi. Umumiy TypeError β ? operatori orqali avtomatik yig'iladigan aggregate:
use ;
// Aniq tip β ikki holat uchun ikki qatorli match
match parse
// Application kodda `?` TypeError ga o'tadi
assert!;
Barcha error tiplari std::error::Error, Copy, Eq va #[non_exhaustive]; TypeError variantlari #[error(transparent)] β xabar ichki xatonikidir.
serde integratsiyasi
features = ["serde"]. Har tip JSON'da bitta shaklga ega:
| Tip | JSON |
|---|---|
Passport, Pinfl, PhoneNumber, EmailAddress, ClientId |
"AA1234567" (normalizatsiya qilingan string) |
BirthDate |
"1990-05-15" |
Id<Tag> |
"9b7e597e-893e-4e11-92cf-f4e7d4f923b1" (bincode/postcard'da 16 bayt) |
NumId<Tag> |
42 (faqat integer; "42" string qabul qilinmaydi) |
AccessToken va boshqa sirlar |
Deserialize β
; Serialize faqat serialize-secrets |
Deserializatsiya validatsiyadan o'tadi β noto'g'ri JSON Err beradi, #[derive(Deserialize)] kabi smart constructor chetlab o'tilmaydi:
#
serde dependency'si derive feature'siz ulanadi β proc-macro kompilyatsiyasi kerak emas.
sqlx integratsiyasi
features = ["sqlx-postgres"] (yoki faqat sqlx + o'zingizning driver'ingiz). Ustun tiplari:
| Tip | Postgres ustuni |
|---|---|
Passport, Pinfl, PhoneNumber, EmailAddress, ClientId |
TEXT / VARCHAR |
BirthDate |
DATE |
Id<Tag> |
UUID |
NumId<Tag> |
BIGINT |
Decode ham parse() orqali o'tadi: DB'dagi buzuq yozuv try_get da xato beradi, jimgina ichkariga kirmaydi.
use *;
// query_as! da maxsus tip uchun ustun override sintaksisi: `ustun AS "ustun: Tip"`
let row = query_as!
.fetch_one
.await?;
// bind β Encode
query
.bind
.bind
.execute
.await?;
// Vec<T> β PgHasArrayType (sqlx-postgres)
let passports: = vec!;
query.bind;
Migratsiya eslatmasi: eski tizimdan kelgan DB'da parse() strukturasiga mos kelmaydigan yozuvlar (masalan, 13 raqamli PINFL) bo'lsa, ular SELECT da xato beradi β migratsiyadan oldin ma'lumotni tozalang. parse_strict darajasi (checksum) talab qilinmaydi.
Cheklovlar
| Tip | Cheklov |
|---|---|
Passport |
Faqat format. Seriya amaldagi ro'yxatga kiradimi β tekshirilmaydi. |
Pinfl |
parse() faqat 14 raqam. Checksum, jins/asr va sana β parse_strict() yoki query metodlar. Haqiqiy shaxsga tegishliligini faqat davlat xizmati (my.gov.uz va h.k.) tasdiqlaydi. |
PhoneNumber |
9 raqamli mahalliy shakl (90 123 45 67) qabul qilinmaydi β 998 bilan yuboring. MOBILE_CODES ro'yxati crate ichida; eskirsa parse() ta'sirlanmaydi, is_known_operator() / parse_strict() ta'sirlanadi. |
EmailAddress |
Faqat ASCII. IDN (unicode domenlar), quoted local-part ("a b"@x.com) va IP-literal (a@[1.2.3.4]) qabul qilinmaydi. Local-part ham lowercase qilinadi. |
BirthDate |
parse()/age() tizim soatiga (UTC) tayanadi; testlarda *_at() variantlarini ishlating. |
NumId<Tag> |
DB'da BIGINT (i64): i64::MAX dan katta qiymat Encode da xato beradi. |
| Sir tiplari | zeroize β "best effort": String realloc/clone nusxalari va HTTP/serde buferlari tozalanmaydi. |
MSRV va semver
- MSRV: Rust 1.94 (edition 2024). MSRV ko'tarilishi minor reliz hisoblanadi.
- Barcha public enum'lar
#[non_exhaustive]βmatchda_tarmog'ini qoldiring. - Public konstantalar slice/
RangeInclusiveβ yangi kod qo'shilishi breaking emas. - Feature nomlari 1.0 gacha qulflangan:
date,id,serde,sqlx,sqlx-postgres,zeroize,serialize-secrets. - Har reliz
cargo semver-checksbilan tekshiriladi; breaking o'zgarishlar CHANGELOG da migratsiya jadvali bilan beriladi.
Rivojlantirish
Talab: just, cargo-hack, cargo-semver-checks.
Testlar: unit + integration (tests/api.rs, tests/serde.rs, tests/sqlx_bounds.rs) + property-based (tests/props.rs: hech qanday input panic qilmaydi, parse idempotent). Postgres integration testi DATABASE_URL bo'lsa ishlaydi (CI'da postgres:16 service).
Litsenziya
MIT yoki Apache-2.0 β o'zingizga qulayini tanlang.