Codebase design
Skill 15102045545/skills-cn/skills/engineering/codebase-design
用于设计深模块的共享词汇。用户希望设计或改进模块接口、寻找深化机会、决定接缝位置、提高代码的可测试性或 AI 可导航性,或其他技能需要深模块词汇时使用。From its SKILL.md
npx -y skills add 15102045545/skills-cn --skill codebase-designAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
6.3 KB, as published. Nobody here has run it
代码库设计
设计深模块:在清晰的接缝处,以小接口承载大量行为,并可通过该接口进行测试。凡是设计或重构代码,都应使用这套语言和原则。目标是让调用方获得杠杆效应,让维护者获得局部性,并让所有人都获得可测试性。
术语表
必须准确使用这些术语——不得替换为“component”“service”“API”或“boundary”。这套方法的核心正是保持语言一致。
模块(Module)——任何具有接口和实现的事物。刻意不限定规模:可以是函数、类、包,也可以是跨层切片。避免使用:unit、component、service。
接口(Interface)——调用方为正确使用模块而必须知道的一切:不仅包括类型签名,还包括不变量、顺序约束、错误模式、必需配置和性能特征。避免使用:API、signature(范围过窄——它们仅指类型层面的表面)。
实现(Implementation)——模块内部的内容,即其代码主体。它不同于适配器(Adapter):一个事物可以是实现很大的小型适配器(Postgres 仓库),也可以是实现很小的大型适配器(内存假对象)。讨论接缝时使用“适配器”,其他情况下使用“实现”。
深度(Depth)——接口处的杠杆效应:调用方(或测试)每学习一个单位的接口,便可运用多少行为。当大量行为位于小接口之后时,模块是深的;当接口几乎与实现一样复杂时,模块是浅的。
接缝(Seam) (Michael Feathers)——无需在某处直接编辑就能改变行为的位置;即模块接口所在的位置。接缝放在哪里本身就是一项设计决策,与接缝之后放什么不同。避免使用:boundary(与 DDD 的限界上下文含义重叠)。
适配器(Adapter)——在接缝处满足接口的具体事物。它描述的是角色(填补哪个位置),而非实质(内部有什么)。
杠杆效应(Leverage)——调用方从深度中获得的收益:每学习一个单位的接口,就能获得更多能力。一份实现可惠及 N 个调用点和 M 项测试。
局部性(Locality)——维护者从深度中获得的收益:变更、缺陷、知识和验证集中在一处,而不是散布于各调用方。修复一次,处处生效。
深与浅
深模块 = 小接口 + 大量实现:
┌─────────────────────┐
│ 小型接口 │ ← 方法少,参数简单
├─────────────────────┤
│ │
│ 大量实现 │ ← 隐藏复杂逻辑
│ │
└─────────────────────┘
浅模块 = 大接口 + 少量实现(应避免):
┌─────────────────────────────────┐
│ 大型接口 │ ← 方法多,参数复杂
├─────────────────────────────────┤
│ 少量实现 │ ← 仅作透传
└─────────────────────────────────┘
设计接口时,问自己:
- 能否减少方法数量?
- 能否简化参数?
- 能否在内部隐藏更多复杂性?
原则
- 深度是接口的属性,而非实现的属性。 深模块内部可以由小型、可模拟、可替换的部件组成——只是这些部件不属于接口。模块既可以有内部接缝(实现私有,供自身测试使用),也可以在接口处有外部接缝。
- 删除测试。 想象一下删除该模块。如果复杂性消失了,它只是透传层;如果复杂性重新出现在 N 个调用方中,说明它确实物有所值。
- 接口就是测试表面。 调用方和测试跨越同一个接缝。如果你想越过接口深入测试,模块的形态很可能有误。
- 一个适配器意味着假想接缝,两个适配器才意味着真实接缝。 除非确实有某些内容会跨接缝变化,否则不要引入接缝。
为可测试性而设计
良好的接口让测试自然而然:
-
接收依赖,不要创建依赖。
// 可测试 function processOrder(order, paymentGateway) {} // 难以测试 function processOrder(order) { const gateway = new StripeGateway(); } -
返回结果,不要产生副作用。
// 可测试 function calculateDiscount(cart): Discount {} // 难以测试 function applyDiscount(cart): void { cart.total -= discount; } -
表面积要小。 方法越少 = 所需测试越少。参数越少 = 测试设置越简单。
关系
- 一个模块恰好有一个接口(它向调用方和测试呈现的表面)。
- 深度是模块的属性,依据其接口衡量。
- 接缝是模块的接口所在之处。
- 适配器位于接缝处,并满足接口。
- 深度为调用方带来杠杆效应,为维护者带来局部性。
不采用的表述方式
- 把深度视为实现行数与接口行数之比(Ousterhout):这会奖励填充实现。我们改用“深度即杠杆效应”。
- 把“接口”理解为 TypeScript 的
interface关键字或类的公共方法:范围过窄——这里的接口包括调用方必须知道的每项事实。 - “边界”:与 DDD 的限界上下文含义重叠。应使用接缝或接口。
继续深入
- 根据依赖深化模块簇——参见 DEEPENING.md:依赖类别、接缝纪律,以及“替换而非叠加”的测试策略。
- 探索备选接口——参见 DESIGN-IT-TWICE.md:启动并行子智能体,以若干种截然不同的方式设计接口,然后比较深度、局部性和接缝位置。