2. MATLAB工程化项目结构设计

算法从脚本走向可交付的工程，第一步不是优化代码，而是把文件放到正确的位置。一个随手写在桌面上的 test.m 与一个可维护的算法项目，差别往往不在算法本身，而在目录组织、依赖边界、配置分离和版本管理这四件事上。本节围绕一个可复用的信号处理算法项目骨架展开，说明如何让代码在半年后、在同事的机器上、在 CI 服务器上都能被正确运行。

标准工程目录：让每个文件有唯一归属

MATLAB 官方推荐的工程结构以 .prj 工程文件为入口，但即使不使用 Project 工具，也应遵循一套稳定的目录约定。一个典型的算法工程骨架如下：

SignalProcToolbox/
├── SignalProcToolbox.prj      % 工程入口，定义路径与启动脚本
├── startup.m                  % 添加路径、检查依赖版本
├── src/                       % 核心算法，只放函数，不放脚本
│   ├── filters/
│   │   ├── firDesign.m
│   │   └── applyFilter.m
│   └── metrics/
│       └── snrEstimate.m
├── config/                    % 配置分离，环境相关参数
│   ├── default.json
│   ├── dev.json
│   └── prod.json
├── tests/                     % 单元测试与回归测试
│   ├── test_firDesign.m
│   └── testdata/
├── examples/                  % 可运行示例，面向使用者
│   └── demo_filtering.m
├── docs/                      % 文档与接口说明
│   └── api_reference.md
├── tools/                     % 构建、打包、代码检查脚本
│   └── buildPackage.m
└── .gitignore

关键原则是按职责分层，而非按文件类型堆放。src/ 下只允许函数文件，禁止出现依赖 clear all 或交互输入的脚本；examples/ 才是面向使用者的可运行入口。这样做的直接收益是：单元测试可以安全地调用 src/ 中的函数，而不会被脚本的副作用污染工作区。

依赖管理：明确边界，拒绝隐式路径

MATLAB 项目最常见的隐性故障是“在我机器上能跑”——因为某台机器的 path 里恰好有某个第三方工具箱。工程化要求把依赖显式化。对于 MathWorks 官方工具箱，在 startup.m 中用 ver 或 matlab.addons.toolbox 检查版本；对于第三方代码，优先通过 addpath 指向项目内的 extern/ 子目录，而不是依赖用户手动安装。

function startup()
% 检查必需工具箱版本
required = struct('Name', {'Signal_Toolbox'}, 'MinVer', {'9.0'});
v = ver;
for k = 1:numel(required)
    idx = strcmp({v.Name}, required(k).Name);
    assert(any(idx), '缺少工具箱: %s', required(k).Name);
    assert(compareVersion(v(idx).Version, required(k).MinVer) >= 0, ...
        '%s 版本过低，需要 >= %s', required(k).Name, required(k).MinVer);
end
% 添加项目内部路径
addpath(genpath(fullfile(fileparts(mfilename('fullpath')), 'src')));
end

注意 genpath 会递归添加所有子目录，包括 tests/ 和 examples/，这在大型项目中可能引入命名冲突。更严格的做法是只添加 src/ 及其子目录，测试路径由测试运行器单独管理。

配置分离：同一份代码，不同环境参数

算法代码不应硬编码采样率、文件路径、阈值等环境相关参数。把这些值抽到 config/ 下的 JSON 或 MAT 文件中，通过环境变量选择加载哪一份。例如 default.json 定义基线参数，dev.json 覆盖为本地调试值，prod.json 使用生产参数。

{
  "fs": 48000,
  "filterOrder": 64,
  "snrThreshold": 12.5,
  "dataRoot": "./tests/testdata"
}

加载逻辑集中在一个函数中，避免每个模块各自读取文件：

function cfg = loadConfig(env)
if nargin < 1
    env = getenv('SPT_ENV');
    if isempty(env), env = 'default'; end
end
cfgFile = fullfile('config', [env '.json']);
cfg = jsondecode(fileread(cfgFile));
end

这样切换环境只需设置 SPT_ENV=prod，代码路径完全不变。配置分离的另一个好处是：prod.json 可以纳入版本控制但只含占位值，真实密钥通过环境变量注入，避免敏感信息进入 Git 历史。

版本控制与文档规范

MATLAB 工程应使用 Git 管理，.gitignore 至少排除 *.asv、*.mat（除非是测试基线）、slprj/、codegen/ 等生成物。提交粒度以“一个可测试的功能单元”为准，避免把格式化改动和逻辑改动混在一起。

文档方面，每个 src/ 下的函数必须有 H1 行和输入输出说明，格式统一为：

function y = applyFilter(x, coeffs)
%APPLYFILTER 对输入信号应用 FIR 滤波器
%   y = APPLYFILTER(x, coeffs) 返回滤波后的信号。
%   x       - 输入列向量，double
%   coeffs  - FIR 系数，由 firDesign 生成
%   y       - 输出列向量，长度与 x 相同
end

这种注释可被 help 和 doc 直接解析，也是生成 API 文档的基础。项目根目录的 README.md 应说明：如何启动（运行 startup.m）、如何跑测试（runtests('tests')）、如何切换配置（设置 SPT_ENV），以及依赖的工具箱版本。

结构关系总览

下图把上述四类要素放在同一张关系图中：左侧是目录层级，中间是依赖与配置的流向，右侧是版本控制与文档的约束关系。箭头方向表示“被引用/被加载”的方向，而非执行顺序。

把这张图落到实际操作上，一个最小可用的工程化检查清单是：startup.m 能无警告执行；runtests('tests') 全部通过；切换 SPT_ENV 后 loadConfig 返回不同参数；git status 在运行示例后不出现未跟踪的生成文件。满足这四条，项目骨架就已经具备可维护和可协作的基础。