3. 算法接口设计与模块化封装

在 MATLAB 算法工程化部署中，算法能否被稳定复用、独立测试和快速替换，往往不取决于算法本身有多复杂，而取决于接口是否清晰、模块边界是否合理。接口设计的核心目标是：让调用者只关心“输入什么、输出什么、可能出什么错”，而不需要了解内部实现细节。模块化封装则进一步把相关函数、数据与状态组织在一起，形成高内聚、低耦合的单元。

一、函数接口设计原则

MATLAB 函数接口设计应遵循四条基本原则。第一，单一职责：一个函数只完成一件明确的事，例如 normalizeSignal 只负责按指定方式归一化，不负责读文件或画图。第二，显式输入输出：所有影响结果的数据都通过参数传入，所有结果都通过输出参数返回，避免依赖 base 工作区或全局变量。第三，参数校验前置：在函数开头用 arguments 块或 validateattributes 检查类型、尺寸和取值范围，让错误尽早暴露。第四，稳定契约：一旦接口被外部调用，参数名称、顺序、默认值和输出含义应保持向后兼容。

下面是一个带参数校验与默认值的函数接口示例，用于对一维信号做滑动平均：

function [y, info] = movingAverage(x, windowLen, NameValue)
% MOVINGAVERAGE 对一维信号做滑动平均
%   x          : 输入信号，数值向量
%   windowLen  : 窗口长度，正整数
%   'Edge'     : 'shrink'（默认）或 'zero'
%   y          : 平滑后信号，与 x 同尺寸
%   info       : 结构体，含有效窗口数、边界处理方式

arguments
    x (:,1) double {mustBeReal, mustBeFinite}
    windowLen (1,1) double {mustBeInteger, mustBePositive}
    NameValue.Edge (1,:) char {mustBeMember(NameValue.Edge, ...
        {'shrink','zero'})} = 'shrink'
end

n = numel(x);
y = zeros(n,1);
half = floor(windowLen/2);

for k = 1:n
    lo = max(1, k-half);
    hi = min(n, k+half);
    seg = x(lo:hi);
    if strcmp(NameValue.Edge,'zero') && (hi-lo+1) < windowLen
        seg = [seg; zeros(windowLen-(hi-lo+1),1)];
    end
    y(k) = mean(seg);
end

info.WindowLength = windowLen;
info.EdgeMode = NameValue.Edge;
info.ValidCount = n;
end

调用方式为 [y, info] = movingAverage(x, 5, 'Edge', 'zero')。这里 arguments 块同时承担了类型声明、默认值设定和错误提示三项职责，比在函数体内手写 if nargin < 2 更清晰，也更容易被 MATLAB 的代码分析工具检查。

二、包与命名空间的组织方式

当算法模块增多时，仅靠文件夹区分不够，应使用 +package 目录建立命名空间。包目录名以 + 开头，例如 +sigproc，其中的函数通过 sigproc.movingAverage 调用。包的作用有三点：避免不同模块间的函数重名；明确函数的归属；限制作用域，包内函数默认不能被包外直接访问，除非显式导出。

一个典型的工程目录可以组织为：

project/
├─ +sigproc/
│   ├─ movingAverage.m
│   ├─ normalizeSignal.m
│   └─ +filters/
│       ├─ lowpassFIR.m
│       └─ medianFilter.m
├─ +io/
│   ├─ readSensorCSV.m
│   └─ writeResultMAT.m
├─ +cfg/
│   └─ defaultConfig.m
└─ runPipeline.m

调用时使用完整包路径，例如 sigproc.filters.lowpassFIR(x, fs, fc)。这样即使两个模块都定义了 filter 函数，也不会冲突。需要注意的是，包内函数调用同包其他函数时，可以直接写函数名；但跨包调用必须写全路径，这本身就是一种显式的依赖声明。

三、面向对象封装：值类与句柄类的选择

当算法需要维护状态、配置或生命周期时，类比函数更合适。MATLAB 中类分为值类和句柄类：值类对象在赋值时复制，适合表示不可变的数据结构或纯计算模块；句柄类对象在赋值时共享引用，适合表示有状态的对象，如数据采集器、缓存器或需要显式释放资源的对象。

下面定义一个值类，封装滑动平均算法的配置与执行：

classdef MovingAverageFilter
    properties (SetAccess = immutable)
        WindowLength (1,1) double
        EdgeMode (1,:) char
    end

    methods
        function obj = MovingAverageFilter(windowLen, edgeMode)
            arguments
                windowLen (1,1) double {mustBePositive, mustBeInteger}
                edgeMode (1,:) char {mustBeMember(edgeMode, ...
                    {'shrink','zero'})} = 'shrink'
            end
            obj.WindowLength = windowLen;
            obj.EdgeMode = edgeMode;
        end

        function [y, info] = apply(obj, x)
            [y, info] = sigproc.movingAverage(x, ...
                obj.WindowLength, 'Edge', obj.EdgeMode);
        end
    end
end

使用 SetAccess = immutable 后，对象一旦构造完成，配置就不能被外部修改，这保证了算法行为的一致性。调用方式为：

f = MovingAverageFilter(5, 'zero');
[y, info] = f.apply(x);

如果算法需要缓存历史数据或维护内部计数器，则应改为 classdef MovingAverageFilter < handle，并在 delete 方法中释放资源。选择值类还是句柄类，判断标准是：对象是否代表“一份数据”还是“一个持续存在的实体”。

四、高内聚低耦合的落地检查

高内聚指一个模块内部各元素围绕同一职责紧密协作；低耦合指模块之间只通过最小、最稳定的接口交互。落地时可以检查以下几点：模块是否只暴露必要的公开方法；是否通过参数对象或配置结构体传递大量参数；是否存在跨模块直接访问内部属性；是否可以在不修改调用方代码的前提下替换实现。

下图展示了一个典型的算法模块封装结构：外部调用者只接触公开接口层，配置、核心计算与数据访问被封装在内部，依赖方向由外向内单向流动。

图中可以看到，外部调用层只依赖公开接口层，内部实现层的变化不会向上传播。例如把 lowpassFIR 换成 medianFilter，只要 MovingAverageFilter.apply 的输出契约不变，调用脚本无需修改。这就是低耦合带来的可替换性。

综合来看，函数接口负责定义“做什么”，包与命名空间负责定义“归属哪里”，面向对象负责定义“如何维护状态与配置”。三者配合，才能让算法模块在工程化部署中既独立可测，又能被稳定组合。实际项目中，建议先以函数接口实现核心计算，待出现状态管理或配置复用需求时，再引入类封装，避免过早抽象带来的额外复杂度。