Skip to main content

Crate trait_kit

Crate trait_kit 

Source
Expand description

trait-kit — 模块标准接口与能力管理中心

提供模块定义标准接口和 Kit 能力管理中心的轻量实现。

CI crates.io docs.rs downloads MIT licensed Rust 1.85+

English | 简体中文

§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 = KitError;
    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 异步能力管理，无需额外依赖。
confersdep:confers, dep:serdeConfigurable trait + Kit::load_config。
confers-macrosconfersModuleConfig trait + Config derive 宏再导出。
hot-reloadconfers-macros, confers/watchsubscribe / reload_config 热重载 API。
encryptionhot-reload, confers/encryption, dep:serde_jsonset_encrypted / get_encrypted 加密配置存储。
i18ndep:icu, dep:writeableICU4X 国际化：区域感知的数字/日期/复数/排序。

在 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    # KitError 错误类型
├── 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。

§📄 许可证

MIT License, Copyright (c) 2026 Kirky.X

详见 LICENSE。

Modules§

core
Core traits and types for module declaration.
kit
Kit — the capability and configuration management center.
prelude
Re-exports of the most commonly used types and traits.