Rust Miko 框架系列（十）：配置管理Miko 框架系列（十）：配置管理将配置与代码分离是现代应用开发的十二要素

Miko 框架系列（十）：配置管理

注意：此文章主要为了给支持联网搜索的AI提供RAG，此项目还在开发阶段，不建议用于生产。

配置是将代码与环境分离的关键。Miko 在 v0.8 中引入了全新的配置系统，基于强大的 config crate，提供了多格式支持、环境变量注入以及灵活的默认值机制。

1. 配置文件与格式

Miko 默认支持 TOML 格式，但你可以通过开启 feature 来支持 YAML、JSON 或 JSON5。

基础文件结构

在项目根目录下，Miko 会按顺序查找并加载以下文件（以 TOML 为例）：

config.toml (基础配置)
config.{env}.toml (环境特定配置，覆盖基础配置)

环境 {env} 默认为：

dev: 当在 Debug 模式下构建 (cargo run)
prod: 当在 Release 模式下构建 (cargo run --release)
或者通过环境变量 CONFIG_ENV 显式指定。

示例配置

config.toml:

# [server] 是核心配置段 (v0.8 变更: 以前是 [application])
[server]
host = "0.0.0.0"
port = 8080

[database]
url = "postgres://localhost/dev"

[app]
title = "My Miko App"

config.prod.toml:

[server]
port = 3000 # 生产环境覆盖端口

[database]
url = "postgres://prod-db/prod"

2. 环境变量注入

Miko 支持遵循 12-factor app 原则，通过环境变量覆盖配置。

规则是：以 MIKO__ 开头，使用双下划线 __ 分隔层级。

server.port -> MIKO__SERVER__PORT=9090
database.url -> MIKO__DATABASE__URL=...

3. 在代码中使用配置

自动加载

当你使用 #[miko] 宏时，配置系统会自动初始化，无需手动代码。

#[miko]
async fn main() {
    // 自动加载配置并启动 server
}

使用 `#[config]` 宏注入

这是获取配置最简单的方式。你可以将配置值直接注入到 handler 的参数中。

#[get("/")]
async fn index(
    // 注入普通值
    #[config("app.title")] title: String,
    
    // v0.8 新特性：支持默认值！
    // 如果配置文件里没有 app.page_size，则使用 20
    #[config("app.page_size:20")] page_size: u32,
) -> String {
    format!("Title: {}, Page Size: {}", title, page_size)
}

注入结构体

你也可以一次性注入整个配置段：

#[derive(Deserialize)]
struct DbConfig {
    url: String,
    pool_size: Option<u32>,
}

#[get("/db-info")]
async fn db_info(#[config("database")] db: DbConfig) -> String {
    format!("URL: {}", db.url)
}

4. 全局程序化访问

如果你需要在 Handler 之外的地方访问配置，可以使用 miko::app::config 模块提供的 API。

use miko::app::config::{get_settings, get_settings_value};

fn init_something() {
    // 获取单个值
    let port: u16 = get_settings_value("server.port").unwrap_or(8080);
    
    // 获取底层 Config 对象进行更多操作
    let settings = get_settings();
}

5. 破坏性变更 (v0.7 -> v0.8)

如果你是从旧版本升级，请注意：

核心配置段重命名：[application] 变更为 [server]。字段 addr 变更为 host。
移除旧 API：ApplicationConfig 结构体和 load_() 方法已被移除，请使用新的 ServerSettings 和 get_settings()。

下一篇预告：Miko 框架系列（十一）：自动生成 OpenAPI 文档

Rust Miko 框架系列（十）：配置管理