Question

显然，API在过去几年中已经爆炸式增长，但是在使用它们时，其中许多似乎设计得很差......我有机会设计一个API，但我认为合适，但我希望它是对于访问它的人来说很容易使用。当然，保持尽可能简单是一个很大的帮助，但人们遇到的问题是什么？是否应该不惜一切代价避免或不惜一切代价实施？

Answer 1

查看此技术演讲“How to Design a Good API and Why it Matters”。涵盖了一些重要的观点，它与语言无关。

上述演示文稿的幻灯片可用here。

一些真正让我产生共鸣的观点：

如果您编程，那么您就是API设计师
- 好的代码是模块化的 - 每个模块都有一个API
难以滥用
在发布前编写多个插件
易于阅读
代码应该像散文一样阅读

对于优秀API的优秀示例，我建议您查看这些API（这是一个社区维基，所以请随意添加）：

要将好的API与crAPI进行对比，请参阅从文件中读取所有行并将其打印出来的常见示例。（爪哇）：

BufferedReader reader = new BufferedReader(new FileReader("filePath"));
String line = null;
while ((line = reader.readLine()) != null) {
    System.out.println(line);
}

我已经在很多场合用Java完成了文件IO，我仍然必须每次都查找如何进行文件IO，这是一种简洁的做事方式，真实。

vs（Ruby）

file = File.open("filePath", "r");
puts file.readlines

来自Javascript的另一个例子。从数组中的特定位置插入和删除元素是您认为常见的任务。

以下是您可以这样做的方法：

// insert element at index
someArray.splice(index, 0, element);
// remove element at index
someArray.splice(index, 1);

现在，设计师在代码可重用性方面做了很棒的工作真是太棒了，但每次我需要这样做时我都无法打开w3schools.com。因此，在我的所有项目中，这些简单的包装器都被包含在Array的核心扩展中：

Array.prototype.insertAt = function(element, index) {
    this.splice(index, 0, element);
}

Array.prototype.removeAt = function(index) {
    this.splice(index, 1);
}

注意：这不是关于更短的代码，而是更简单，更容易记忆，可读和一致的代码。

另请参阅此相关问题 - How do you define a good or bad API?

Answer 2

要创建出色的API，我认为将它与一个或多个真实应用程序一起开发至关重要。这样做可以让您测试API完全和优雅地解决常见问题。

Answer 3

我建议您参考 Framework Design Guidelines。

alt text http://davesbox.com/images/books/FrameworkDesignGuidelines2ndEditionLarge.jpg

Answer 4

首先编写客户端代码。请您的同行编写将使用您的API的客户端代码，并从客户端代码中发展您的设计。

如果您正在编写Math api，请让您的同行编写客户端代码，就好像他们正在使用它一样。这将为您提供一些好主意。

Answer 5

尽管这个问题非常主观，但要记住的主要事情是保持API的设计更容易实现（以简单的方式编写大量的代码）并且很难做到这一点。原本不是为了做。

为了给你一个非常简单的例子，让我们假设你在C＃中编写一个API，并且你有一个返回项集合的方法。你应该返回哪种类型？在这种情况下，您可以询问以下问题来帮助您做出决定：我希望我的API消费者更改集合（添加或删除项目）？如果你的答案不是，你应该返回一个项目的ReadOnlyCollection，否则你应该返回一个项目列表。

继续询问这些问题，以帮助您更好地设计API。始终牢记您最初为API设定的目标。试图扩大是许多API成为弗兰克斯坦背后的一个非常常见的原因。

正如另一位用户在回答开发API以及真实系统时总是最好的方法。

Answer 6

也许您可以首先列出为什么说“的原因，但在使用它们时，其中许多设计似乎设计得很差”。

Answer 7

扩展Anurag的帖子，这里列出了在设计/实现API时应该记住的一些注意事项

https://github.com/srijanlabs/docs/wiki/API-Guidelines

它的灵感来自Joshua Bloch的精彩演讲。我通常在API设计的初始阶段保持方便。该文件是以清单的方式设计的，请务必遵循“如何使用此文件？”在顶部给出。

设计一个可靠的API，如何？

7 个答案: