# 配置管理模块 (Config)
这个模块提供了统一的配置管理功能，支持多种配置文件格式和环境变量覆盖。
## 特性
- 🗂️ **多格式支持**: 支持 YAML、TOML、JSON 配置文件
- 🌍 **环境变量覆盖**: 支持通过环境变量覆盖配置值
- 🔄 **多文件合并**: 支持加载和合并多个配置文件
- 🎯 **自动发现**: 自动发现应用配置文件
- ⚙️ **默认值支持**: 支持设置配置默认值
- 🔧 **灵活构建**: 提供灵活的配置构建器模式
- 📁 **忽略缺失**: 可选择忽略缺失的配置文件
- 🛡️ **类型安全**: 基于 Serde 的强类型配置反序列化
## 基本使用
### 1. 定义配置结构
```rust
use serde::{Deserialize, Serialize};
#[derive(Debug, Serialize, Deserialize)]
struct AppConfig {
name: String,
port: u16,
debug: bool,
database: DatabaseConfig,
}
#[derive(Debug, Serialize, Deserialize)]
struct DatabaseConfig {
host: String,
port: u16,
username: String,
password: String,
}
```
### 2. 从单个配置文件加载
```rust
use clamber_core::load_config;
// 从 YAML 文件加载
let config: AppConfig = load_config(\"config.yaml\")?;
// 从 TOML 文件加载
let config: AppConfig = load_config(\"config.toml\")?;
// 从 JSON 文件加载
let config: AppConfig = load_config(\"config.json\")?;
```
### 3. 支持环境变量覆盖
```rust
use clamber_core::load_config_with_env;
// 加载配置文件并支持 APP_ 前缀的环境变量覆盖
let config: AppConfig = load_config_with_env(\"config.yaml\", \"APP\")?;
// 环境变量示例:
// APP_PORT=8080
// APP_DEBUG=true
// APP_DATABASE__HOST=localhost
// APP_DATABASE__PORT=5432
```
### 4. 使用配置构建器
```rust
use clamber_core::ConfigBuilder;
let config: AppConfig = ConfigBuilder::new()
// 添加多个配置文件（按优先级顺序）
.add_yaml_file(\"base.yaml\")
.add_yaml_file(\"production.yaml\")
// 设置默认值
.with_default(\"name\", \"my-app\")?
.with_default(\"port\", 8080)?
// 启用环境变量覆盖
.with_env_prefix(\"APP\")
.with_env_separator(\"__\")
// 忽略缺失的配置文件
.ignore_missing_files(true)
.build()?;
```
### 5. 自动发现配置
```rust
use clamber_core::auto_load_config;
// 自动查找 myapp.{yaml,yml,toml,json} 配置文件
let config: AppConfig = auto_load_config(\"myapp\", Some(\"APP\"))?;
```
## 配置文件格式
### YAML 格式 (`config.yaml`)
```yaml
name: \"my-application\"
port: 8080
debug: false
database:
host: \"localhost\"
port: 5432
username: \"postgres\"
password: \"password\"
```
### TOML 格式 (`config.toml`)
```toml
name = \"my-application\"
port = 8080
debug = false
[database]
host = \"localhost\"
port = 5432
username = \"postgres\"
password = \"password\"
```
### JSON 格式 (`config.json`)
```json
{
\"name\": \"my-application\",
\"port\": 8080,
\"debug\": false,
\"database\": {
\"host\": \"localhost\",
\"port\": 5432,
\"username\": \"postgres\",
\"password\": \"password\"
}
}
```
## 环境变量规则
环境变量遵循以下命名规则：
- 前缀：通过 `with_env_prefix()` 设置（如 `APP`）
- 分隔符：通过 `with_env_separator()` 设置（默认 `__`）
- 嵌套：使用分隔符表示嵌套结构
例如，对于配置：
```yaml
port: 8080
database:
host: \"localhost\"
port: 5432
```
对应的环境变量为：
```bash
APP_PORT=9000
APP_DATABASE__HOST=db.example.com
APP_DATABASE__PORT=3306
```
## 配置优先级
配置值的优先级从高到低：
1. 🌍 **环境变量** - 最高优先级
2. 📄 **后加载的配置文件** - 覆盖先加载的文件
3. 📄 **先加载的配置文件**
4. ⚙️ **默认值** - 最低优先级
## 错误处理
配置模块使用统一的错误类型：
- `ConfigLoadError` - 配置加载错误
- `ConfigFileNotFoundError` - 配置文件不存在
- `ConfigParseError` - 配置解析错误
- `ConfigValidationError` - 配置验证错误
- `EnvVarParseError` - 环境变量解析错误
## 高级用法
### 配置验证
```rust
#[derive(Debug, Serialize, Deserialize)]
struct AppConfig {
#[serde(deserialize_with = \"validate_port\")]
port: u16,
// 其他字段...
}
fn validate_port<'de, D>(deserializer: D) -> Result<u16, D::Error>
where
D: serde::Deserializer<'de>,
{
let port: u16 = u16::deserialize(deserializer)?;
if port < 1024 {
return Err(serde::de::Error::custom(\"端口号必须大于等于1024\"));
}
Ok(port)
}
```
### 可选配置项
```rust
#[derive(Debug, Serialize, Deserialize)]
struct AppConfig {
name: String,
port: u16,
// 可选的 Redis 配置
redis: Option<RedisConfig>,
// 带默认值的配置
#[serde(default = \"default_timeout\")]
timeout: u64,
}
fn default_timeout() -> u64 {
30
}
```
### 自定义配置路径
```rust
use clamber_core::get_config_paths;
// 获取应用 \"myapp\" 的所有可能配置路径
let paths = get_config_paths(\"myapp\");
for path in paths {
println!(\"检查配置文件: {:?}\", path);
}
```
## 示例
查看 `examples/config_example.rs` 了解完整的使用示例，包括：
- 基础配置加载
- 环境变量覆盖
- 多文件合并
- 自动发现
- 不同格式支持
运行示例：
```bash
cargo run --example config_example
```