Rust 工业边缘 serde_yaml 配置实战

工业边缘网关的配置通常包含服务端口、采集周期、协议参数、设备列表、告警规则和数据上报策略。相比随意拼接 JSON 或环境变量，YAML 更适合表达这类分层的声明式配置；但在 Rust 中，YAML 不能只停留在“能读出来”，还要做到类型严格、默认值明确、变更可校验、热更新失败可回退。

本文围绕 serde_yaml 0.9 展开实战，覆盖结构体反序列化、嵌套列表、可选字段、默认值、枚举、多文档、动态 Value、配置热更新和测试方法。

一、先说清依赖状态

serde_yaml 曾经是 Rust 生态中非常常用的 Serde YAML 实现，但上游项目已经明确标注为不再维护。因此选型时要区分两类场景：

本文示例以 serde_yaml 0.9 的 API 为主。如果使用后续维护分支或其他实现，多数 Serde 派生标注可以复用，但 API 细节仍要以对应版本的文档和测试为准。

依赖示例：

[dependencies]
anyhow = "1"
serde = { version = "1", features = ["derive"] }
serde_yaml = "0.9"
tempfile = "3"
tokio = { version = "1", features = ["fs", "sync"] }

二、基础配置读写

先定义一个贴近工业边缘网关的配置模型：

app_name: edge-gateway
workers: 4
debug: false
database:
  host: db.local
  port: 5432
  user: app

对应 Rust 类型：

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Config {
    pub app_name: String,
    pub workers: u32,
    pub debug: bool,
    pub database: DatabaseConfig,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DatabaseConfig {
    pub host: String,
    pub port: u16,
    pub user: String,
}

pub fn load_from_str(yaml: &str) -> anyhow::Result<Config> {
    let config: Config = serde_yaml::from_str(yaml)?;
    config.validate()?;
    Ok(config)
}

impl Config {
    pub fn validate(&self) -> anyhow::Result<()> {
        if self.app_name.trim().is_empty() {
            anyhow::bail!("app_name cannot be empty");
        }
        if self.workers == 0 || self.workers > 64 {
            anyhow::bail!("workers must be between 1 and 64");
        }
        if self.database.host.trim().is_empty() {
            anyhow::bail!("database.host cannot be empty");
        }
        Ok(())
    }
}

读取、解析和写出：

use std::fs;

fn main() -> anyhow::Result<()> {
    let yaml = fs::read_to_string("config.yaml")?;
    let config = load_from_str(&yaml)?;
    println!("{config:?}");

    let output = serde_yaml::to_string(&config)?;
    fs::write("output.yaml", output)?;

    Ok(())
}

这里建议把“反序列化”和“业务校验”分成两个阶段。类型系统能保证字段类型正确，但无法保证 workers = 9999、空字符串、非法端口范围或互斥配置组合是合理的。

三、嵌套结构与设备列表

工业配置里最常见的是设备、点位和标签列表：

devices:
  - id: dev_001
    voltage: 220.5
    tags: [meter, prod]
  - id: dev_002
    voltage: 221.0
    tags: [meter, backup]

Rust 定义：

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct Device {
    pub id: String,
    pub voltage: f64,
    pub tags: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DeviceConfig {
    pub devices: Vec<Device>,
}

不要为了省事把整段配置读成 serde_yaml::Value 或 HashMap<String, Value>。强类型结构体有三个直接好处：

• 字段名、类型和必填关系在编译期固定；
• 配置漂移更容易通过 diff 和 review 发现；
• 业务代码拿到的是明确字段，而不是到处动态取值和类型转换。

对设备列表还要补业务规则，例如设备 ID 唯一、标签非空、电压范围合法、点位数量符合 license 或资源约束。

四、可选字段、默认值与别名

配置文件不一定要填写每个字段。对可演进字段，可以显式声明默认值：

use serde::{Deserialize, Serialize};

fn default_workers() -> u32 {
    4
}

fn default_sample_interval_ms() -> u64 {
    1000
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RuntimeConfig {
    pub app_name: String,

    #[serde(default = "default_workers")]
    pub workers: u32,

    #[serde(default)]
    pub debug: bool,

    #[serde(default = "default_sample_interval_ms")]
    pub sample_interval_ms: u64,

    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    #[serde(alias = "site")]
    pub plant: String,
}

几个细节：

• #[serde(default)] 对 bool 会得到 false，对 Option<String> 会得到 None；
• 数值默认值建议写成独立函数，便于单元测试复用；
• alias 可以兼容历史字段名，但不要无限累积别名，达到迁移终点后应删除旧字段；
• skip_serializing_if 可以让输出保持干净，但反序列化仍必须处理旧字段；
• 对敏感字段不要使用 YAML 默认值，更不要把真实密码写入配置文件。

如果希望配置文件中出现未知字段时直接报错，可以增加：

#[derive(Debug, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StrictConfig {
    pub app_name: String,
    pub workers: u32,
}

deny_unknown_fields 对拼写错误很有效，例如把 workers 写成 worker 会立刻失败。不过它也会拒绝老程序读取新增字段，适合版本受控的网关配置，不适合作为开放扩展格式。

五、枚举与协议驱动配置

不同协议驱动的参数结构差异很大，枚举比一个大而全的 struct 更合适：

use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum LogLevel {
    Debug,
    Info,
    Warning,
    Error,
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type")]
pub enum DriverConfig {
    Modbus {
        port: String,
        baud_rate: u32,
    },
    Mqtt {
        broker: String,
        topic: String,
    },
    Opcua {
        endpoint: String,
    },
}

如果不使用 rename_all 或 rename，内部标签会按变体名输出。对应 YAML：

log_level: info
drivers:
  - type: Modbus
    port: /dev/ttyUSB0
    baud_rate: 9600
  - type: Mqtt
    broker: broker.local
    topic: devices/+/voltage
  - type: Opcua
    endpoint: opc.tcp://192.168.10.10:4840

枚举配置的校验建议包括：

• topic 符合 MQTT Topic 规则，且不越权订阅系统 Topic；
• baud_rate 属于设备支持列表；
• endpoint 使用允许的协议和地址范围；
• 一个网关内驱动实例数量、串口占用和采集周期不冲突；
• 老配置中已经废弃的驱动变体能给出明确错误。

六、多文档 YAML

YAML 支持用 --- 分隔多个文档。边缘侧可以用它表达“基础配置 + 站点覆盖 + 测试数据”：

app_name: edge-gateway
workers: 4
---
app_name: edge-gateway-test
workers: 1

serde_yaml::Deserializer 可以逐个文档反序列化：

use serde::Deserialize;

fn parse_documents(yaml: &str) -> anyhow::Result<Vec<serde_yaml::Value>> {
    let mut documents = Vec::new();

    for document in serde_yaml::Deserializer::from_str(yaml) {
        let value = serde_yaml::Value::deserialize(document)?;
        documents.push(value);
    }

    Ok(documents)
}

如果最终配置仍是一个强类型对象，更推荐“基础配置 + 覆盖配置”在业务层显式合并，而不是让多个文档隐式生效。多文档的顺序、覆盖策略和冲突处理必须明确写入配置规范。

七、动态 Value 的安全访问

在配置迁移工具、调试页面或 schema 未定型的阶段，可以使用 serde_yaml::Value：

use serde_yaml::Value;

fn inspect_value(yaml: &str) -> anyhow::Result<()> {
    let value: Value = serde_yaml::from_str(yaml)?;

    if let Some(app_name) = value.get("app_name").and_then(Value::as_str) {
        println!("app_name = {app_name}");
    }

    if let Some(devices) = value.get("devices").and_then(Value::as_sequence) {
        for device in devices {
            if let Some(id) = device.get("id").and_then(Value::as_str) {
                println!("device id = {id}");
            }
        }
    }

    Ok(())
}

相比直接使用 value["devices"]["id"] 这类索引访问，get() 会把“字段不存在”和“类型不匹配”处理成普通分支，不会让动态配置的小改动引发运行时 panic。

Value 适合作为过渡和诊断工具，不建议作为核心运行时配置类型。长期保留动态访问会让重构变弱，错误推迟到运行时。

八、配置热更新

工业网关常需要在不停机的情况下调整采集周期或告警规则。热更新的关键是：先完整读取、完整解析、完整校验，全部通过后再交换内存配置。

use std::sync::Arc;

use serde::{Deserialize, Serialize};
use tokio::sync::RwLock;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct GatewayConfig {
    pub app_name: String,
    pub workers: u32,
    pub sample_interval_ms: u64,
}

impl GatewayConfig {
    pub fn validate(&self) -> anyhow::Result<()> {
        if self.workers == 0 || self.workers > 64 {
            anyhow::bail!("workers must be between 1 and 64");
        }
        if self.sample_interval_ms < 100 {
            anyhow::bail!("sample_interval_ms cannot be less than 100");
        }
        Ok(())
    }
}

#[derive(Clone)]
pub struct ConfigManager {
    config: Arc<RwLock<GatewayConfig>>,
}

impl ConfigManager {
    pub async fn load(path: &str) -> anyhow::Result<Self> {
        let yaml = tokio::fs::read_to_string(path).await?;
        let config: GatewayConfig = serde_yaml::from_str(&yaml)?;
        config.validate()?;

        Ok(Self {
            config: Arc::new(RwLock::new(config)),
        })
    }

    pub async fn reload(&self, path: &str) -> anyhow::Result<()> {
        let yaml = tokio::fs::read_to_string(path).await?;
        let new_config: GatewayConfig = serde_yaml::from_str(&yaml)?;
        new_config.validate()?;

        let mut config = self.config.write().await;
        *config = new_config;
        Ok(())
    }

    pub async fn get(&self) -> GatewayConfig {
        self.config.read().await.clone()
    }
}

这段代码保证了一次热更新只会整体生效，不会出现一半字段来自旧配置、一半字段来自新配置的中间态。

生产上还可以补充：

• 配置文件写入使用临时文件加原子 rename；
• reload 前备份当前配置和错误详情；
• 热更新失败时保留旧配置并告警；
• 对高危字段变更要求审批或重启窗口；
• 记录配置版本、文件哈希、操作者和生效时间；
• 需要通知采集任务时，用 tokio::sync::watch 发布版本号。

九、配置文件原子写入

人工编辑或程序生成配置时，都应避免直接覆盖原文件：

use std::io::Write;
use std::path::Path;

use tempfile::NamedTempFile;

pub fn atomic_write_yaml(path: &str, yaml: &str) -> anyhow::Result<()> {
    let target = Path::new(path);
    let directory = target
        .parent()
        .ok_or_else(|| anyhow::anyhow!("invalid config path"))?;

    let mut file = NamedTempFile::new_in(directory)?;
    file.write_all(yaml.as_bytes())?;
    file.sync_all()?;

    file.persist(target)?;
    Ok(())
}

NamedTempFile::new_in 会生成唯一临时文件名，避免两个配置写入任务同时使用固定临时文件。persist 在类 Unix 平台上通过同目录 rename 替换目标文件。更严谨的实现还要考虑目录 fsync、权限保留和 SELinux/AppArmor 上下文。

十、测试配置解析

配置解析代码应该有单元测试，至少覆盖默认值、非法值、未知字段和枚举分支：

#[cfg(test)]
mod tests {
    use super::*;

    #[derive(Debug, serde::Deserialize)]
    #[serde(deny_unknown_fields)]
    struct StrictConfig {
        app_name: String,
        workers: u32,
    }

    #[test]
    fn parse_gateway_config() {
        let yaml = r#"
app_name: edge-gateway
workers: 4
sample_interval_ms: 1000
"#;

        let config: GatewayConfig = serde_yaml::from_str(yaml).unwrap();
        config.validate().unwrap();
        assert_eq!(config.workers, 4);
    }

    #[test]
    fn reject_zero_workers() {
        let yaml = r#"
app_name: edge-gateway
workers: 0
sample_interval_ms: 1000
"#;

        let config: GatewayConfig = serde_yaml::from_str(yaml).unwrap();
        assert!(config.validate().is_err());
    }

    #[test]
    fn reject_unknown_fields_in_strict_mode() {
        let yaml = r#"
app_name: edge-gateway
worker: 4
"#;

        let result: Result<StrictConfig, _> = serde_yaml::from_str(yaml);
        assert!(result.is_err());
    }
}

如果配置来自外部系统，建议增加集成测试：准备多份历史版本配置，验证程序能明确支持、迁移或拒绝，而不是静默忽略差异。

十一、工程实践

十二、常见坑

十三、TL;DR

• serde_yaml 常见于存量 Rust 项目，但上游已停止维护，新项目应把维护状态纳入选型。
• 配置建模优先使用强类型 struct，而不是动态 Value。
• Option 表达可缺失，default 表达可推导，必填字段保持明确。
• 枚举适合表达 Modbus、MQTT、OPC UA 等不同驱动配置。
• 多文档和动态 Value 有适用场景，但必须约束访问和覆盖规则。
• 热更新必须完整解析、完整校验、整体交换，失败保留旧配置。
• 配置变更要版本化、原子化、可审计，敏感信息不能明文落盘。

在工业边缘场景中，Zenova EdgeOS 可将 YAML 声明的设备接入、协议映射与运行策略，同配置校验、热更新和审计联动，让边缘网关的配置变更更可控。