SuperAPI AI 工具集

codebase-design

编程与开发

查看项目

更新于 11-08 20:55

技能介绍

该技能围绕“深模块”设计提供一套共享词汇和设计原则,目标是让调用方获得杠杆、让维护者获得局部性、让所有人获得可测试性。资料要求严格使用其术语,不要用 component、service、API、boundary 等词替代。

用途与术语 模块指任何具有接口和实现的单位,刻意不限定规模,可以是函数、类、包或跨层切片。接口指调用方正确使用模块所需知道的一切,不仅是类型签名,还包括不变量、顺序约束、错误模式、必需配置和性能特征;资料明确不建议用 API 或 signature,因为二者过窄。实现指模块内部内容。深度指接口处的杠杆:调用方或测试每学习一单位接口能触发多少行为;深表示小接口背后有大量行为,浅表示接口几乎和实现一样复杂。接缝(Feathers)指无需在该处编辑即可改变行为的位置,也是模块接口所在处;把接缝放在哪里是独立决策,资料建议避免用 boundary,因其与 DDD 的限界上下文混淆。适配器指在接缝处满足接口的具体事物,描述其承担的角色而非内部内容。杠杆指调用方从深度获得的好处:一份实现回馈 N 个调用点和 M 个测试。局部性指维护者从深度获得的好处:变更、缺陷和验证集中在一处,修一次即处处修复。

主要原则 深度是接口的属性,不是实现的属性;深模块内部可由小的可替换部件组成,但这些部件不属于其接口。模块可以有内部接缝供自身测试使用,同时在接口处保留外部接缝。删除测试:想象删除该模块,若复杂度消失,它只是直通;若复杂度在 N 个调用方处重新出现,它就在发挥价值。接口即测试面:调用方和测试跨越同一接缝,若需要绕过接口测试,说明模块形状不对。一个适配器只是假想接缝,两个适配器才是真实接缝;除非确实有东西在接缝两侧变化,否则不要引入接缝。塑造接口时问:能否减少方法数量、简化参数、把更多复杂度藏在内部。

面向可测试性 接受依赖,不要构造依赖:processOrder(order, gateway) 可测试,而在内部 new 一个 StripeGateway 的 processOrder 不可测试。返回结果,不要修改:calculateDiscount(cart): Discount 可测试,applyDiscount(cart): void 不可测试。保持小接口面:方法越少测试越少,参数越少搭建越简单。

被否定的框架 资料否定以实现行数与接口行数之比来定义深度(Ousterhout),因为这会奖励填充实现;应使用“深度即杠杆”。也否定把接口理解为语言关键字或类公开方法,因为这过窄;此处的接口是调用方必须知道的每一件事。

搭配使用 审计既有模块时可与 scrutinize 搭配;接口形态尚未确定时可与 brainstorming 搭配。资料未提供安装命令、具体操作步骤、平台支持、收费或效果数据,这些暂未提供。