SuperAPI AI 工具集

codebase-design-plus

编程与开发

查看项目

更新于 10-23 16:18

技能介绍

用途

Codebase Design Plus 是一套用于在 PHP/Laravel 代码库中设计或重构代码时使用的共享词汇与设计原则。它的核心目标是设计“深模块”:在小型接口背后隐藏大量行为,把接口放在干净的接缝上,并让调用方和测试都通过同一个接口来使用模块。其宣称的收益是:为调用方带来杠杆(leverage),为维护者带来局部性(locality),为所有人带来可测试性。

主要能力

该技能提供了一套精确的术语表,并要求在讨论中严格使用这些词,不要用“component”“service”“API”“boundary”替代:

  • Module(模块):任何具有接口和实现的东西,刻意与规模无关,可以是函数、类、Laravel action、包或跨层切片。避免使用 unit、component、service。
  • Interface(接口):调用方正确使用模块所需知道的一切,包括方法签名、不变量、顺序约束、错误模式、必需配置和性能特征。避免使用 API、signature(过于狭窄)。
  • Implementation(实现):模块内部的代码体。与 Adapter 区分:一个东西可以是小适配器配大实现(如 Eloquent 支持的 repository),也可以是大适配器配小实现(如内存 fake)。当话题是接缝时用“adapter”,否则用“implementation”。
  • Depth(深度):接口层面的杠杆,即调用方或测试每学习一单位接口所能行使的行为量。大量行为位于小接口之后即为深,接口几乎和实现一样复杂即为浅。
  • Seam(接缝,Michael Feathers):可以在不编辑该处的情况下改变行为的地方,即模块接口所在的位置。接缝放在哪里是独立的设计决策。避免使用 boundary(与 DDD 的限界上下文混淆)。
  • Adapter(适配器):在接缝处满足接口的具体事物,描述角色而非实质。
  • Leverage(杠杆):调用方从深度中获得的东西,一份实现回报于 N 个调用点和 M 个测试。
  • Locality(局部性):维护者从深度中获得的东西,变更、缺陷、知识和验证集中在一处。

该技能还提供深模块与浅模块的对比图示、设计接口时的自问清单(能否减少方法数量、简化参数、隐藏更多复杂度),以及若干原则:深度是接口的属性而非实现的属性;删除测试(想象删除该模块,若复杂度消失则是直通,若复杂度在 N 个调用方处重现则它在创造价值);接口即测试面;一个适配器意味着假设性接缝,两个适配器才意味着真实接缝。

使用方式

该技能以共享词汇和原则的形式使用,适用于任何正在设计或重构代码的场景。它包含 Laravel 映射,说明这些概念在 Laravel 代码库中的落点:容器是接缝机制(PHP 接口加服务提供者绑定),但应先应用两适配器规则;框架 fake(Storage::fake()、Queue::fake()、Mail::fake()、Http::fake())是框架自有接缝的适配器,优先于手写端口;Eloquent 模型是宽共享接口,深度通常位于其上方(如 action 或 service 类);控制器、命令、任务、Livewire/Filament 组件是入口适配器,若其中积累真实逻辑则是深化候选。

在可测试性方面,它建议:接受依赖而非创建依赖(构造函数注入);返回结果而非产生副作用;缩小表面积(更少方法、更少参数)。

该技能还提到可进一步阅读的参考文件:references/deepening.md(给定依赖深化集群)和 references/design-it-twice.md(用并行子代理以多种截然不同的方式设计接口再比较)。

适用场景

适用于在 PHP/Laravel 代码库中设计或改进类或模块的接口、寻找接缝、重构代码、提升可测试性等场景。

限制

该技能明确拒绝若干框架表述:不把深度视为实现行数与接口行数的比率(Ousterhout),因为那会奖励填充实现;不把“接口”窄化为 PHP interface 关键字或类的公共方法;不使用“boundary”一词。关于该技能的安装方式、收费、价格、平台支持等信息,资料中暂未提供。