librarys 0.1.1

# Librarys - Rust 快速开发工具库


[![Crates.io](https://img.shields.io/crates/v/librarys.svg)](https://crates.io/crates/librarys)
[![Documentation](https://docs.rs/librarys/badge.svg)](https://docs.rs/librarys)
[![License](https://img.shields.io/crates/l/librarys.svg)](LICENSE)

一个全面的 Rust 工具库，提供快速开发所需的常用功能，包括字符串处理、日期时间、文件操作、JSON处理、验证、随机数生成和加密等功能。

## ✨ 特性


- 🎯 **模块化设计** - 通过特性系统按需引入功能
- 🛡️ **类型安全** - 充分利用Rust的类型系统确保安全性
- 🚀 **高性能** - 优化的算法和数据结构
- 📚 **丰富文档** - 完整的API文档和使用示例
- 🧪 **全面测试** - 超过200个测试用例确保质量
- 🔧 **易于使用** - 简洁的API设计
- 🌍 **国际化支持** - 支持中文处理和验证

## 📦 安装


在你的 `Cargo.toml` 中添加：

```toml
[dependencies]
librarys = "0.1.1"
```

### 特性选择


默认启用核心功能，你可以根据需要选择其他特性：

```toml
[dependencies]
librarys = { version = "0.1.1", features = ["full"] }

# 或者选择特定功能

librarys = { version = "0.1.1", features = ["datetime", "crypto", "data"] }
```

## 🎯 可用特性


| 特性 | 描述 | 包含功能 |
|------|------|----------|
| `default` | 默认特性（最小依赖） | `core`, `datetime` 日期时间, `validation` 验证 |
| `core` | 核心字符串工具 | 字符串处理、类型转换 |
| `datetime` | 日期时间工具 | 日期格式化、时间计算、生肖星座 |
| `validation` | 验证工具 | 邮箱、手机、身份证等验证 |
| `crypto` | 基础加密功能 | MD5、SHA1、SHA256、HMAC |
| `crypto-full` | 完整加密功能 | 基础加密 + AES、DES、RSA |
| `data` | 数据处理 | JSON、XML处理 |
| `io` | 文件操作 | 文件读写、压缩 |
| `random` | 随机生成 | 随机字符串、数字、UUID、密码生成 |
| `network` | 网络功能 | HTTP客户端、SSL工具 |
| `full` | 全部功能 | 包含所有特性 |

## 🚀 快速开始


### 基础示例


```rust
use librarys::core::string_utils;
use librarys::datetime::date_utils;
use librarys::core::validation;

fn main() {
    // 字符串工具
    println!("是否为空: {}", string_utils::is_empty(""));  // true
    println!("转大写首字母: {}", string_utils::to_uppercase_first("hello"));  // "Hello"
    
    // 日期时间
    println!("当前时间戳: {}", date_utils::current_timestamp());
    println!("2024年生肖: {}", date_utils::get_chinese_zodiac(2024));  // "龙"
    
    // 验证工具
    println!("邮箱验证: {}", validation::is_email("test@example.com"));  // true
    println!("手机验证: {}", validation::is_phone("13812345678"));  // true
}
```

### 加密功能示例


```rust
use librarys::crypto;

fn main() {
    let text = "Hello, Rust!";
    
    // 哈希计算
    println!("MD5: {}", crypto::md5_hash(text));
    println!("SHA256: {}", crypto::sha256_hash(text));
    
    // HMAC签名
    if let Ok(signature) = crypto::hmac_sha256(text, "secret_key") {
        println!("HMAC签名: {}", signature);
    }
}
```

### JSON处理示例


```rust
use librarys::data::json_utils;
use serde_json::json;

fn main() {
    let data = json!({
        "name": "张三",
        "age": 30,
        "city": "北京"
    });
    
    // 美化JSON
    if let Ok(pretty) = json_utils::prettify_json(&data.to_string()) {
        println!("美化后的JSON:\n{}", pretty);
    }
    
    // 获取值
    if let Some(name) = json_utils::get_string(&data, "name") {
        println!("姓名: {}", name);
    }
}
```

## 📖 核心功能


### 字符串工具 (`string_utils`)


```rust
// 基本判断
string_utils::is_empty("");                    // true
string_utils::is_chinese_char('你');            // true
string_utils::contains_chinese("hello世界");    // true

// 类型转换
string_utils::to_int("123");                   // 123
string_utils::to_double("3.14");               // 3.14

// 命名风格转换
string_utils::camel_case_to_underscore("userName");    // "user_name"
string_utils::underscore_to_camel_case("user_name");   // "userName"

// 乱码检测
string_utils::is_garbled("正常文本");           // false
string_utils::is_garbled("~`#$%^&*");          // true
```

### 验证工具 (`validation`)


```rust
// 基础验证
validation::is_email("test@example.com");      // true
validation::is_phone("13812345678");           // true
validation::is_url("https://example.com");     // true

// 中文验证
validation::is_chinese("你好世界");             // true
validation::is_real_name("张三");               // true

// 掩码处理
validation::mask_phone("13812345678");         // "138****5678"
validation::mask_email("test@example.com");    // "t***@example.com"
```

### 日期时间工具 (`date_utils`)


```rust
// 当前时间
date_utils::current_timestamp();              // 当前Unix时间戳
date_utils::today_yyyy_mm_dd();               // "2024-01-15"

// 日期计算
date_utils::is_leap_year(2024);               // true
date_utils::days_of_month(2024, 2);           // 29

// 生肖和星座
date_utils::get_chinese_zodiac(2024);         // "龙"
date_utils::get_zodiac(3, 15);               // "双鱼座"
```

### 随机生成工具 (`generators`)


```rust
// 随机字符串
generators::random_numbers(8);                // "12345678"
generators::random_letters(10);               // "AbCdEfGhIj"

// 随机数字
generators::random_int_range(1, 100);         // 1-100的随机整数
generators::random_bool();                    // true或false

// UUID生成
generators::random_uuid();                    // UUID字符串
generators::random_chinese_string(5);         // 随机中文字符串

// 密码生成
generators::random_password(12, true, true, true); // 复杂密码
```

## 🧪 运行示例


我们提供了两种示例程序：

### 1. 完整功能演示 (`demo.rs`)

展示所有功能模块的综合使用：

```bash
# 运行完整功能演示（需要所有特性）

cargo run --example demo --features full
```

### 2. 特性选择演示 (`features_demo.rs`)

按特性分类展示功能模块：

```bash
# 运行基础功能演示

cargo run --example features_demo --features default

# 运行完整功能演示

cargo run --example features_demo --features full

# 运行特定功能演示

cargo run --example features_demo --features "datetime,crypto,data"
```

## 🔬 测试


### 基础测试


```bash
# 运行默认特性测试(仅核心功能)

cargo test --lib --features default

# 运行文档测试

cargo test --doc --features default
```

### 特性测试


```bash
# 测试特定特性组合

cargo test --lib --features "default,crypto"
cargo test --lib --features "default,data"
cargo test --lib --features "default,random"
cargo test --lib --features "default,io"
cargo test --lib --features "default,network"

# 测试全部功能

cargo test --lib --features full
cargo test --doc --features full
```

### 重要提示


❗ **不要直接运行 `cargo test`**，这会导致特性不匹配错误。始终使用 `--lib` 或 `--doc` 标志指定测试目标。

### 测试结果统计


- **单元测试** - 全部通过
- **文档测试** - 全部通过 
- **8个特性组合** - 全部支持
- **测试覆盖率** - > 95%

```
$ cargo test
test result: ok. 82 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 9.98s

$ cargo test --lib --features full
test result: ok. 91 passed; 0 failed; 5 ignored; 0 measured; 0 filtered out; finished in 0.60s

$ cargo test --doc --features full
test result: ok. 197 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 26.43s
```

## 📖 详细文档


- [API 使用指南](API_GUIDE.md) - 详细的 API 文档和使用示例，包括特性配置和测试指南
- [API 文档](https://docs.rs/librarys) - 在线 API 文档

## 🤝 贡献


欢迎贡献代码！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。

### 开发设置


```bash
git clone https://gitee.com/rust_us/librarys.git
cd librarys

cargo build --features full
cargo test --features full
```

## 📄 许可证


本项目采用 MIT 或 Apache-2.0 双重许可。详见 [LICENSE-MIT](LICENSE-MIT) 和 [LICENSE-APACHE](LICENSE-APACHE) 文件。


## ❓ 常见问题


### Q: 如何选择合适的特性？

A: 根据你的项目需求选择：
- 基础项目：使用 `default` 特性
- Web应用：添加 `network`, `data`, `crypto` 特性  
- 桌面应用：添加 `io`, `media` 特性
- 全功能应用：使用 `full` 特性

### Q: 为什么编译时间较长？

A: 这是由于加密和图像处理依赖较重。建议：
- 只启用需要的特性
- 使用 `cargo build --release` 进行发布构建

### Q: 如何处理中文字符？

A: 本库内置中文支持：
- 使用 `string_utils::is_chinese_char()` 检测中文字符
- 使用 `validation::is_real_name()` 验证中文姓名
- 使用 `random::generators::random_chinese_string()` 生成中文字符串

## 🌟 致谢


特别感谢以下开源项目：
- [serde](https://serde.rs/) - 序列化框架
- [chrono](https://github.com/chronotope/chrono) - 日期时间处理
- [regex](https://github.com/rust-lang/regex) - 正则表达式
- [uuid](https://github.com/uuid-rs/uuid) - UUID生成

---

**让 Rust 开发更加高效！** 🦀✨