设计接口
基于《软件设计哲学》中的“设计两次”原则:你的第一个想法不太可能是最好的。生成多个根本不同的设计,然后进行比较。
工作流程
1. 收集需求
在设计之前,请先理解:
- 这个模块要解决什么问题?
- 调用者是谁?(其他模块、外部用户、测试)
- 关键操作有哪些?
- 有任何约束吗?(性能、兼容性、现有模式)
- 哪些应该隐藏在内部,哪些应该暴露?
问:“这个模块需要做什么?谁会使用它?”
2. 生成设计(并行子代理)
使用 Task 工具同时派生出 3 个以上的子代理。每个子代理必须生成一种根本不同的方法。
每个子代理的提示模板:
为以下模块设计接口:[模块描述]
需求:[收集的需求]
此设计的约束条件:[为每个代理分配不同的约束条件]
- 代理 1:“最小化方法数量 - 目标最多 1-3 个方法”
- 代理 2:“最大化灵活性 - 支持多种用例”
- 代理 3:“针对最常见情况进行优化”
- 代理 4:“从 [特定范式/库] 中汲取灵感”
输出格式:
1. 接口签名(类型/方法)
2. 使用示例(调用者如何使用)
3. 此设计内部隐藏了什么
4. 这种方法的权衡
3. 展示设计
展示每个设计,包括:
- 接口签名 - 类型、方法、参数
- 使用示例 - 调用者在实际中如何使用
- 隐藏的内容 - 维持内部的复杂性
按顺序展示设计,以便用户在比较之前能够吸收每个方法。
4. 比较设计
在展示所有设计之后,从以下方面进行比较:
- 接口简洁性:方法更少、参数更简单
- 通用与专用:灵活性 vs 专注
- 实现效率:形态是否允许高效内部实现?
- 深度:小接口隐藏大量复杂性(好) vs 大接口但实现单薄(差)
- 正确使用的容易程度 vs 误用的风险
用文字而非表格讨论权衡。重点标出设计之间最大的分歧点。
5. 综合
通常,最佳设计来自多个选项见解的结合。询问:
- “哪个设计最适合你的主要用例?”
- “是否有其他设计中的元素值得纳入?”
评估标准
来自《软件设计哲学》:
接口简洁性:方法越少、参数越简单 = 更容易学习和正确使用。
通用性:无需修改即可处理未来用例。但需警惕过度泛化。
实现效率:接口形态是否允许高效实现?还是导致内部实现笨拙?
深度:小接口隐藏大量复杂性 = 深模块(好)。大接口但实现单薄 = 浅模块(避免)。
反模式
- 不要允许子代理产生相似的设计 - 强制实现根本差异
- 不要跳过比较 - 价值在于对比
- 不要实现 - 这纯粹是接口形态设计
- 不要根据实现工作量来评估