块命名与模型整理：Gain1/Gain2 一周后自己都看不懂，命名规范与子系统分层

一、问题的本质：为什么默认命名是技术债

1.1 一个真实的场景

设想这样一个场景：你在一周前搭建了一个电机控制模型，里面有三个增益环节，Simulink 自动命名为 Gain1、Gain2、Gain3。一周后你打开模型，想调整电流环的 Kp 参数，却发现自己完全分不清哪个 Gain 对应哪个环节。你不得不逐个点开属性查看参数值，或者干脆重新推导一遍控制结构。这不是个例——这是 Simulink 建模中最普遍的效率黑洞。

MathWorks 社区论坛中关于"命名规范"的讨论帖累计超过数千条，其中高频出现的抱怨就是"默认命名导致模型不可读"。MathWorks 官方文档在 Modeling Guidelines for High-Integrity Systems 中明确指出：可读性是模型质量的第一要素，而命名是决定可读性的最直接因素。

1.2 技术债的量化视角

软件工程中，技术债（Technical Debt）概念由 Ward Cunningham 于 1992 年提出，指为了短期交付速度而牺牲长期可维护性的累积代价。Simulink 模型中的命名混乱，正是一种典型的"可读性技术债"。

根据国际系统工程委员会（INCOSE）2023 年发布的系统工程手册中的估算数据，在大型复杂系统项目中，模型维护成本约占全生命周期成本的 40%-60%。而可读性差的模型，其维护时间平均增加 30%-50%（数据来源：INCOSE Systems Engineering Handbook, 5th Edition, 2023，为行业调研综合估算值）。

笔者在多个工业项目中观察到一个经验规律：一个 200 个模块的中等规模模型，如果命名规范缺失，新人上手时间约为 3-5 天；如果命名规范完善，上手时间可压缩到 0.5-1 天。这个差距在团队人员流动时会被急剧放大。

1.3 命名混乱的四种典型模式

模式	典型表现	危害
默认命名残留	Gain1、Sum2、Subsystem3	完全无语义，无法定位功能
过度缩写	spd_ctl_kp、tmp1、x2	缩写规则不统一，歧义大
命名与功能脱节	名字叫 Filter 实际是限幅	误导性强，比默认命名更危险
层级扁平化	所有模块平铺在一个顶层	无法建立功能层次认知

本文评述：命名混乱的本质不是"懒"，而是缺乏一套可执行、可检查、可传承的规范体系。单纯靠"提醒大家注意命名"无法解决问题，必须把命名规范嵌入到工具链和流程中，让不合规的命名在提交时就被拦截。

二、命名规范的理论基础与行业标准

2.1 国际主流建模规范概览

在 Simulink 建模领域，目前有若干被广泛认可的规范体系，它们对命名都有明确要求：

规范名称	发布机构	命名核心要求
MAAB Style Guidelines	MathWorks Automotive Advisory Board	禁止默认命名，要求语义化、长度限制
MISRA Simulink/Stateflow	MISRA Consortium	面向安全关键系统，命名需可追溯
JMAAB Style Guide	Japan MATLAB Automotive Advisory Board	日系车企广泛采用，强调一致性
NASA Modeling Standards	NASA	面向航天系统，命名需支持需求追溯
ISO 26262 相关指南	ISO	功能安全语境下的模型可读性要求

MAAB 规范（当前版本为 Version 5.0，2023 年更新）在第 2 章"Model Architecture"中明确要求：所有模块、信号、子系统必须使用有意义的名称，禁止保留 Simulink 默认命名。规范同时建议单个名称长度控制在 32 个字符以内，避免过长影响布局。

MISRA 的 Simulink/Stateflow 建模指南（MISRA AC SLSF，2023 版）则从安全关键角度出发，要求命名必须支持需求追溯——即从模块名能追溯到对应的需求条目。这一要求比单纯的"可读性"更严格。

2.2 命名规范的认知科学基础

命名规范并非纯粹的工程约定，其背后有认知科学支撑。George Miller 于 1956 年提出的"神奇数字 7±2"理论指出，人类工作记忆的容量约为 5-9 个信息块。在阅读模型时，如果每个模块名都需要额外解码（比如 Gain1 需要查看参数才知道含义），就会占用宝贵的工作记忆资源。

John Sweller 于 1988 年提出的认知负荷理论（Cognitive Load Theory）进一步指出：内在认知负荷由问题本身复杂度决定，而外在认知负荷由信息呈现方式决定。糟糕的命名属于典型的外在认知负荷——它不增加问题复杂度，却显著消耗理解者的认知资源。

笔者认为：好的命名本质上是在做"认知外包"——把理解成本从读者大脑转移到模型本身。当你看到 current_loop_kp 时，不需要任何额外推理就知道这是电流环比例增益；而看到 Gain1 时，你的大脑必须启动"查参数→推断功能→记忆映射"三步流程。前者是零认知负荷，后者每次都要付出代价。

2.3 国内外研究现状

在学术研究层面，模型可读性与命名质量的关系已有若干实证研究。德国斯图加特大学软件工程研究所 2022 年发表的一项研究（Ratiu et al., "Assessing the Readability of Model Names in Simulink", 2022）通过对 15 个工业模型的实证分析发现：命名质量与模型缺陷密度呈显著负相关——命名质量高的模型，其缺陷密度平均低 23%。该研究采用 5 级命名质量评分量表，对 3000 余个模块名进行了人工标注与统计分析。

国内方面，北京航空航天大学 2023 年的一项硕士论文研究（基于 Simulink 的飞控模型质量评估方法研究）提出了一套面向航空领域的模型命名质量评估指标，包括语义完整性、一致性、可追溯性三个维度。该研究指出，在飞控模型审查中，命名问题占所有审查问题的 18%-25%。

MathWorks 公司在 2024 年发布的 Model-Based Design 白皮书中，将"命名规范"列为模型质量检查的第一项，并提供了 Model Advisor 中的内置检查规则（Check ID: mathworks.maab.na_0001 等）。

三、三维命名框架：语义密度、作用域与生命周期

3.1 框架总览

笔者结合多年工程实践与对现有规范的梳理，提出一个可操作的三维命名框架。该框架的核心思想是：命名不是单一的"起名字"行为，而是需要在三个维度上同时做出决策。

3.2 维度一：语义密度

语义密度决定了名称的信息量。密度太低（如 g1）无法传达足够信息；密度太高（如 motor_three_phase_current_loop_proportional_gain_final_v2）则冗长难读。笔者建议采用"功能+对象+属性"的三段式结构，但根据作用域灵活调整。

语义密度层级	结构	示例	适用场景
低密度	功能	lpf	子系统内部局部信号
中密度	功能+对象	current_lpf	子系统输入输出端口
高密度	功能+对象+属性	current_loop_lpf_cutoff	顶层接口、跨团队共享信号

这里有一个关键原则：语义密度应与作用域匹配。局部信号可以用低密度名称，因为上下文已经提供了足够信息；而全局接口必须用高密度名称，因为它会在没有上下文的地方被引用。

3.3 维度二：作用域

作用域决定了命名的"前缀策略"。在 Simulink 中，信号和模块的作用域大致可分为三层：

• 子系统内部：仅在当前子系统内可见，命名可简洁，如 err、sat。
• 子系统接口：作为 Inport/Outport 跨子系统传递，命名需包含功能语义，如 speed_ref、torque_cmd。
• 模型顶层/全局：在模型根级或跨模型引用，命名需包含系统级语义，如 vehicle_speed_target。

笔者建议采用"作用域前缀"策略，但前缀不宜过长。例如：局部信号不加前缀，接口信号加功能前缀（ref_、cmd_、fb_），全局信号加系统前缀（veh_、mot_）。

3.4 维度三：生命周期

生命周期维度常被忽视，但在实际工程中非常重要。模型中的元素并非都是永久性的：

• 永久性架构组件：如控制器主体、被控对象模型，命名需正式、稳定。
• 阶段性功能模块：如某个版本的补偿器，命名可包含版本标识。
• 临时调试观察点：如用于调试的 Scope 和 To Workspace，命名应带 dbg_ 前缀，并在提交前清理。

一个常见的坏习惯是：调试用的 Scope1、ToWorkspace2 被永久留在模型里，既占空间又干扰阅读。建议在模型提交检查清单中加入"清理调试模块"一项。

3.5 命名框架的落地模板

综合三个维度，笔者给出一套可直接使用的命名模板：

【信号命名模板】
  <作用域前缀>_<对象>_<属性>
  示例：
    ref_speed            // 接口信号：速度参考
    fb_current           // 接口信号：电流反馈
    mot_temp_measured    // 全局信号：电机温度测量值
    err                  // 局部信号：误差（无前缀）

【模块命名模板】
  <功能>_<对象>[_<限定>]
  示例：
    pi_current           // 电流环 PI 控制器
    lpf_speed            // 速度低通滤波器
    sat_voltage          // 电压限幅
    rate_limiter_torque  // 扭矩速率限制

【子系统命名模板】
  <层级>_<功能域>
  示例：
    l1_current_ctrl      // 第一层：电流控制
    l2_current_pi        // 第二层：电流 PI
    l2_current_lpf       // 第二层：电流滤波

本文评述：模板的价值不在于"必须完全照搬"，而在于提供一套可讨论、可裁剪的基线。团队可以根据自身领域特点调整前缀列表和分段规则，但一旦确定，就必须通过工具强制执行。没有强制力的规范等于没有规范。

四、子系统分层五原则与架构模式

4.1 为什么分层比命名更重要

命名解决的是"单个元素可读"的问题，而分层解决的是"整体结构可理解"的问题。一个模型即使每个模块都命名规范，如果所有模块平铺在一个顶层，阅读者仍然会陷入"信息过载"。

Simulink 官方文档在 Model Architecture 章节中指出：良好的模型架构应该让读者在 3 层以内理解系统的主要功能划分。超过 5 层的嵌套会导致导航困难，而完全不分层则会导致单层信息过载。

4.2 子系统分层五原则

笔者总结出以下五条分层原则，按优先级排列：

4.3 三种典型分层架构模式

根据不同的系统特点，笔者推荐以下三种分层模式：

模式	结构	适用场景
功能分解式	按功能域划分（控制/估计/监控）	大多数控制系统
信号流式	按信号处理阶段划分（采集/处理/输出）	信号处理、通信系统
物理层次式	按物理系统层次划分（部件/子系统/系统）	多物理域系统、车辆模型

4.4 分层重构的操作步骤

如果你面对一个扁平化的混乱模型，可以按以下步骤进行重构：

1. 功能识别：通读模型，用注释或颜色标注出主要功能块。
2. 边界划定：确定哪些模块属于同一功能域，画出边界。
3. 创建子系统：选中功能块，使用 Ctrl+G 创建子系统。
4. 接口整理：为每个子系统添加命名良好的 Inport/Outport，替换原有的 Goto/From。
5. 命名规范化：按三维命名框架重命名所有元素。
6. 验证测试：运行仿真，确保重构前后行为一致。

MathWorks 官方提供了一篇关于模型重构的教程，可参考：Refactor Models - MATLAB & Simulink。此外，YouTube 上的 Simulink 模型重构教程 也有不少实操演示。

五、工程实践：从混乱到有序的重构路径

5.1 重构前的准备工作

在开始重构之前，必须做好以下准备，否则重构可能引入新问题：

• 建立基线：对当前模型进行完整仿真，保存所有关键输出数据，作为重构后的对比基准。
• 版本控制：确保模型已提交到 Git 或 SVN，重构过程中定期提交。
• 测试用例：准备一组覆盖主要功能的测试用例，用于验证重构正确性。
• 命名规范文档：团队达成共识的命名规范文档，作为重构依据。

5.2 分阶段重构策略

大规模重构不应一次性完成，建议分三个阶段：

5.3 批量重命名的脚本实现

MATLAB 提供了丰富的 API 用于批量操作模型元素。以下是一个批量重命名默认 Gain 模块的示例脚本：

% 批量重命名默认 Gain 模块（示例脚本）
% 注意：运行前请备份模型
modelName = 'my_model';
load_system(modelName);

% 查找所有 Gain 模块
gainBlocks = find_system(modelName, 'BlockType', 'Gain');

for i = 1:length(gainBlocks)
    oldName = get_param(gainBlocks{i}, 'Name');
    % 检查是否为默认命名（Gain + 数字）
    if ~isempty(regexp(oldName, '^Gain\d+$', 'once'))
        % 获取 Gain 值，用于生成语义化名称
        gainValue = get_param(gainBlocks{i}, 'Gain');
        % 生成新名称（此处为示例规则，需根据实际调整）
        newName = sprintf('gain_%s', strrep(gainValue, '.', 'p'));
        % 执行重命名
        set_param(gainBlocks{i}, 'Name', newName);
        fprintf('Renamed: %s -> %s\n', oldName, newName);
    end
end

save_system(modelName);

上述脚本仅为示例，实际使用时需要根据团队的命名规则调整 newName 的生成逻辑。更复杂的重命名需求可以参考 MathWorks 官方文档：Programmatically Rename Blocks and Signals。

5.4 信号线的命名与传播

信号线命名是 Simulink 模型可读性的关键。MathWorks 官方推荐使用"信号标签传播"（Signal Label Propagation）功能，让信号名自动传递到子系统内部。

操作步骤：

1. 选中信号线，双击添加标签。
2. 右键信号线 → Properties → 勾选 "Show propagated signals"。
3. 在子系统内部，对应的信号线会自动显示相同的名称。

这一功能可以显著减少"信号名不一致"的问题。更多细节可参考：Signal Label Propagation - MATLAB & Simulink。

六、自动化检查与工具链配置

6.1 Model Advisor 内置检查

Simulink 自带的 Model Advisor 提供了大量与命名和架构相关的检查规则。以下是与本文主题最相关的几条：

Check ID	检查内容	严重级别
mathworks.maab.na_0001	检查默认模块名	Warning
mathworks.maab.na_0002	检查名称长度	Warning
mathworks.maab.jc_0001	检查子系统层级深度	Warning
mathworks.maab.ar_0001	检查模型架构合理性	Warning

运行 Model Advisor 的方法：在 Simulink 中打开模型 → Analysis → Model Advisor → Model Advisor。选择 "By Task" → "MAAB Style Guidelines" 即可运行全套检查。

6.2 自定义检查脚本

Model Advisor 的内置检查覆盖了通用规则，但团队往往有特定的命名约定。可以通过编写自定义检查脚本（基于 MATLAB 的 ModelAdvisor.Check 类）来扩展。

一个简单的自定义检查示例如下：

% 自定义检查：检测不符合团队前缀规范的信号名
function result = checkSignalNaming(system)
    result = ModelAdvisor.ResultDetail;
    validPrefixes = {'ref_', 'cmd_', 'fb_', 'mot_', 'veh_'};
    signals = find_system(system, 'FindAll', 'on', 'Type', 'line');
    
    for i = 1:length(signals)
        sigName = get_param(signals(i), 'Name');
        if isempty(sigName)
            continue;
        end
        % 检查是否有合法前缀
        hasValidPrefix = false;
        for p = 1:length(validPrefixes)
            if startsWith(sigName, validPrefixes{p})
                hasValidPrefix = true;
                break;
            end
        end
        if ~hasValidPrefix
            result(end+1) = ModelAdvisor.ResultDetail;
            result(end).Status = 'Warn';
            result(end).Description = sprintf('Signal "%s" lacks valid prefix', sigName);
        end
    end
end

自定义检查的完整开发流程可参考 MathWorks 官方文档：Define Custom Model Advisor Checks。

6.3 CI/CD 集成

在团队协作环境中，命名检查应集成到持续集成流程中。MathWorks 提供了 Simulink Check 和 Simulink Test 工具，支持在 CI 服务器上自动运行模型检查。

典型的 CI 流程配置：

1. 开发者提交模型到 Git 仓库。
2. CI 服务器（如 Jenkins、GitLab CI）触发构建。
3. 调用 MATLAB 命令行运行 Model Advisor 检查。
4. 检查结果生成报告，不合规项导致构建失败。
5. 开发者根据报告修复问题后重新提交。

这一流程的关键是将命名检查设为"门禁"——不合规的模型无法合并到主分支。虽然初期可能引起团队抵触，但一旦习惯形成，模型质量会显著提升。

七、前沿方向：AI 辅助命名与模型即代码

7.1 AI 辅助命名的可能性

随着大语言模型（LLM）在代码生成领域的应用，AI 辅助 Simulink 命名成为一个有前景的方向。其基本思路是：给定模块的上下文（输入输出信号、参数值、所在子系统），让 LLM 生成语义化的名称建议。

MathWorks 在 2024 年发布的 MATLAB AI 功能中，已经包含了一些代码辅助能力，但针对 Simulink 模型命名的专用功能尚在早期阶段。学术界方面，2023 年有研究探索了基于代码克隆检测的模型命名推荐方法（如 Kästner et al., "Towards Automated Naming of Simulink Models", 2023），但距离工业级应用仍有距离。

笔者认为：AI 辅助命名短期内更适合做"建议"而非"决策"。模型命名的核心难点不是"生成一个名字"，而是"理解设计意图"——而设计意图往往存在于工程师头脑中，而非模型本身。因此，AI 更现实的角色是：在工程师输入一个模糊名称时，提示"这个名字与模型中已有名称冲突"或"建议补充对象信息"。

7.2 模型即代码（MaC）趋势

"模型即代码"（Model as Code, MaC）是近年来 MBSE（基于模型的系统工程）领域的重要趋势。其核心理念是：将模型视为一等公民的代码资产，纳入与软件代码相同的版本控制、审查、测试流程。

在这一趋势下，命名规范的重要性进一步提升——因为模型将像代码一样被 diff、被 review、被自动化工具分析。MathWorks 的 .slx 格式（基于 ZIP 的 XML 封装）已经支持较好的 diff 能力，但可读性仍然依赖命名质量。

GitHub 上的开源项目 simulink-model-diff 提供了模型差异对比工具，可以帮助团队在代码审查中查看模型变更。但这类工具的效果高度依赖命名规范——如果模块名都是 Gain1、Gain2，diff 结果将毫无意义。

7.3 模型度量与质量门禁

学术界和工业界都在探索"模型质量度量"的量化指标。以下是一些被广泛讨论的度量维度：

度量维度	指标示例	数据来源
命名质量	默认命名占比、平均名称长度	Model Advisor 统计
结构复杂度	子系统数量、最大嵌套深度	模型静态分析
接口清晰度	Goto/From 使用次数、跨层信号数	模型静态分析
可测试性	可独立测试的子系统占比	人工评估 + 工具分析

这些指标可以组合成"模型健康度评分"，作为团队质量门禁的一部分。例如：默认命名占比超过 5% 则不允许合并；最大嵌套深度超过 5 层则触发审查。

八、投入产出分析与团队落地建议

8.1 命名治理的投入产出比

很多团队担心"花时间规范命名会影响开发进度"。但从全生命周期看，命名治理的投入产出比是正向的。以下是一个简化的量化分析框架（数据为基于行业经验的模拟估算，非精确测量）：

项目阶段	无规范（人时）	有规范（人时）	差异
初次建模	100	115	+15
调试修改	80	50	-30
团队交接	40	10	-30
新人上手	32	8	-24
合计	252	183	-69

从表中可以看出：虽然初次建模多花了 15% 的时间，但在调试、交接、新人上手环节节省了更多时间。总体来看，有规范的总投入约为无规范的 73%。这还没有计入因命名混乱导致的错误修改、重复沟通等隐性成本。

8.2 团队落地路线图

基于上述分析，笔者建议团队按以下路线图推进命名治理：

1. 第 1 周：制定团队命名规范文档，明确前缀列表、分段规则、长度限制。
2. 第 2-3 周：在 1-2 个试点项目中应用规范，收集反馈并调整。
3. 第 4 周：配置 Model Advisor 自定义检查，集成到 CI 流程。
4. 第 2 个月：对存量模型进行分阶段重构，优先处理高频维护的模型。
5. 第 3 个月起：将命名检查设为合并门禁，持续监控模型健康度指标。

8.3 常见阻力与应对

推行命名规范时，常见的阻力包括：

• "太忙了，没时间改"：回应是展示投入产出分析，说明规范能节省后续时间。
• "我的命名方式就很好"：回应是强调规范的价值在于"一致性"而非"个人偏好"。
• "工具检查太严格"：回应是先从 Warning 开始，逐步过渡到 Error，给团队适应期。

九、总结

回到文章开头的问题：为什么 Gain1、Gain2 一周后就看不懂了？因为默认命名没有承载任何语义信息，而人的记忆是依赖语义关联的。解决这个问题，需要的不是"更努力地记住"，而是一套系统的命名规范与分层方法。

本文提出的三维命名框架（语义密度、作用域、生命周期）和子系统分层五原则，提供了一套可操作的方法论。结合 Model Advisor 检查和 CI 集成，可以将命名规范从"纸面约定"变为"工程实践"。

最后，笔者想强调一个观点：命名规范不是"额外工作"，而是"必要投资"。它不会让模型跑得更快，但会让团队走得更远。在一个模型可能被维护 5 年、10 年的工程世界里，可读性就是生产力。