SuperAPI AI 工具集

deep-module-design

编程与开发

查看项目

更新于 11-09 12:07

技能介绍

Deep Module Design 是一个面向模块级代码设计的技能,针对的是「越来越难改」的代码库。其核心理念是:深模块用很小的接口向调用方提供大量行为;浅模块则让调用方几乎要学一样多的东西。该技能负责衡量代码库中哪些地方偏浅、排序出加深后回报最大的位置、写出评审报告,并在任何人动手实现之前,至少设计两遍替换接口。目标有三点:调用方通过极小的表面完成很多事;一次变更局限在一个模块内;测试走的是与调用方相同的接口。

何时使用

  • 设计新模块,希望在调用方增多之前把接口定对。
  • 被要求「改进这个代码库的架构」,需要找出并排序加深机会。
  • 一条业务规则改动总是牵动五个文件。
  • 测试脆弱,因为它们越过接口直接触碰内部实现。
  • 存在只转发调用的层:service 调 repository,repository 再调 client,层层不添加任何东西。
  • 需要在同一模块的多个接口提案之间做选择。

输入

  • 代码:用于扫描的路径,或用于设计任务的模块及其调用方。
  • 变更历史(如 git log),用于给热点加权。
  • 项目的术语表和已记录决策,以尊重既有命名与历史选择。
  • 设计任务还需:模块必须承担的职责及其依赖。
  • 约束:公共 API 稳定性、调用方数量、当前测试覆盖率。

工作流程

  1. 架构评审(推荐):先确定观察范围(需求方指定区域,或近六个月变更最频繁的路径),阅读术语表与决策记录;在仓库根目录运行分析器(python3 engineering/deep-module-design/scripts/module_depth.py --path . --churn churn.json --format json > depth.json);逐个阅读被标记模块及其调用方,应用「删除测试」——删掉它会让复杂度集中还是扩散?丢弃可接受的形态(真实接缝处的适配器、类型定义、框架处理器);对幸存者按变更频率、痛点证据、局部性收益、测试收益、迁移风险 1–3 打分,保留前 3–5 个;按模板写报告,最后给出一个首要建议并询问先探索哪个候选。
  2. 审问选定的候选:命名模块将拥有的唯一概念(若名字需要「和」,就拆分);列出调用方及最常见调用方的需求;按进程内、本地替身、远程自有、第三方对依赖分类;把接缝放在行为变化处并命名两个适配器;决定调用方必须区分的错误模式,其余在接缝处翻译;把新术语记入术语表。
  3. 设计两遍接口并比较:在不同约束下(最小表面、常见调用方优先、灵活、基于端口)写出至少两套设计,列出入口点、配置旋钮、隐藏内容、留给调用方的部分、常见场景调用次数、带适配器的接缝及常见调用方代码;编码为 JSON 后运行 interface_compare.py 比较并修正违规;推荐一套并说明理由,差距不足一分时提议混合方案。
  4. 不破坏调用方地迁移:先在新接口上按常见调用方场景写测试,在其后构建深模块并内部复用旧代码,逐个迁移调用方并保持构建通过,删除被吸收的浅模块及固定其内部实现的测试,再次运行 module_depth.py 确认候选不再出现在标记列表中。

脚本与默认阈值

  • module_depth.py:统计各模块入口点、接口成本、代码行数、深度、转发函数、长参数列表和私有名导入,按 --churn 加权排序机会;退出码 0 无标记,1 发现浅/转发/泄漏模块,2 输入错误。
  • interface_compare.py:按接口成本、深度、调用方负担为候选接口打分,强制检查职责归属、双适配器接缝与设计差异性,并推荐一套;退出码 0 全部有效,1 规则违规,2 输入错误。
  • 两个脚本均支持 --format text|json;module_depth.py 支持 --path 分析真实代码或 --input 读取 {"files": {name: source}, "churn": {name: count}} 形式的 JSON,默认跳过测试文件,除非 --include-tests。
  • 默认阈值:--shallow-below 4.0(每个接口单元少于 4 行代码且入口点 3 个以上视为浅);--deep-above 8.0(8 行以上报告为深);--pass-ratio 0.5(一半以上函数为转发且至少两个,标记为转发层);--max-params 5(超过即标记为泄漏入口点)。接口成本把每个入口点计为 1 加其参数个数。比率只是指针不是判决,报告前需阅读代码。

反模式

  • 仅为可测试性而抽取:把函数拆成许多微小纯函数,但缺陷出在组合方式上。应通过调用方使用的接口测试,辅助函数保持私有。
  • 转发栈:controller → service → manager → repository,其中三层原样转发参数。应对每层做删除测试,合并到拥有行为的模块中。
  • 假想接缝:为一个只有单一实现、也没有测试替身的依赖引入接口和工厂。应在存在第二个适配器(通常是测试需要的内存替身)时再加接缝。
  • 只设计一次:为众多调用方依赖于其上的模块直接交付第一个想到的接口。应至少写两套设计并比较。
  • 在新接口上叠加旧测试:新接口有测试后仍保留所有固定内部实现的旧测试。覆盖到位后应删除旧测试。

适用范围与限制

范围内:单个代码库内的模块级设计(接口、深度、信息隐藏、接缝、适配器、可测试性);排序加深机会并产出书面报告的代码库评审;比较同一模块的两套以上接口设计并推荐一套;从浅模块迁移到深模块的步骤(含测试替换)。

范围外:系统级架构——服务边界、数据存储、扩展性、部署拓扑;机械重构执行与代码格式化;维护项目术语表和决策记录本身(本技能只读取并建议补充);分析器支持的语言仅限 Python 和 JS/TS(原则适用于任何语言)。

重要注意:JS/TS 分析基于模式而非解析器,特殊导出风格、重载和装饰器可能被误计;Python 分析使用标准 ast 模块,语法层面是精确的。每接口单元行数只是深度的代理指标,适配器、类型模块和框架处理器常被标记但其实合理,报告前需阅读。interface_compare.py 只对你描述的内容打分,描述得乐观得分就乐观,用法示例是诚实的检验。