什么是 TOML？

🛠 Rust 配置文件实战：TOML 语法详解与结构体映射（

在 Rust 中，Cargo.toml 是每个项目的心脏。它不仅定义了项目的名称、版本和依赖项，还使用了一种轻巧易读的配置语言：TOML。

本文将深入解析 TOML 的语法，并带你一步步学会如何用 Rust 来读取并解析 TOML 文件，并最终将其映射为你可以直接使用的结构体对象。文章包括：

• TOML 基本与复杂语法详解
• Rust 中对应的数据结构表示

📘 什么是 TOML？

TOML，全称 Tom’s Obvious, Minimal Language，是一个专门为配置文件设计的语言，追求的是：

“人类易读 + 机器易解析”。

TOML 的语法非常接近 INI，但更加强大和一致性，是 Rust 官方默认的配置文件格式。

🔧 TOML 基本语法

1. 键值对（Key = Value）

name = "MyApp"
version = "1.0.0"

• 键（key）和等号之间允许空格
• 字符串必须用引号包裹

2. 注释

# 这是一个注释
name = "MyApp"  # 这也是注释

3. 支持的数据类型

📦 表（Table）与嵌套结构

1. 表

[database]
host = "localhost"
port = 3306

相当于创建了一个 database 命名空间。

2. 嵌套表（Nested Table）

[owner]
name = "Tom"

[owner.address]
street = "123 Elm"
city = "Springfield"

等价于：

{
  "owner": {
    "name": "Tom",
    "address": {
      "street": "123 Elm",
      "city": "Springfield"
    }
  }
}

📚 数组和数组表（Array of Tables）

1. 普通数组

fruits = ["apple", "banana", "pear"]

2. 数组中的表（Array of Tables）

[[servers]]
name = "Server1"
ip = "192.168.1.1"

[[servers]]
name = "Server2"
ip = "192.168.1.2"

这表示 servers 是一个表数组，类似于：

{
  "servers": [
    { "name": "Server1", "ip": "192.168.1.1" },
    { "name": "Server2", "ip": "192.168.1.2" }
  ]
}

🦀 在 Rust 中读取 TOML 配置

1. 添加依赖

在 Cargo.toml 中加入：

[dependencies]
serde = { version = "1.0", features = ["derive"] }
toml = "0.5"

2. 假设我们的配置如下（config.toml）：

[app]
name = "MyApp"
version = "1.0.0"

[[servers]]
name = "Server1"
ip = "192.168.1.1"
port = 8080

[[servers]]
name = "Server2"
ip = "192.168.1.2"
port = 8081

[database]
host = "localhost"
port = 3306
username = "root"
password = "secret"

3. Rust 中的结构体定义

use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Config {
    app: App,
    servers: Vec<Server>,
    database: Database,
}

#[derive(Debug, Deserialize)]
struct App {
    name: String,
    version: String,
}

#[derive(Debug, Deserialize)]
struct Server {
    name: String,
    ip: String,
    port: u16,
}

#[derive(Debug, Deserialize)]
struct Database {
    host: String,
    port: u16,
    username: String,
    password: String,
}

4. 加载并解析 TOML

fn main() {
    let config_str = std::fs::read_to_string("config.toml").expect("读取失败");

    let config: Config = toml::from_str(&config_str).expect("解析失败");

    println!("{:#?}", config);
}

🧾 解析后的数据长什么样？

运行 cargo run 后，你会看到打印出的结构体内容如下：

Config {
    app: App {
        name: "MyApp",
        version: "1.0.0",
    },
    servers: [
        Server {
            name: "Server1",
            ip: "192.168.1.1",
            port: 8080,
        },
        Server {
            name: "Server2",
            ip: "192.168.1.2",
            port: 8081,
        },
    ],
    database: Database {
        host: "localhost",
        port: 3306,
        username: "root",
        password: "secret",
    },
}

你现在可以像正常使用结构体那样访问这些配置项：

println!("App Name: {}", config.app.name);
println!("DB Host: {}", config.database.host);
println!("First Server IP: {}", config.servers[0].ip);

✅ 总结

📌 附加：配置热更新方案（高级进阶）

• 使用 notify crate 监听 TOML 文件变化
• 使用 lazy_static 或 once_cell 实现全局配置缓存
• 定时 reload 或 on-change reload 配置