在 API 中公开多少底层内容？答案

【问题标题】：How much low-level stuff to expose in an API?在 API 中公开多少底层内容？
【发布时间】：2010-09-30 16:05:58
【问题描述】：

在设计通用库的公共 API 时，应该公开多少内部使用的低级内容？一方面，用户不应该过于依赖实现细节，过多的低级函数/类可能会使 API 混乱。因此，下意识的反应可能是“无”。另一方面，一些低级功能可能对人们有用，并且公开更多功能可以防止抽象反转（在高级构造之上重新实现低级构造）。

此外，公开更多低级细节可以提供性能捷径。例如，假设您有一个查找数组中位数的函数。最不意外的原则是你应该复制数组，这样你的 API 的用户就不必关心它的实现涉及重新排序元素的副作用。在这种情况下，您是否应该注意 medium() 会消耗内存分配并提供另一个绕过分配但会任意重新排序用户输入的函数？

对于要公开多少此类细节有哪些一般准则？

【问题讨论】：

【解决方案1】：

尽可能少。

您公开的细节越多，更改就越有可能破坏消费者。

【讨论】：

【解决方案2】：

您的 API 不应允许调用者通过破坏内部状态（例如重新排序集合等）来“破坏”任何内容。为了解决这个问题，你暴露的接口应该只在必要时才被读取。

关于复杂性，我更倾向于简单、基本的方法。我非常努力地不过度设计任何我认为未来需要的东西。

写出今天的要求（也许明天的），但不能超出。您可以在未来随时扩展。丢弃无法再维护的东西要困难得多。

【讨论】：

【解决方案3】：

unix 的做法是提供机制，而不是策略。只需提供正确的工具来做事（例如，一把刀），但尽量不要预测它们将如何使用（剥苹果或削铅笔）。

【讨论】：

【解决方案4】：

我听说过一种表达方式：公开是什么，而不是如何。

我们的目标是提供一个有用且丰富的库供客户使用，而不会使他们依赖于库的内部结构。您希望能够在不破坏调用者的情况下更改内部结构（正如其他人已经指出的那样）。

编写好的 API 涉及到一定程度的巧妙边缘政策。

【讨论】：