SuperAPI AI 工具集

codebase-design

设计与创作

查看项目

更新于 10-16 07:24

技能介绍

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

核心术语:模块(Module)指任何有接口和实现的东西,刻意与规模无关,可为函数、类、包或跨层切片;接口(Interface)指调用方正确使用模块所需知道的一切,包括类型签名、不变量、顺序约束、错误模式、必需配置和性能特征;实现(Implementation)指模块内部代码;深度(Depth)指接口处的杠杆,即调用方或测试每学习一单位接口能触发的行为量;接缝(Seam)指无需编辑该处即可改变行为的位置,也是模块接口所在之处;适配器(Adapter)指在接缝处满足接口的具体事物。

主要原则:深度是接口的属性而非实现的属性;删除测试——若删除模块后复杂度消失则为直通,若复杂度在 N 个调用方重现则值得保留;接口即测试面,调用方与测试跨越同一接缝;一个适配器意味着假设接缝,两个适配器才是真实接缝,不要引入没有实际变化的接缝。

可测试性设计:接受依赖而非创建依赖,例如 function processOrder(order, paymentGateway) {} 可测试,而内部 new StripeGateway() 难以测试;返回结果而非产生副作用,例如 function calculateDiscount(cart): Discount {} 可测试,而直接修改 cart.total 难以测试;保持小表面积,方法越少测试越少,参数越少测试设置越简单。

关系:一个模块恰好有一个接口;深度是模块相对其接口的属性;接缝是模块接口所在之处;适配器位于接缝并满足接口;深度为调用方产生杠杆,为维护者产生局部性。

已拒绝的框架:不以实现行数与接口行数之比定义深度;不将接口窄化为 TypeScript 的 interface 关键字或类的公开方法;不用“边界”一词,因其与 DDD 的限界上下文混淆。

深入资料:给定依赖深化集群见 DEEPENING.md;探索替代接口见 DESIGN-IT-TWICE.md,可并行子代理以多种截然不同方式设计接口,再按深度、局部性和接缝位置比较。

限制:资料未提供具体安装命令、平台支持、收费或价格信息。