trait-kit

trait-kit 是一个轻量级 Rust 库，提供标准化的模块接口和集中式能力与配置管理中心（Kit）。采用 typestate 模式（Kit<Unbuilt> → Kit<Ready>）进行构建时验证，基于 RefCell 的内部可变性实现单线程设计（!Sync）。

✨ 核心特性

标准化模块接口 — ModuleMeta + AutoBuilder trait 定义统一契约：每个模块声明其名称、依赖、能力类型和构建逻辑，确保初始化方式一致。
Typestate 构建验证 — Kit<Unbuilt> 注册模块和配置；kit.build() 验证依赖图（环检测、缺失依赖检测）并返回 Kit<Ready>，构建错误在应用启动前暴露。
类型安全的能力检索 — 能力按模块类型存储和检索（kit.require::<LoggerModule>()），而非字符串键。无需 downcast，无需运行时查找。
配置中心 — kit.set_config(value) / kit.config::<C>() 通过 TypeMap（以 TypeId 为键）存储和检索类型化配置，无需 ConfigKey 或 ConfigHandle 样板代码。
可选 confers 集成 — 四级 feature flag 集成 confers，支持 derive 宏配置加载、热重载订阅和 XChaCha20-Poly1305 加密配置存储。
AsyncKit 异步支持 — async feature 提供 AsyncKit，支持 Send + Sync 的异步能力管理，适用于数据库连接池、HTTP 客户端等异步初始化场景。
ICU4X 国际化 — i18n feature 集成 ICU4X，提供区域感知的数字、日期、复数和排序能力。
最小依赖 — 仅 thiserror 为必需依赖。confers、serde、serde_json、icu 均为可选，仅在启用对应 feature 时引入。
#![deny(unsafe_code)] — 整个 crate 无任何 unsafe 代码。

📦 快速开始

安装

cargo add trait-kit

基础使用

定义一个 logger 模块，注册、构建 Kit，然后检索能力：

use std::sync::Arc;
use trait_kit::prelude::*;

// 1. 定义能力（任意 Clone 类型）
struct StdoutLogger;
impl StdoutLogger {
    fn info(&self, msg: &str) {
        println!("[LOG] {msg}");
    }
}

// 2. 定义模块（实现 ModuleMeta + AutoBuilder）
struct LoggerModule;
impl ModuleMeta for LoggerModule {
    const NAME: &'static str = "logger";
    fn dependencies() -> &'static [(&'static str, std::any::TypeId)] {
        &[]
    }
}
impl AutoBuilder for LoggerModule {
    type Capability = Arc<StdoutLogger>;
    type Error = TraitKitError;
    fn build(_kit: &Kit) -> Result<Self::Capability, Self::Error> {
        Ok(Arc::new(StdoutLogger))
    }
}

// 3. 注册、构建、使用
fn main() {
    let mut kit = Kit::new();
    kit.register::<LoggerModule>().unwrap();
    let kit = kit.build().unwrap();

    let logger = kit.require::<LoggerModule>().unwrap();
    logger.info("Hello from trait-kit!");
    assert!(kit.contains::<LoggerModule>());
}

🔧 特性标志

Feature	启用	说明
`default`	—	无额外特性，仅核心 `Module` + `Kit`。
`async`	—	`AsyncKit`：`Send + Sync` 异步能力管理，无需额外依赖。
`confers`	`dep:confers`, `dep:serde`	`Configurable` trait + `Kit::load_config`。
`confers-macros`	`confers`	`ModuleConfig` trait + `Config` derive 宏再导出。
`hot-reload`	`confers-macros`, `confers/watch`	`subscribe` / `reload_config` 热重载 API。
`encryption`	`hot-reload`, `confers/encryption`, `dep:serde_json`	`set_encrypted` / `get_encrypted` 加密配置存储。
`i18n`	`dep:icu`, `dep:writeable`	ICU4X 国际化：区域感知的数字/日期/复数/排序。

在 Cargo.toml 中启用所需级别：

[dependencies]
trait-kit = { version = "0.2", features = ["encryption"] }

🏗️ 架构

src/
├── lib.rs          # crate 入口，#![deny(unsafe_code)]
├── prelude.rs      # 常用类型再导出
├── core/
│   ├── mod.rs      # 模块声明
│   ├── meta.rs     # ModuleMeta + AutoBuilder + AsyncAutoBuilder trait
│   └── error.rs    # TraitKitError 错误类型
├── kit/
│   ├── mod.rs      # Kit 模块声明
│   ├── kit.rs      # Kit<Unbuilt> → Kit<Ready> typestate 实现
│   ├── graph.rs    # 依赖图：环检测 + 拓扑排序
│   ├── typemap.rs  # TypeMap：以 TypeId 为键的能力存储
│   ├── async_kit.rs    # AsyncKit（async feature）
│   ├── async_typemap.rs # AsyncTypeMap（async feature）
│   └── config.rs   # confers 集成（confers feature）
└── i18n/
    └── mod.rs      # ICU4X 国际化（i18n feature）

核心设计：

Typestate 模式：Kit<Unbuilt> → Kit<Ready>，构建时验证依赖图，运行时零开销。
内部可变性：基于 RefCell，单线程 !Sync 设计，避免锁开销。
三级继承体系（confers 集成）：模块能力继承 → Cargo feature 继承 → 配置值继承（HKDF 密钥派生）。

📚 文档

🤝 贡献

详见 CONTRIBUTING.md。

📋 更新日志

详见 CHANGELOG.md。

📄 许可证

详见 LICENSE。

trait-kit 0.3.0