confers 0.4.0 - Docs.rs

🎯 零样板配置管理

Confers 提供声明式方法进行配置管理：

✨ 类型安全	🔄 自动重载	🔐 XChaCha20-Poly1305 加密	🌐 远程配置源
编译时检查	热重载支持	敏感数据保护	etcd、Consul、HTTP

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

// 配置自动从文件、环境变量和命令行参数加载
let config = AppConfig::load_sync()?;

📋 目录

✨ 功能特性
🚀 快速开始
- 📦 安装
- 💡 基本用法
📚 文档
💻 示例
🏗️ 架构设计
⚙️ 配置选项
🧪 测试
📊 性能
🔒 安全
🗺️ 开发路线图
🤝 参与贡献
📄 许可证
🙏 致谢

✨ 功能特性

🎯 核心功能	⚡ 可选功能
始终可用	按需启用

🎯 核心功能（始终可用）

状态	功能	描述
✅	类型安全配置	通过派生宏自动生成配置结构体（`derive` 功能）
✅	多格式支持	支持 TOML、YAML、JSON、INI 配置文件
✅	环境变量覆盖	支持环境变量覆盖配置
✅	命令行参数覆盖	支持命令行参数覆盖（`cli` 功能）

⚡ 可选功能

状态	功能	描述
🔍	配置验证	内置验证器集成（`validation` 功能）
📊	Schema 生成	自动生成 JSON Schema（`schema` 功能）
🚀	文件监控与热重载	实时文件监控（`watch` 功能）
🔐	配置加密	XChaCha20-Poly1305 加密存储（`encryption` 功能）
🌐	远程配置	支持 etcd、Consul、HTTP（`remote` 功能）
📦	审计日志	记录访问和变更历史（`audit` 功能）
🔧	配置对比	多种输出格式的配置比较
🛡️	安全增强	Nonce 重用检测、SSRF 防护
🔑	密钥管理	内置密钥生成和轮换

📦 功能预设

预设	包含功能	使用场景
minimal	`env`, `json`	最小化配置加载（无验证、无 CLI）
recommended	`toml`, `json`, `env`, `validation`	推荐大多数应用程序使用
dev	`toml`, `json`, `yaml`, `env`, `cli`, `validation`, `schema`, `audit`, `watch`, `migration`, `snapshot`, `dynamic`	开发环境，包含所有工具
production	`toml`, `env`, `watch`, `encryption`, `validation`, `audit`, `schema`, `cli`, `migration`, `dynamic`, `progressive-reload`, `snapshot`	生产环境配置
distributed	`toml`, `env`, `watch`, `validation`, `config-bus`, `progressive-reload`, `audit`	分布式系统
full	所有功能	完整功能集

🎨 功能架构

graph LR
    A["<b>配置源</b><br/>文件 • 环境变量 • CLI"] --> B["<b>ConfigLoader</b><br/>核心引擎"]
    B --> C["<b>验证</b><br/>类型和业务规则"]
    B --> D["<b>Schema</b><br/>JSON Schema 生成"]
    B --> E["<b>加密</b><br/>XChaCha20-Poly1305"]
    B --> F["<b>审计</b><br/>访问日志"]
    C --> H["<b>应用配置</b><br/>可直接使用"]
    D --> H
    E --> H
    F --> H

    style A fill:#DBEAFE,stroke:#1E40AF,stroke-width:2px
    style B fill:#FEF3C7,stroke:#92400E,stroke-width:2px
    style H fill:#DCFCE7,stroke:#166534,stroke-width:2px

🚀 快速开始

📦 安装

🦀 Rust 安装

安装方式	配置方式	使用场景
默认	`confers = "0.4.0"`	包含 `toml`、`json`、`env`（默认特性）
最小化	`confers = { version = "0.4.0", default-features = false, features = ["minimal"] }`	环境变量 + JSON
推荐	`confers = { version = "0.4.0", default-features = false, features = ["recommended"] }`	TOML + JSON + Env + 验证
CLI 工具	`confers = { version = "0.4.0", features = ["cli"] }`	CLI 工具（不含验证/加密）
完整	`confers = { version = "0.4.0", features = ["full"] }`	所有功能

单独功能说明：

功能	描述	默认启用
格式支持
`toml`	TOML 格式支持	✅
`json`	JSON 格式支持	✅
`yaml`	YAML 格式支持	❌
`ini`	INI 格式支持	❌
`env`	环境变量支持	✅
`dotenv`	`.env` 文件支持（`env` 的别名）	❌
核心功能
`validation`	配置验证（garde）	❌
`watch`	文件监控和热重载	❌
`encryption`	XChaCha20-Poly1305 加密	❌
`cli`	命令行工具	❌
`schema`	JSON Schema 生成	❌
`typescript-schema`	TypeScript 类型生成（`schema` 的别名）	❌
高级功能
`audit`	审计日志	❌
`dynamic`	动态字段	❌
`progressive-reload`	渐进式重载	❌
`migration`	配置迁移	❌
`snapshot`	快照回滚	❌
`interpolation`	变量插值	❌
远程源
`remote`	HTTP 轮询	❌
`etcd`	Etcd 集成	❌
`consul`	Consul 集成	❌
消息总线
`config-bus`	配置事件总线	❌
`nats-bus`	NATS 消息总线	❌
`redis-bus`	Redis 消息总线	❌
其他
`security`	安全模块	❌
`key`	密钥管理系统	❌
`modules`	模块化配置	❌
`context-aware`	上下文感知配置	❌

🔧 CLI 命令功能依赖

命令	必需功能	可选功能	描述
`inspect`	`cli`	-	查看配置键及来源
`validate`	`cli`	-	验证配置文件
`diff`	`cli`	-	比较配置文件
`export`	`cli`	-	导出合并后的配置
`snapshot`	`cli`	`snapshot`	管理配置快照

注意：cli 功能提供用于配置管理的命令行工具。

💡 基本用法

🎬 5 分钟快速入门

必需功能：toml、env、validation（使用：features = ["recommended"]）

第一步：定义配置结构体

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
#[config(env_prefix = "APP_")]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

第二步：创建配置文件

# config.toml
name = "my-app"
port = 8080
debug = true

第三步：加载配置

fn main() -> anyhow::Result<()> {
    let config = AppConfig::load_sync()?;
    println!("✅ 已加载: {:?}", config);
    Ok(())
}

第四步：环境变量覆盖

# 环境变量自动覆盖配置
export APP_PORT=9090
export APP_DEBUG=true

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
#[config(env_prefix = "APP_")]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

fn main() -> anyhow::Result<()> {
    // 创建配置文件
    let config_content = r#"
name = "my-app"
port = 8080
debug = true
"#;
    std::fs::write("config.toml", config_content)?;

    // 加载配置
    let config = AppConfig::load_sync()?;

    // 打印配置
    println!("🎉 配置加载成功！");
    println!("📋 名称: {}", config.name);
    println!("🔌 端口: {}", config.port);
    println!("🐛 调试模式: {}", config.debug);

    Ok(())
}

🎨 三种使用模式

Confers 提供三种灵活的使用模式以满足不同需求：

1️⃣ 简单模式（推荐）

适用于大多数应用程序，代码简洁：

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
    pub debug: bool,
}

// 一行代码加载配置
let config = AppConfig::load_sync()?;

2️⃣ 构建器模式

更好地控制配置来源：

use confers::{ConfigBuilder, ConfigProviderExt};

let config = ConfigBuilder::<serde_json::Value>::new()
    .file("config.toml")
    .file("local.toml")  // 更高优先级
    .env()
    .build()?;

let name = config.get_string("app.name");
let port = config.get_int("app.port");

3️⃣ 依赖注入模式

便于集成到框架中，支持运行时灵活性：

use std::sync::Arc;
use confers::{ConfigBuilder, ConfigProviderExt};

#[derive(Debug, Clone, serde::Deserialize)]
pub struct MyConfig {
    pub name: String,
    pub port: u16,
}

let config = ConfigBuilder::<MyConfig>::new()
    .file("config.toml")
    .env()
    .build()?;

let shared_config = Arc::new(config);

let service = MyService::new(shared_config);

📚 文档

📖 更多资源

资源	描述
❓ 常见问题	常见问题解答
📖 贡献指南	代码贡献指南
📘 API 参考	完整 API 文档
🏗️ 架构决策	ADR 文档
📚 库集成指南	如何将 confers CLI 集成到您的项目中

🔄 BrickArchitecture 迁移指南

Confers 遵循 BrickArchitecture 错误分离模式：

错误类型	阶段	出现时机	示例
`ConfigConfigError`	配置阶段	初始化时	缺失字段、解析错误、验证失败
`ConfersError`	运行时	使用时	超时、远程不可用、解密失败

向后兼容： 现有的 ConfigError 和 ConfigResult<T> 别名仍然可用。

// 旧：所有错误都用 ConfigError
use confers::ConfigError;

// 新：使用 BrickArchitecture 错误分离
use confers::{ConfigConfigError, ConfersError};

// 配置阶段 - 使用 ConfigConfigError
fn init_config() -> Result<impl confers::interface::ConfigConnector, ConfigConfigError> {
    use confers::impl_::memory::InMemoryConfig;
    let config = InMemoryConfig::new_validated(1000)?; // 返回 ConfigConfigError
    Ok(config)
}

// 运行时阶段 - 使用 ConfersError
async fn use_config(config: &impl ConfigReader) -> Result<(), ConfersError> {
    let value = config.get_string("key").await?;  // 返回 ConfersError
    Ok(())
}

💻 示例

🗂️ 示例目录

完整可运行的示例展示所有主要功能。所有示例可在 examples/ 目录中找到。

示例	文件	所需功能	描述
basic_usage	`examples/src/examples/basic_usage.rs`	`toml`, `env`	从 TOML 和环境变量加载基本配置
hot_reload	`examples/src/examples/hot_reload.rs`	`watch`	实时文件监控与自动重载
encryption	`examples/src/examples/encryption.rs`	`encryption`	使用 XChaCha20-Poly1305 加密敏感字段
key_rotation	`examples/src/examples/key_rotation.rs`	`key`	密钥生命周期管理与轮换
migration	`examples/src/examples/migration.rs`	`migration`	配置版本迁移
dynamic_fields	`examples/src/examples/dynamic_fields.rs`	`dynamic`	无锁动态字段更新与回调
config_groups	`examples/src/examples/config_groups.rs`	`modules`	模块化配置分组
progressive_reload	`examples/src/examples/progressive_reload.rs`	`progressive-reload`	金丝雀部署与基于健康检查的滚动发布
config_bus	`examples/src/examples/config_bus.rs`	`config-bus`	通过 NATS/Redis 多实例配置广播
snapshot	`examples/src/examples/snapshot.rs`	`snapshot`	配置快照与 diff、回滚
remote_consul	`examples/src/examples/remote_consul.rs`	`consul`	从 HashiCorp Consul 获取远程配置
remote_etcd	`examples/src/examples/remote_etcd.rs`	`etcd`	从 etcd v3 获取远程配置
validation	`examples/src/examples/validation.rs`	`validation`	使用 garde 进行配置验证
json_schema	`examples/src/examples/json_schema.rs`	`schema`	JSON Schema 和 TypeScript 类型生成
interpolation	`examples/src/examples/interpolation.rs`	`interpolation`	配置字符串插值，支持 ${VAR} 语法
audit	`examples/src/examples/audit.rs`	`audit`	审计日志，AuditWriter 和 AuditEvent
context_aware	`examples/src/examples/context_aware.rs`	`context-aware`	上下文感知配置，ContextAwareField
security	`examples/src/examples/security.rs`	`security`	安全功能：加密前缀检测、环境变量验证
modules_demo	`examples/src/examples/modules_demo.rs`	`modules`	模块注册表，按特性加载配置
cli_integration	`examples/src/examples/cli_integration.rs`	`cli`	CLI 工具集成与使用
full_stack	`examples/src/examples/full_stack.rs`	`full`	完整功能展示

# 从 examples 目录运行任意示例
cd examples && cargo run --bin basic_usage
cd examples && cargo run --bin encryption
cd examples && cargo run --bin full_stack

# 验证所有示例可编译
cd examples && ./verify_examples.sh

💡 实际示例

📝 示例 1：基本配置

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
pub struct BasicConfig {
    pub name: String,
    pub port: u16,
}

fn basic_example() -> anyhow::Result<()> {
    let config = BasicConfig::load_sync()?;
    println!("✅ 名称: {}, 端口: {}", config.name, config.port);
    Ok(())
}

✅ 名称: my-app, 端口: 8080

🔥 示例 2：高级配置

use confers::Config;
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Serialize, Deserialize, Config)]
#[config(validate)]
#[config(env_prefix = "MYAPP_")]
pub struct AdvancedConfig {
    #[config(description = "服务器端口号")]
    pub port: u16,
    #[config(default = "localhost")]
    pub host: String,
    #[config(sensitive = true)]
    pub api_key: String,
}

fn advanced_example() -> anyhow::Result<()> {
    let config = AdvancedConfig::load_sync()?;
    println!("🚀 服务器: {}:{}", config.host, config.port);
    Ok(())
}

🚀 服务器: localhost:8080

📂 查看所有示例 →

🏗️ 架构设计

🏗️ 系统架构

graph TB
    subgraph Sources ["配置源"]
        A["本地文件<br/>TOML, JSON, YAML, INI"]
        B["环境变量"]
        C["命令行参数"]
        D["远程配置源<br/>etcd, Consul, HTTP"]
    end

    subgraph Core ["核心引擎"]
        E["ConfigLoader<br/>多源合并"]
    end

    subgraph Processing ["处理层"]
        F["验证<br/>类型和业务规则"]
        G["Schema 生成"]
        H["加密<br/>XChaCha20-Poly1305"]
        I["审计日志"]
        J["文件监控"]
    end

    subgraph Output ["应用"]
        L["应用配置<br/>类型安全且已验证"]
    end

    Sources --> Core
    Core --> Processing
    Processing --> Output

    style Sources fill:#DBEAFE,stroke:#1E40AF
    style Core fill:#FEF3C7,stroke:#92400E
    style Processing fill:#EDE9FE,stroke:#5B21B6
    style Output fill:#DCFCE7,stroke:#166534

📐 组件状态

组件	描述	状态
ConfigLoader	支持多源的核心加载器	✅ 稳定
配置验证	内置验证器集成	✅ 稳定
Schema 生成	自动生成 JSON Schema	✅ 稳定
文件监控	实时监控并热重载	✅ 稳定
远程配置	etcd、Consul、HTTP 支持	🚧 测试版
审计日志	记录访问和变更历史	✅ 稳定
加密存储	XChaCha20-Poly1305 加密存储	✅ 稳定
配置对比	多种输出格式	✅ 稳定

⚙️ 配置选项

🎛️ 配置选项

基本配置

[project]
name = "my-app"
version = "1.0.0"

[server]
host = "localhost"
port = 8080

[features]
debug = true
logging = true

高级配置

[project]
name = "my-app"
version = "1.0.0"

[server]
host = "0.0.0.0"
port = 8080
workers = 4

[database]
url = "postgres://localhost/db"
pool_size = 10

[performance]
cache_size = 1000

选项	类型	默认值	描述
`name`	String	-	项目名称
`version`	String	"1.0.0"	版本号
`host`	String	"localhost"	服务器主机
`port`	u16	8080	服务器端口
`debug`	Boolean	false	启用调试模式
`workers`	usize	4	工作线程数
`cache_size`	usize	1000	缓存大小（MB）

🧪 测试

🎯 测试覆盖率

# 🧪 运行所有测试
cargo test --features full

# 📊 生成覆盖率报告
cargo llvm-cov --features full

# ⚡ 运行基准测试
cargo bench

# 🎯 运行特定测试
cargo test test_name

数据来源：cargo test --features full（截至 2026-07）。数字随代码演进增长，可重新运行命令验证。

类别	测试数量	说明
🧪 单元测试	1700+	跨所有 feature gate 的 lib 测试
🔗 集成测试	多套件	`tests/integration_*.rs` 按 feature 组织
📚 文档测试	32	rustdoc 示例
⚡ 性能测试	10 个 bench 文件	`benches/*.rs`（criterion）
📈 总计	1700+	运行 `cargo test --features full`

覆盖率目标：≥ 80%（CI 通过 cargo llvm-cov 强制执行）。

📊 性能

⚡ 基准测试结果

以下为参考预估值。实际性能取决于配置复杂度和硬件环境。建议运行 cargo bench 获取针对您场景的真实数据。

📊 吞吐量

操作	性能
配置加载	1,000,000 次/秒
验证	500,000 次/秒
Schema 生成	2,000,000 次/秒

⏱️ 延迟

百分位	延迟
P50	0.5ms
P95	1.2ms
P99	2.5ms

# 运行基准测试
cargo bench

# 示例输出：
test bench_config_load  ... bench: 1,000 ns/iter (+/- 50)
test bench_validate     ... bench: 2,000 ns/iter (+/- 100)
test bench_schema_gen   ... bench: 500 ns/iter (+/- 25)

🔒 安全

🛡️ 安全特性

🛡️ 安全措施

措施	描述	API 参考
✅ 内存保护	使用 zeroization 自动安全清理	`SecretString`、`zeroize` crate
✅ 侧信道保护	常量时间加密操作	XChaCha20-Poly1305 加密
✅ 输入验证	全面的输入清理	`Validate` trait、`garde` crate
✅ 审计日志	完整的操作追踪	`AuditConfig`、审计追踪
✅ SSRF 防护	内置的服务端请求伪造防护	`HttpPolledSource`、`is_ip_blocked()`
✅ 敏感数据检测	自动检测敏感字段	`#[config(sensitive = true)]` 派生宏
✅ 错误信息清理	从错误消息中移除敏感信息	`ErrorSanitizer`、`SecureLogger`
✅ Nonce 重用检测	防止加密 nonce 重用	内置于加密模块

🔐 安全 API

// 安全字符串处理
use confers::security::{SecureString, SensitivityLevel};
let secure_str = SecureString::new("sensitive_data", SensitivityLevel::High);

// 输入验证
use confers::security::ConfigValidator;
let validator = ConfigValidator::builder()
    .max_string_length(1024)
    .strict_mode()
    .build();
let data: std::collections::HashMap<String, String> = std::collections::HashMap::new();
let result = validator.validate(&data);

// 错误信息清理
use confers::security::ErrorSanitizer;
let sanitizer = ErrorSanitizer::default();
let safe_error = sanitizer.sanitize(&error_message);

// 审计日志
#[cfg(feature = "audit")]
use confers::audit::AuditConfig;
let audit = AuditConfig::new().enable_sensitive_field_tracking();

🚨 安全最佳实践

敏感数据使用 SecureString：自动清理内存
启用审计日志：追踪所有配置访问和变更
验证所有输入：使用内置验证器验证用户输入
使用加密：为敏感配置启用 encryption 功能
遵循最小权限原则：最小化敏感数据暴露

📧 报告安全问题

请将安全漏洞报告至：security@confers.dev

🗺️ 开发路线图

🎯 开发路线图

gantt
    title Confers 开发路线图
    dateFormat  YYYY-MM
    section 核心功能
    类型安全配置     :done, 2024-01, 2024-06
    多格式支持       :done, 2024-02, 2024-06
    环境变量覆盖     :done, 2024-03, 2024-06
    section 验证系统
    基础验证集成     :done, 2024-04, 2024-07
    section 高级功能
    Schema 生成      :active, 2024-06, 2024-09
    文件监控热重载   :done, 2024-07, 2024-09
    远程配置支持     :active, 2024-08, 2024-12
    审计日志         :done, 2024-08, 2024-10

✅ 已完成

核心功能

类型安全配置
多格式支持（TOML、YAML、JSON、INI）
环境变量覆盖
命令行参数覆盖

验证系统

配置验证系统（garde）

高级特性

Schema 生成（JSON Schema + TypeScript 类型）
文件监控与热重载
审计日志
加密存储支持（XChaCha20-Poly1305）
动态字段（无锁）
模块化配置（modules）
上下文感知配置（租户感知）
配置迁移
快照与回滚
变量插值
渐进式重载（金丝雀发布）

远程与总线

远程配置支持（etcd、Consul、HTTP）
HTTP 轮询
配置事件总线（NATS / Redis Pub-Sub）

安全

安全模块（环境变量验证、错误信息清理、SSRF 防护）
密钥管理与轮换
Nonce 重用检测

📋 计划中

性能优化

基准测试套件完善（criterion 基线）
大型配置的内存占用优化
高频读取的零拷贝热路径

云原生集成增强

Kubernetes ConfigMap 集成
服务网格支持（Istio/Linkerd）
分布式追踪集成

🤝 参与贡献

💖 感谢所有贡献者！

🐛 报告 Bug

发现问题？创建 Issue

💡 功能建议

有好想法？开始讨论

🔧 提交 PR

想贡献代码？ Fork 并提交 PR

🚀 如何贡献

Fork 本仓库
Clone 你的 fork：git clone https://github.com/yourusername/confers.git
创建分支：git checkout -b feature/amazing-feature
进行修改
测试修改：cargo test --all-features
提交修改：git commit -m 'feat: 添加某功能'
推送到分支：git push origin feature/amazing-feature
创建 Pull Request

📋 代码规范

✅ 遵循 Rust 标准编码规范
✅ 编写全面的测试
✅ 更新文档
✅ 为新功能添加示例
✅ 通过 cargo clippy -- -D warnings

📄 许可证

本项目采用 MIT 许可证：

🙏 致谢

🌟 基于优秀工具构建

💝 特别感谢

类别	描述
🌟 依赖项目	serde - 序列化框架
	figment - 配置管理
	validator - 验证库
👥 贡献者	感谢所有贡献者！
💬 社区	特别感谢社区成员

📞 联系与支持

⭐ Star 历史

💝 支持本项目

如果您觉得这个项目有用，请考虑给它一个 ⭐️！

由 Kirky.X 用 ❤️ 构建

⬆ 返回顶部