SuperAPI AI 工具集

codebase-design

编程与开发

查看项目

更新于 10-16 01:38

技能介绍

用途:在设计与重构代码时提供统一的深模块设计语言与原则,目标是让调用者获得杠杆(leverage)、维护者获得局部性(locality)、所有人获得可测试性。

术语(需严格使用,不替换为 component、service、API、boundary):Module 指任何具有接口与实现的东西,对规模不敏感,可适用于函数、类、包或跨层切片;Interface 指调用者正确使用模块所需知道的一切,包括类型签名、不变量、顺序约束、错误模式、必需配置与性能特征;Implementation 指模块内部代码,与 Adapter 不同;Depth 指接口处的杠杆——调用者或测试每学习一单位接口所能驱动的行为量;Seam 源自 Michael Feathers,指无需就地修改即可改变行为的位置,也是接口所在之处;Adapter 指在接缝处满足接口的具体事物,描述角色而非实质;Leverage 是调用者从深度中获得的收益;Locality 是维护者从深度中获得的收益,变更、缺陷、知识与验证集中一处。

深与浅:深模块=小接口+大量实现(方法少、参数简单、隐藏复杂逻辑);浅模块=大接口+少量实现(方法多、参数复杂、仅做透传)。设计接口时可自问:能否减少方法数量、简化参数、隐藏更多复杂度。

原则:深度是接口属性而非实现属性,深模块内部可由小的、可模拟、可替换的部件组成,但它们不属于接口;模块可同时有内部接缝(实现私有,供自身测试)与接口处的外部接缝。删除测试:设想删除该模块,若复杂度消失说明它只是透传,若复杂度在 N 个调用者处重现说明它值得存在。接口即测试面,调用者与测试跨越同一接缝。一个适配器意味着假想接缝,两个适配器才意味着真实接缝,除非确有变化否则不要引入接缝。

可测试性设计:接受依赖而非创建依赖;返回结果而非产生副作用;缩小接口面积,方法越少所需测试越少,参数越少测试搭建越简单。

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

被拒斥的框架:不采用以实现行数与接口行数之比定义深度(Ousterhout),因其会奖励填充实现;Interface 不限于 TypeScript 的 interface 关键字或类的公开方法,而是包含调用者必须知道的一切;不使用“boundary”一词(与 DDD 的限界上下文混淆),应说 seam 或 interface。

深入:关于在给定依赖下深化一组模块,见 DEEPENING.md(依赖类别、接缝纪律、替换而非分层测试);关于探索替代接口,见 INTERFACE-DESIGN.md(并行子代理以多种截然不同方式设计接口,再按深度、局部性与接缝位置比较)。资料未提供安装命令、收费、价格与支持平台信息。