软件架构度量这个词在很多团队里其实是被绕开的。功能需求排期紧代码能跑就行架构好不好先放着。但等项目上了规模线上事故按模块集中爆发、新需求改一处崩三处的时候再回头看架构往往已经积重难返。架构度量要解决的就是这个“事后才发现烂”的问题把架构的健康程度量化成指标持续观测让退化趋势在早期就被看见、被定位、被止损。这篇不会讲空泛的“架构治理理念”直接给一套可以落地的思路。你会看到架构度量怎么定指标、怎么采集数据、怎么算圈复杂度和耦合度、怎么建基线以及怎么把“架构适配”这种容易被忽略的维度纳入度量范围——包括怎么看一个软件支持哪些 CPU 架构、怎么排查依赖包架构不匹配、TPM 度量的基本逻辑还有用等度量映射做架构特征降维可视化的思路。适合架构师、技术负责人、后端开发和 QA 工程化团队参考。先说结论架构度量不是搞一堆报表给领导看它的真正价值是给架构做“体检”。指标本身不解决问题但它能告诉你问题在哪、严重到什么程度、哪些模块正在变坏。有了这个前提后面的工具选型、指标口径、落地节奏才谈得上。1. 架构度量核心能力速览项目说明度量对象代码结构、模块依赖、耦合与内聚、复杂度、规模、技术债务、运行架构适配核心指标圈复杂度、扇入扇出、耦合度、内聚度、代码重复率、依赖环、架构契合度常用工具cloc、SonarQube、ArchUnit、JDepend、dependency-cruiser、Structure101、自研采集脚本输出形式指标报表、趋势曲线、依赖图、架构适配矩阵、降维可视化散点图适用阶段存量系统架构体检、新系统架构守护、重构前后对比、技术债务治理集成方式CI 流水线、定时任务、代码仓库 Webhook、架构评审辅助是否需要重构不需要先度量后治理指标是诊断依据不是惩罚依据落地周期小团队可先用脚本起量级再逐步接入平台化工具这里有一个关键认知架构度量并不等于“代码扫描”。代码扫描偏向找 bug、找安全漏洞而架构度量关注的是结构性问题——模块边界是否清晰、依赖是否合理、变更成本是否在膨胀、系统是否还能按预期演进。从材料里可以看到热词中同时出现了“软件架构”“度量”“等度量映射”“TPM 度量”“CPU 架构查看”“软件包架构不匹配”这些方向。这说明实际操作中架构度量并不只是静态代码分析还要包含“运行架构”和“适配架构”的度量。比如你做一个跨平台软件结果某个依赖库不支持目标 CPU 架构安装时直接报“软件包架构不匹配”那这套系统的可交付性就是不合格的。这类问题也应该纳入架构度量的范围。2. 架构度量的适用场景与使用边界架构度量适合哪些场景先说最典型的三个。第一个是存量系统架构体检。系统跑了三五年文档早就过期核心模块没有人敢动。这时候通过依赖分析、复杂度统计、变更热力图可以快速定位“这个系统里哪些模块最复杂、最多人改、最容易出问题”。这些信息比翻旧文档可靠得多。第二个是重构效果验证。重构前记录一轮指标重构后再记录一轮对比复杂度、耦合度、重复率的变化。如果重构后圈复杂度没有下降、模块依赖反而更乱了说明重构方向可能有问题。这个对比过程完全是数据驱动的比“我觉得重构得不错”有说服力得多。第三个是架构守护。在 CI 流水线里加一道架构检查比如禁止某层反向依赖、禁止循环依赖、禁止模块数量超过阈值。一旦有人提交了破坏架构规则的代码流水线直接失败。这是防止架构腐化的最有效手段之一。但架构度量也有边界。它度量的是“结构健康度”不是“业务正确性”。一个系统架构指标很漂亮不代表功能没有问题。同样指标也不是越低越好——过度追求低耦合可能会把系统拆成碎片过度追求高内聚可能导致模块体积膨胀。另外度量数据本身有滞后性它反映的是历史积累的结果不能预测下一次线上故障。更实际的做法是把它当作“风险信号”而不是“评价 KPI”。还有一个必须强调的边界合规与隐私。做架构度量通常要扫描代码仓库、分析依赖、记录模块变更历史。如果是企业内部系统这些数据要控制访问范围不能把内部代码和依赖信息上传到未经授权的第三方平台。涉及 TPM 度量、可信计算相关的内容时只能从技术流程角度做解释和度量不能涉及任何绕过安全机制的操作。涉及人脸、声音、版权素材的架构功能比如音视频处理系统在度量这些模块时要同步检查授权链路是否完整。3. 架构度量指标维度与关键计算方式架构度量不是只看一两个数字而是要从多个维度组合观察。一个健康的架构通常需要在以下维度上保持平衡维度典型指标计算方式关注点规模代码行数、文件数、模块数、类数直接统计或工具采集系统膨胀速度复杂度圈复杂度、认知复杂度(V(G) E - N 2) 或工具计算代码可读性与测试难度耦合扇入、扇出、模块间依赖数、耦合度依赖图分析模块间影响扩散范围内聚类内聚度、模块内聚度方法间关联度计算模块职责是否单一重复代码重复率、重复块数量文本归一化比对复制粘贴导致的维护风险依赖质量循环依赖数、依赖深度、稳定度依赖图遍历架构边界是否清晰架构契合度实际依赖与目标架构的偏差规则校验差异统计代码是否遵守既定架构适配性支持 CPU 架构数、依赖包架构匹配率环境探测与依赖元数据检查跨平台可交付能力实际落地时不一定要把每个维度都做全。建议优先级是这样的第一优先做复杂度、耦合、重复率因为它们最能反映代码维护风险第二优先做依赖质量特别是循环依赖它能快速暴露架构边界的破损第三再考虑规模、内聚、架构契合度和适配性。3.1 圈复杂度的计算口径圈复杂度是架构度量里最常见的指标它衡量一个函数或方法的独立路径数量。公式是[ V(G) E - N 2 ]其中 E 是控制流图中的边数N 是节点数。实际写代码的时候if、switch、for、while、catch 都会增加复杂度。很多工具已经能在解析语法树后直接给出结果不需要手动实现。但要注意不同工具的统计口径会有差异比如是否把 catch 计算进去、是否处理短路逻辑。所以做横向对比时尽量固定同一套工具链。3.2 扇入扇出与耦合度扇入Fan-in是指一个模块被多少个其他模块调用扇出Fan-out是指一个模块调用了多少个其他模块。高扇出的类往往承担了过多职责修改它可能影响一大片调用方高扇入的类往往是公共基础类变更时要格外谨慎。耦合度的计算可以简单化处理[ Coupling \frac{实际模块间依赖数}{模块总数 \times (模块总数 - 1)} ]这个值越高说明模块之间交错越严重。配合循环依赖检测一起看能很快找出“这个系统为什么改一处崩三处”的结构性原因。3.3 内聚度的实际判断内聚度是衡量一个模块内部元素关联程度的指标。完全数学化的内聚度计算需要分析类内方法间的数据依赖工程上更实用的做法是直接看一个类的字段被多少方法使用、一个模块是否承担了多个不相关的职责。如果一个工具类里有“日期转换”“字符串处理”“HTTP 调用”三个毫不相关的方法组那它的内聚度基本可以判定为不合格。4. 架构度量工具链与数据采集工具的选择取决于技术栈和度量目标。下面是几类常用工具对应不同采集需求工具用途适用场景cloc / scc统计代码行数、注释比例快速摸清仓库规模SonarQube圈复杂度、重复率、规范扫描持续集成、质量门禁ArchUnitJava 架构规则测试架构守护、依赖规则校验JDependJava 包依赖分析包级耦合、循环依赖检测dependency-cruiserJavaScript/TypeScript 依赖分析前端模块边界检查Structure101架构可视化与违规分析大型系统架构治理pmd / cppcheck / bandit语言级静态检查多语言项目扫描自研脚本依赖矩阵、Git 变更热力统计定制化指标采集实际落地时不建议一上来就铺全套工具。更务实的路径是先用 cloc 看规模用 SonarQube 或语言原生工具看复杂度和重复率用依赖分析工具看耦合与循环依赖。跑通一轮再逐步接入 CI。4.1 命令行采集示例规模统计用 cloc 做直接出报告# 统计当前仓库代码量排除构建目录 cloc . --exclude-dirnode_modules,dist,build,target --by-file --report-filecloc_report.txt依赖分析用 dependency-cruiser 做支持自定义规则# 安装依赖分析工具 npm install --save-dev dependency-cruiser # 生成依赖图 npx depcruise src --include-only ^src --output-type dot | dot -T svg dependency-graph.svg # 校验架构规则 npx depcruise --validate .dependency-cruiser.js srcJava 项目用 ArchUnit 写架构规则测试直接嵌入测试框架AnalyzeClasses(packages com.example.app) public class ArchitectureRuleTest { Test public void 控制层不得依赖持久层() { JavaClasses classes new ClassFileImporter().importPackages(com.example.app); ArchRule rule noClasses() .that().resideInAPackage(..controller..) .should().dependOnClassesThat() .resideInAPackage(..repository..); rule.check(classes); } }这类规则一旦跑在 CI 里就形成架构守护闭环提交代码 - 跑测试 - 违规即失败。4.2 依赖矩阵与 Git 变更统计依赖矩阵是另一种有效的采集方式。把模块名作为行和列单元格填依赖次数就能得到一个依赖矩阵。用 Python 的 pandas 可以直接从导出数据构建import pandas as pd data { from_module: [auth, auth, order, order, pay], to_module: [order, pay, pay, user, user], } df pd.DataFrame(data) matrix pd.crosstab(df[from_module], df[to_module]) print(matrix)输出结果可以直观看到模块间的依赖频次。依赖频次最高的路径通常就是变更风险最高的链路。Git 变更热力统计也值得做。分析最近 N 次提交中哪些文件被改得最多、哪个模块累计变更量最大、有没有“每次发布都要动”的钉子户文件。这类数据用脚本就能算# 统计最近 90 天提交最频繁的 20 个文件 git log --since90 days ago --name-only --prettyformat: | sort | uniq -c | sort -rn | head -20把“变更集中度”和“架构复杂度”两张图叠在一起看你会发现最危险的模块往往是“既复杂又经常改”的那一批。5. 架构度量的基线与目标设定没有基线的指标是没有意义的。第一次扫描出来“圈复杂度平均值是 8”这个数字本身不能说明好坏需要对比行业经验值或者项目历史数据才能判断是偏高还是正常。所以落地架构度量的第一步是先跑一轮“摸底扫描”把当前数据记录下来形成基线。基线的设定有几个原则。不要用绝对标准一刀切。不同语言、不同业务领域的复杂度差异很大一个 3 万行的配置处理模块和一个 3 万行的业务逻辑模块合理的复杂度阈值是完全不同的。应该按模块分层设定不同的阈值比如基础设施层允许更高的复杂度业务层要求更低。用百分位数代替平均值。平均值容易被极端值拉偏更稳妥的方式是看 P50、P90、P95。比如“全项目圈复杂度 P90 是 12”意思是 90% 的函数复杂度都低于 12剩下 10% 是重点治理对象。这比“平均复杂度 5.8”更有工程指导价值。目标要分阶段。不要期望一个月把技术债清零建议按季度设定降幅目标比如“Q3 把 P90 圈复杂度从 12 降到 10循环依赖模块数从 15 个降到 8 个”。目标越具体治理越容易推进。技术债可以参照 SonarQube 的 SQALE 模型来估算修复成本。它的思路是把每个违规项换算成预计修复时间再汇总得到总技术债。比如一个项目显示“技术债 32 人天”意思是按当前团队效率把这些结构性问题修完大约需要 32 个工作日。这个数字更适合做优先级排序。6. 架构适配度量CPU 架构、依赖匹配与 TPM 度量过程这一部分容易被忽略但对跨平台系统和信创环境来说非常关键。架构度量不能只盯着代码结构还要度量“软件能不能在目标环境下正确运行”。这涉及 CPU 架构适配、依赖包架构匹配以及可信度量过程。6.1 如何查看一个软件支持的 CPU 架构在 Linux 环境下查看已安装软件包架构最直接的方式是用包管理工具# Debian/Ubuntu dpkg --print-architecture dpkg --print-foreign-architectures dpkg -l | grep ^ii | awk {print $2, $3, $4} | head # 查看某个软件包的架构 dpkg -I some-package.deb | grep Architecture # RHEL/CentOS rpm -q --qf %{NAME}-%{VERSION}-%{RELEASE} %{ARCH}\n package-name在 Android 场景下想查看 APK 支持哪些 CPU 架构可以解包后检查 lib 目录unzip app.apk -d apk_extracted ls apk_extracted/lib/正常情况下会列出arm64-v8a、armeabi-v7a、x86、x86_64等目录。如果某个架构目录缺失说明该 APK 不支持对应架构的设备。还有一种方式是用 aaptaapt dump badging app.apk | grep native-code它会直接输出 APK 支持的原生库架构列表。理解这个信息的意义在于架构度量要回答“这个软件的真实可运行范围”是什么而不仅仅是“代码能编译过”。6.2 统信系统安装软件提示软件包架构不匹配在统信 UOS 这类基于 Linux 的国产操作系统上安装软件有时会提示“软件包架构不匹配”。这通常意味着你尝试安装的软件包架构和系统架构不一致。典型场景是系统是 arm64 架构但下载的安装包是 amd64 的或者系统默认只启用了 amd64 架构却想安装 arm64 的包。处理思路是# 确认系统主架构 dpkg --print-architecture # 确认是否启用了多架构 dpkg --print-foreign-architectures # 如果需要启用 arm64 支持 sudo dpkg --add-architecture arm64 sudo apt update如果启用了对应架构但还是报错需要进一步查看软件包本身的依赖是否完整# 检查依赖缺失情况 sudo apt install -f sudo apt --fix-broken install在架构度量体系里这类问题应该被记录为“可交付性缺陷”。如果目标环境包含多种 CPU 架构而构建产物没有按架构矩阵做适配验证那就是架构层的风险点。6.3 TPM 度量过程简述热词中出现“TPM 度量过程”这里可以理解为“信任平台模块的度量过程”也可以理解为“团队绩效度量中的 TPM 过程”等不同语境。常见技术语境下TPM 是可信平台模块用于度量系统的完整性状态——在启动过程中对固件、引导加载程序、操作系统内核进行哈希度量并将度量值扩展到平台配置寄存器PCR用于证明系统处于可信状态。用 TPM 做完整性度量的基本过程是度量对启动链中的每个组件计算哈希值。存储将哈希值扩展到 PCR 寄存器而不是直接覆盖。报告向验证方提供 PCR 值和度量日志。验证验证方比对 PCR 值是否与预期一致。在架构度量中如果系统涉及可信计算能力应该把“是否具备完整性度量链”“度量日志是否可审计”“PCR 策略是否可更新”纳入非功能架构检查项。这里只做技术流程层面的度量设计说明具体部署需结合芯片型号和平台需求来实现。6.4 等度量映射与架构特征降维“等度量映射”在机器学习里常用于降维可视化。架构度量会产生大量高维数据——每个模块的复杂度、耦合度、变更频率、重复率、测试覆盖率等直接看表格看不出聚类关系。这时可以用降维方法把高维架构指标映射到二维平面观察模块分布是否合理。主成分分析PCA是最常用的线性降维方法等度量映射Isomap则适合保留流形结构。示例代码如下from sklearn.manifold import Isomap from sklearn.preprocessing import StandardScaler import pandas as pd # 假设 metrics 是模块级架构指标表 # 每行代表一个模块每列代表一个指标 df pd.read_csv(module_metrics.csv) feature_cols [complexity, fan_out, fan_in, duplication, change_freq, coverage] X df[feature_cols] # 标准化消除量纲影响 scaler StandardScaler() X_scaled scaler.fit_transform(X) # 等度量映射降维到 2 维 model Isomap(n_neighbors8, n_components2) embedding model.fit_transform(X_scaled) df[x] embedding[:, 0] df[y] embedding[:, 1] # 输出每个模块的二维坐标 print(df[[module, x, y]].head())降维后可以把模块按所属分层或团队染色观察是否存在“多个模块挤在一起但职责完全无关”的异常聚类。这种可视化对架构评审特别有帮助它能让“架构是不是乱了”这个问题变得肉眼可见。7. 架构度量可视化与报告度量数据只有变成图表和报告才能推动决策。常用的可视化形式有这么几种依赖关系图是最直观的方式。工具可以生成 SVG 或 PNG 格式的依赖图节点代表模块边代表依赖关系。如果图中有密集的环状连接基本可以判定这里的架构边界已经失效。推荐先用 dependency-cruiser 生成 SVG再用浏览器打开交互式查看。趋势折线图用来观察指标变化。“圈复杂度 P90 过去 6 个月的趋势”“循环依赖模块数量趋势”“重复率趋势”这些折线图能暴露架构是变好还是在腐化。雷达图适合做多维度横向对比。把复杂度、耦合、内聚、重复率、适配性几个维度归一化后画雷达图可以看到系统整体的健康画像。某几个维度明显凹陷就是需要优先治理的方向。技术债分布图用堆叠柱状图展示每个柱子代表一个模块堆叠部分按违规类型分色。一眼能看出哪个模块技术债最多、主要是哪类问题。报告不用太长控制在 2 页以内。第一页放核心结论整体评分趋势、风险模块 Top10、新增架构违规数。第二页放详细数据表。报告要回答三个问题架构是变好了还是变坏了、哪里最危险、下一步动哪里。8. 架构度量落地中的常见问题与排查方法问题现象可能原因排查方式解决方案工具扫描结果为空未正确配置源代码目录检查扫描路径和排除规则设置 include/exclude 目录重复率统计偏差大生成了大量模板代码排除生成代码目录将 generated 目录加入排除列表圈复杂度集中在少数类老代码长期无人重构查看 Top 复杂度列表按模块分阶段重构依赖图过大无法阅读模块粒度太细聚合到包或组件层级按命名空间聚合展示循环依赖检测报错存在真正的循环引用定位环的路径抽公共模块或依赖倒置架构规则测试不稳定测试与代码生成顺序冲突检查执行顺序在代码生成后统一执行指标与团队感知不符统计口径或工具不同抽查样本手工验证统一工具和基线安装软件包提示架构不匹配包架构与系统架构不一致检查 dpkg/rpm 架构启用对应多架构或下载正确包CI 跑架构检查太慢全量扫描耗时过长观察扫描耗时增量扫描或仅扫描变更模块8.1 指标看起来很好但架构还是乱这是非常常见的问题。原因是单一指标有幸存者偏差。比如圈复杂度很低但模块之间互相乱调整体耦合依然很高。或者重复率很低但模块内部代码是“大泥球”没有清晰分层。解决方法是组合指标判断。架构健康度至少要看“复杂度 耦合 依赖规则”三项的组合。单看任何一项都可能得出错误结论。更稳妥的做法是挑 3 个“一级指标”和 5 个“二级指标”一级指标出现在月度报告里二级指标只在异常时深入分析。8.2 扫描工具多数据口径不一致不同工具对同一个项目的圈复杂度统计结果可能差 20% 以上。原因是它们的语法解析规则不同。遇到这种情况不要纠结哪个工具更准而是固定一个工具作为“主数据源”其他工具的数据只做参考。在报告里注明数据来源工具和采集时间避免跨工具对比产生误导。9. 最佳实践与落地建议第一第一次试点不要选大项目。找一个 20 万行以内的中型服务做试点跑通“扫描 - 基线 - 报告 - 评审”全流程。小项目验证方法大项目再复制推广。第二架构指标不要直接关联绩效考核。一旦指标和绩效挂钩就会出现“美化数据”的行为。正确的用法是让指标帮助团队发现风险而不是让团队去“刷指标”。复杂度高的代码如果确实必要可以放宽阈值但必须在评审中说明理由。第三把架构规则变成自动化门禁。ArchUnit、dependency-cruiser 这类工具的价值就在于可嵌入 CI主动拦截违规提交。人工评审总会有遗漏规则测试可以兜底。第四保障数据安全和合规。架构度量涉及源码和依赖信息如果是私有代码库必须确保扫描和存储都在受控环境内。依赖分析工具如果支持远程组件库查询要注意是否有代码或依赖元数据上传行为必要时使用离线模式。第五定期清理度量口径。团队技术栈会演进度量指标也要跟着调整。每半年审视一次当前指标还能不能反映架构健康度需不需要增删。保持指标体系精简避免指标爆炸导致团队疲于应付。第六不要忽略构建设计的合理性。很多度量工具都提供预构建包也可以从源码构建。选预构建包要看它是否匹配你的系统和 CPU 架构避免出现“架构不匹配”这种低级却致命的问题。如果选择源码构建要控制好依赖版本保证构建环境和运行环境一致。10. 总结与下一步架构度量最值得尝试的点是你不需要先做大规模重构就能获得一份系统“体检报告”。从 cloc 统计规模开始到 SonarQube 看复杂度再到依赖分析看耦合和循环依赖最后加一道架构规则测试进 CI整个过程可以在两周内跑通。最先应该验证的是圈复杂度和循环依赖这两个指标因为它们的采集成本最低、对架构问题的指示性最强。最容易踩的坑是把指标变成 KPI导致团队玩数字游戏一定要从落地第一天就明确“指标是用来定位风险不是用来惩罚人”。下一步的方向有三个第一个是接入更多语言和项目扩大度量覆盖面第二个是把 Git 变更历史和架构指标关联建立“变更风险预测”能力第三个是建立季度架构评审机制把月度指标趋势、风险模块清单、架构规则违规情况放进评审议程让架构治理从“一次性的体检”变成“持续的守护”。建议先找一个你手上最头疼的模块跑一遍复杂度扫描和依赖分析。看到结果之后你就知道这套方法值不值得往下推了。