Clamber Core (Rust)

一个面向 Rust 项目的通用核心工具库，提供配置管理、JWT、分布式 ID（Snowflake）、结构化日志与错误处理等常用能力，开箱即用、类型安全、易扩展。

• 配置管理：多格式文件 + 环境变量覆盖 + 多文件合并（详见 CONFIG.md）
• JWT：简洁易用的 Token 生成与校验，支持自定义配置（详见 JWT_README.md）
• Snowflake：线程安全的分布式唯一 ID 生成（详见 SNOWFLAKE.md）
• 日志与追踪：tracing 生态，支持文件/控制台、按日滚动、环境过滤
• 错误处理：基于 thiserror 的统一错误类型 ClamberError（详见 ERROR_HANDLING_UPGRADE.md）

安装

在你的 Cargo.toml 中添加依赖：

[dependencies]
clamber-core = "0.1.3"
serde = { version = "1.0", features = ["derive"] }

最低 Rust 版本：与本库 edition 2024 兼容的稳定版 Rust（建议使用最新 stable）。

快速开始

下面展示各核心模块的最小可用示例。更多进阶用法请查看对应的模块文档。

1) 配置管理

• 从单个文件加载并支持环境变量覆盖：

use clamber_core::{load_config_with_env};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct AppConfig { name: String, port: u16, debug: bool }

fn main() -> clamber_core::Result<()> {
    // 自动解析 YAML/TOML/JSON，支持环境变量前缀 APP_
    let config: AppConfig = load_config_with_env("config.yaml", "APP")?;
    println!("{:?}", config);
    Ok(())
}

• 构建器加载多个文件并设置默认值：

use clamber_core::ConfigBuilder;

let config: AppConfig = ConfigBuilder::new()
    .add_yaml_file("base.yaml")
    .add_yaml_file("production.yaml")
    .with_default("port", 8080)?
    .with_env_prefix("APP")
    .with_env_separator("__")
    .ignore_missing_files(true)
    .build()?;

更多内容请见 CONFIG.md（格式、环境变量命名规则、自动发现等）。

2) JWT

• 便利函数：

use clamber_core::token::{generate_token, verify_token, is_valid_token, JwtConfig};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct User { id: String, username: String, role: String }

fn main() -> clamber_core::Result<()> {
    let user = User { id: "1".into(), username: "alice".into(), role: "admin".into() };
    let token = generate_token(&user, JwtConfig::default())?;
    assert!(is_valid_token(&token));
    let decoded: User = verify_token(&token)?;
    assert_eq!(user, decoded);
    Ok(())
}

• 自定义配置：

use clamber_core::token::{JwtConfig, JwtManager};
let manager = JwtManager::new(JwtConfig::new("my_secret", 30));

更多内容请见 JWT_README.md（配置说明、API、错误示例等），以及 examples/jwt_usage.rs。

3) Snowflake 分布式 ID

use clamber_core::snowflake_utils;

let id = snowflake_utils::generate_id()?;
let string_id = snowflake_utils::generate_string_id()?;
let info = snowflake_utils::parse_id(id)?;

更多内容请见 SNOWFLAKE.md（ID 结构、配置、纪元自定义等），以及 examples/snowflake_example.rs。

4) 日志与追踪（tracing）

库内提供基于 tracing 的日志初始化与文件滚动方案，支持：

• 控制台与文件输出
• 按天滚动与压缩
• 环境变量过滤（RUST_LOG）

典型做法：

// 伪代码示例，实际 API 以 src/tracing_logs 为准
let (_guard_stdout, _guard_file) = clamber_core::tracing_logs::logger_start("logs")?;
tracing::info!("service started");

5) 统一错误处理

• 公开类型：
  • Result = std::result::Result<T, ClamberError>
  • ClamberError：覆盖 JWT、IO、配置、日志等常见错误

示例与迁移说明见 ERROR_HANDLING_UPGRADE.md。

运行示例

项目内包含多份可运行示例，使用 Cargo 运行：

# JWT 示例
cargo run --example jwt_usage

# 错误处理示例
cargo run --example error_handling

# 自定义日志示例
cargo run --example beautiful_logs_custom

# Snowflake 示例
cargo run --example snowflake_example

在 Windows PowerShell 下亦可同样执行以上命令。

目录结构（节选）

• src/config 配置模块实现
• src/token JWT 模块实现
• src/snowflake 雪花算法模块实现
• src/tracing_logs 日志与追踪初始化
• examples 示例程序
• CONFIG.md、JWT_README.md、SNOWFLAKE.md、ERROR_HANDLING_UPGRADE.md 详细文档

版本与许可证

• crate: clamber-core = 0.1.3
• 许可证：MIT OR Apache-2.0
• 仓库：https://github.com/Clamber-L/clamber-core-rust

如有问题或建议，欢迎提交 Issue/PR。