📚 课程目录第4章配置与参数管理标准化

4. 配置与参数管理标准化

在工程计算项目中，参数往往比算法更容易引发事故。同一段 MATLAB 代码，在开发机上运行正常，换到测试环境或交付现场却报错，原因常常不是逻辑错误，而是路径、采样率、阈值、单位或数据源被硬编码在脚本里。配置与参数管理标准化的目标，就是把“会变的量”从代码中抽离出来，用统一的结构承载，并让不同环境、不同版本之间的差异可追溯、可切换、可复现。

一、配置的四种承载形式与选择依据

MATLAB 工程中常见的配置载体有四类：结构体（struct）、JSON、YAML 和 MAT 文件。它们并非互相替代，而是各有适用边界。

结构体：运行期内存对象，访问最快，适合作为程序内部统一的配置传递格式。所有外部配置读入后，建议先归一化为结构体，后续函数只依赖结构体字段，不关心来源。
JSON：文本格式，跨语言、跨平台通用，适合与外部系统交换配置，也便于用 Git 做逐行差异对比。缺点是注释支持弱，数值精度和类型需显式处理。
YAML：可读性最好，支持注释和层级缩进，适合人工维护的工程参数文件。MATLAB 需借助第三方解析器或转换为 JSON 后读取，引入依赖时需评估交付环境是否允许。
MAT 文件：MATLAB 原生二进制格式，可直接保存结构体、数组、函数句柄等复杂对象，适合保存标定结果、查找表、大块数值参数。缺点是二进制不便人工审阅和版本对比。

一个务实的组合策略是：YAML/JSON 作为人工可编辑的源配置，MAT 作为数值型标定结果的归档，结构体作为运行期唯一入口。三者通过一个加载函数收敛，避免代码各处直接读文件。

二、环境隔离：base + overlay 的合并模型

环境隔离不是为每个环境复制一份完整配置，而是采用“基础配置 + 环境覆盖”的合并模型。基础配置 config_base.json 存放所有环境共有的参数，环境文件只写差异项。加载时先读基础，再用环境文件递归覆盖同名字段，未覆盖的字段自动继承。

% config/loadConfig.m
function cfg = loadConfig(envName)
    baseFile = fullfile('config','config_base.json');
    envFile  = fullfile('config',['config_' envName '.json']);
    cfg = jsondecode(fileread(baseFile));
    if isfile(envFile)
        over = jsondecode(fileread(envFile));
        cfg  = mergeStruct(cfg, over);   % 递归覆盖
    end
    cfg.env = envName;
    cfg.loadedAt = datestr(now,'yyyy-mm-dd HH:MM:SS');
end

function a = mergeStruct(a, b)
    f = fieldnames(b);
    for k = 1:numel(f)
        if isfield(a,f{k}) && isstruct(a.(f{k})) && isstruct(b.(f{k}))
            a.(f{k}) = mergeStruct(a.(f{k}), b.(f{k}));
        else
            a.(f{k}) = b.(f{k});
        end
    end
end

这样，config_dev.json 只需写 {"data":{"root":"D:/data/dev"},"solver":{"tol":1e-6}}，而 config_prod.json 写 {"data":{"root":"/opt/app/data"},"solver":{"tol":1e-8}}，其余如采样率、通道数、单位制全部继承基础配置。切换环境只改一个入参，不碰任何业务代码。

环境名建议限定为 dev / test / prod 三类，并在加载函数中校验白名单，防止拼写错误导致静默回退到基础配置。

三、参数版本化：让每次运行可复现

参数版本化要解决两个问题：一是知道“这次结果用的是哪版参数”，二是能“回到那一版参数重跑”。推荐做法是给配置目录本身纳入版本控制，并在每次运行开始时把生效配置快照写入结果目录。

cfg = loadConfig('prod');
runId = datestr(now,'yyyymmdd_HHMMSS');
outDir = fullfile('runs', runId);
mkdir(outDir);
save(fullfile(outDir,'config_snapshot.mat'), 'cfg');   % 运行快照
writelines(jsonencode(cfg,'PrettyPrint',true), ...
           fullfile(outDir,'config_snapshot.json'));   % 可读副本

快照同时保存 MAT 与 JSON 两份：MAT 保证复杂字段无损还原，JSON 便于人工比对和代码评审。若某次结果异常，只需用对应快照重跑，即可排除“参数被改过”的干扰。对于关键参数，还可在配置中增加 schemaVersion 字段，当结构发生不兼容变更时，加载函数据此提示迁移。

四、参数校验：把错误挡在计算之前

配置读入后必须校验，否则错误会以难以定位的形式出现在计算深处。校验分三层：字段存在性、类型与范围、跨字段一致性。例如采样率必须为正，起始频率必须小于终止频率，通道数必须与标定表行数一致。

function validateConfig(cfg)
    assert(cfg.solver.tol > 0, 'solver.tol 必须为正');
    assert(cfg.acq.fs > 0,   'acq.fs 必须为正');
    assert(cfg.acq.fStart < cfg.acq.fStop, '频率区间非法');
    assert(size(cfg.calib.gain,1) == cfg.acq.nCh, ...
           '标定表行数与通道数不一致');
end

校验失败应直接报错并给出字段路径，而不是返回默认值继续运行。默认值掩盖问题，是配置管理中最危险的反模式。

五、落地要点与常见陷阱

第一，禁止在业务函数中直接读文件。所有配置读取集中在 loadConfig，业务函数只接收结构体。这样单元测试可以手工构造结构体，无需准备真实配置文件。

第二，路径与机器相关参数必须外置。数据根目录、临时目录、日志目录、许可证路径都属于环境差异项，应放在 overlay 中，绝不写进基础配置。

第三，单位与量纲写进字段名或注释。例如 fs_Hz、tol_rel、length_mm，避免“这个 1000 到底是 Hz 还是 kHz”的歧义。跨单位换算只在加载后统一执行一次。

第四，敏感信息不进入配置文件。密码、令牌应通过环境变量或密钥管理服务注入，配置文件中只保留占位符或引用键。

常见陷阱：用 exist 或 try/catch 静默吞掉配置缺失，回退到硬编码默认值。这会让不同环境的行为悄悄分叉，且难以复现。正确做法是缺失即报错，把问题暴露在启动阶段。

把上述做法固化为项目模板后，新成员加入时只需理解一个加载入口、一套字段命名约定和一份环境清单，就能安全地切换环境、复现历史结果。配置管理标准化的价值，最终体现在“换一台机器、换一个环境、换一个时间点，结果依然可解释、可复现”。