SuperAPI AI 工具集

codebase-design

设计与创作

查看项目

更新于 10-16 06:23

技能介绍

用途:为模块设计提供统一术语与原则,目标是让调用方获得 leverage、维护者获得 locality、所有人获得可测试性。适用于正在设计或重构代码时。

核心概念:Module 指任何具有接口与实现的东西,尺度不限(函数、类、包或跨层切片);Interface 指调用方正确使用模块所需知道的一切,包括类型签名、不变量、顺序约束、错误模式、必要配置与性能特征;Implementation 指模块内部代码;Depth 指接口上的 leverage,即调用方或测试每学习一单位接口能行使多少行为;Seam 指无需修改该处即可改变行为的位置,即接口所在之处;Adapter 指在 seam 上满足接口的具体物;Leverage 是调用方从 depth 获得的收益;Locality 是维护者从 depth 获得的收益。

深与浅:深模块 = 小接口 + 大量实现;浅模块 = 大接口 + 薄实现,应避免。设计接口时可自问:能否减少方法数、简化参数、把更多复杂度藏到内部。

原则:depth 是接口属性而非实现属性;删除测试——想象删除该模块,若复杂度消失则是直通,若复杂度在 N 个调用方重现则它履行了职责;接口即测试面,调用方与测试穿过同一 seam;一个 adapter 意味着假设的 seam,两个 adapter 才意味着真实的 seam,除非确有变化否则不要引入 seam。

可测试性:接受依赖而非自行创建;返回结果而非产生副作用;保持小接口,方法越少测试越少,参数越少测试搭建越简单。

关系:一个 Module 恰好有一个 Interface;Depth 是 Module 相对其 Interface 的属性;Seam 是 Interface 所在之处;Adapter 坐在 Seam 上并满足 Interface;Depth 为调用方产生 Leverage,为维护者产生 Locality。

被拒绝的框架:不把 depth 定义为实现行数与接口行数之比;不把 interface 窄化为 TypeScript 关键字或类的公开方法;不用 boundary 一词,改说 seam 或 interface。

深入:对依赖簇做 deepening 见 DEEPENING.md;并行探索多种替代接口设计见 DESIGN-IT-TWICE.md。具体安装命令与平台支持暂未提供。