优秀的API有什么共同点？[关闭]

出色的API使它们变得如此出色的原因是什么？我认为坚持“做一件事情，做好一件事情”的口号是一个好兆头，良好地映射到问题域很重要，但是出色的API有什么共同点？

您必须要小心，避免仅仅为了您的API而添加新词汇。我最喜欢的API通过我已经了解的词汇向我解释了一些事情。遵循这些原则：

不要在构建的基础之上添加太多抽象。把事情简单化。

我已经不得不考虑大约六个抽象层。不要让我考虑额外的层。不要给我太多学习的新知识，这些新事物不会为我的最终目标增加价值。例如，避免使用自己的特殊文件类，而该类的工作方式不同于语言的文件类型，只会导致您认为自己的方式比公认的方式更好。不管是好是坏，都至少在您的界面中使用公认的方法。

坚持具体思想

例如，不要试图掩盖MVC框架的“模型”部分是数据库的前端这一事实。利用围绕“数据库”的众所周知的词汇。我知道什么是外键。我知道什么是行和列。用这些术语与我交谈。

不要提取基本知识

类似于处理具体想法。不要掩盖我们正在处理文件或数据库或数据库中的行的事实。我知道这些 如果我要处理的是List这样的容器，那么很有可能需要了解常见操作的算法复杂性。您只需告诉我它的“链接列表”或“数组”，就可以简化很多工作。大量的想法会突然带到您正在做的事情上，这一切都会突然变得有意义。当我已经有了一套丰富而有用的术语来解决问题时，就不要创建自己必须学习的想法。

减少我的词汇量

如果我使用您的API打开任何类型的图像文件，我都不必考虑png，gif和jpg。你帮我做 它是您的核心能力，而不是我的能力。我有些模糊的理解，您可以为我做些魔术。

有用的API具有以下内容：

• 简洁明了的文档。如果我正在寻找如何执行任务的方法，则可以在几分钟内确定API是否具有执行任务的能力。这是通过简短的文本和资源的布局实现的。该文档提供了有关如何使用它的示例，也没有对读者构成任何假设。
• 一个庞大而活跃的社区。当我发现论坛，IRC频道，邮件列表等时，我很激动，活跃的参与者愿意帮助新手。我知道大型项目通常会遇到这种情况，但是仍然需要努力。
• 一致性。当我实际使用 API时，我不希望在调用方法时感到震惊，或者发现该方法X与API其余部分设置的约定完全不同。

出色的API具有出色的文档。

• 做一件事，做得很好。
• 易于使用，难以滥用。
• 易于扩展。
• 有据可查。
• 风格一致。

NetBeans团队的Jaroslav Tulach在“实用的API设计：Java框架架构师的自白”中解决了这个问题。

最简单的有用界面和良好的命名约定。