什么时候API设计过度？

我鄙视使用过度工程化的API，这些API不能使简单的事情变得简单。尽管如此，我正在为一个开源库设计一个API，我开始觉得自己陷入了过度工程化的陷阱。我真的不能确定，因为，当然，我写了这该死的东西，所以它的工作原理对我来说比任何人都清楚。从开发人员的角度来看，哪些警告标志表明您的API可能设计过度？

两个（相关的）问题会立即浮现在脑海中：

• 有没有可以用多种方式完成的事情
• API上是否有可以用API其余部分表示的方法/属性

更难回答，这本身并不是一个过度工程的迹象，但肯定是一个API还没有那么简单的迹象：

• 您是否可以引入其他方法/属性，从而可以删除比您引入的更多的方法/属性（基于其他两个问题）

“从开发人员的角度来看，哪些警告标志表明您的API可能设计过度？”

没有用例

如果您不能运行简单的“to do this”场景，那么您在设计有用的API时就没有考虑到特定的用例

您的文档应该是那些用例

---

不直接涉及用例的特性可能过于工程化了。

在审查文档和示例时，讨论API自身的措辞的百分比与讨论其应用于可信用例的措辞的百分比相比。

正如S.Lott所说，用例。它们将决定您的API应该做什么。如果您将API设计为完成一个非常明确、具体的目标，那么最终很可能会得到一个易于使用和理解的API或API组件

设计API应该像设计用户界面一样。大多数UI概念都可以通过API实现，例如，KISS原则，甚至改善

---

我会链接到那些UI概念，但我是新用户，所以他们不会让我发布超过1个超链接。这里有一个很好的例子：StackOverflow，在我们发布之前让我们知道；）

你应该看看约书亚·布洛赫的谷歌科技演讲。。。他涵盖了很多这方面的内容。

当它非常聪明以至于没有人能理解它时。

当普通api调用的堆栈跟踪要求您滚动屏幕以查看整个内容时。

当您有一个包含大量函数的大型api时，您会开始担心，如果仔细检查，结果证明是简单操作的组合。具有高比例组合机制和原语的API通常是一种好的设计

---

（API设计与语言设计非常相似，在这里我基本上支持Scheme理念，而不是在API中堆积更多的例程，简化它并包括使附加例程变得不必要的组合机制。）

我发现一个非常有用的技巧，它在过去对我有帮助，那就是以前写文档，在编写代码期间和之后

当设计供他人使用的API时，我通常在编写代码之前记录设计。如果我过度设计了设计，设计规范通常充满了冲突和胡说八道

在编码过程中，我通常会删除类定义和函数体，并开始为它们编写doxygen注释。在评论中，我将介绍用例、示例代码和接口假设。在这个阶段，在编写太多实际代码之前，类接口通常要经过多次重新设计。我知道当示例代码很难编写时，我已经过度工程化了，我很难解释接口。当你们试图向人们解释如何使用你们的API时，很多糟糕的设计思想被暴露出来并消除了

编码后，我用从单元测试复制的真实编译和测试代码替换注释中的示例代码，并进一步记录接口的行为。过度工程的另一个迹象是，我的单元测试无法跟上接口的变化，因为有太多的活动部件和太多的方法来做同样的事情，单元测试以指数比例增长。

使用API时： （1） 比仅仅使用底层技术更迟钝、更复杂、效率更低、更不可预测，以及

---

（2） 在安全性、可扩展性或跨平台自由度方面没有显著优势。

根据我的经验，你可以知道整个项目何时会被搁置数月，等待API完成。

+1-与我的评论相同，但速度更快。但这将排除人性化的界面（如Fowler所述）。人道！=过度设计。+1，也将链接到它-幻灯片也可用：在这里，您可以一起查看视频和幻灯片，嵌入到相同的浏览器视图中：坦率地说，布洛赫构建的许多API都是过度设计的。尽管如此，这段视频还是有一些好的要点，好的要点，但很难阅读。一些段落分隔符可能会有所帮助。用段落分隔符重新格式化。谢谢。这些似乎是相关的：