Question

设计API需要遵循哪些最佳做法和模式？
如何实现隐藏最佳方式（C ++ / Java）的实现？
设计通用的API？
任何参考书籍/链接，向初学者提供简洁的例子？

Answer 1

我不确定我对你的所有个人问题都有一个很好的答案，但我认为我对第一个问题有一个很好的答案。

尝试在编写之前使用它。我的意思是，为代码编写单元测试，就像它确实存在一样。在编写一行API之前，先编写一些将使用API的代码。当您尝试使用它时，您将很快看到在您的设计中哪些有效，哪些无效，您将快速更改它以匹配其实际用途，因为您还没有写任何实际代码。

如果您没有将任何内容用于编码，那么改变某些内容永远不会有任何摩擦，但是当您这样做时，通常会有一些不情愿的做法。

Answer 2

这可能对你有用。

The Little Manual of API Design (wayback machine)

The Little Manual of API Design (original; dead)

Answer 3

Q4：

How to Design a Good API & Why it Matters - 精彩视频，值得花时间观看。

在我看来，Josh Bloch在编写优秀的API时有最好的想法，他可以用非常容易理解的方式解释它们。上面的视频将为您解决Q1-3。

Answer 4

我建议您查看 How to Design a Good API & Why it Matters

编写良好的API可以很棒   写给组织的资产   它和所有使用它的人。鉴于   良好的API设计的重要性，   令人惊讶的是，写得很少   就此主题而言。在这次谈话中（记录下来   在Javapolis），Java库设计师   Joshua Bloch教授如何设计   良好的API，有许多例子   好的和坏的API看起来像。

http://www.infoq.com/presentations/effective-api-design

您也可以阅读本书Practical API Design: Confessions of a Java™ Framework Architect。我没有阅读它所以我不确定它的内容是否对你有用。

要检查的另一个资源：How To Design a (module) API

Answer 5

关于第3点（通用API设计），我有一个提示：

开始将您的API基于特定用例;使您的设计具体而不是通用 - 然后通用化如果您发现API可以重复使用。

在过去，我已经看到API被重构到它们如此通用的程度，以至于其中一个方法参数是“参数”对象，或者更糟糕的是，一个DOM树对应于一个任意的XML文件; e.g。

void processData(Parameters reportParams);

采用这种超级通用方法：

错误不太可能在编译时被发现或者通过观察代码而被发现，并且会在运行时出现，这使得它们很难被追踪。
代码的可读性较差，自我记录较少，难以使用或实施。
API实现将变得丑陋，因为它需要将此“参数”对象分解为特定的用例并对其进行操作。

Answer 6

Apress - 实用API设计 - Java架构师的自白 - 2008

实用主义 - 面向接口的设计 - 2006

Answer 7

Josh Bloch阅读Effective Java。这本书非常适合任何Java程序员，但也解决了围绕创建有用API的许多问题。

Answer 8

结帐podcast

它谈到了关于api设计的一些非常好的概念。

Answer 9

您可以实施以下准则：

1）使用已建立或已知的方法，例如：

createPatientRecord();
createPatientAppointment();
createPatientCheckup();

2）返回值：

如果有则抛出异常
如果未找到对象，则返回null
如果有多个对象，则返回空列表，而不是null

3）一致的参数排序/顺序

recallPatientRecord(long patientId, long hospitalId);
recallPatientRecord(long patientId);
recallPatientRecord(long patientId, long hospitalId, int disciplineCode);

Answer 10

这个问题几乎无法回答。它甚至可能不是Stack Overflow的正确问题（人A：我如何解决具体问题？B人：这是这个明确的答案）。

1.设计API需要遵循的最佳实践和模式

我们在谈论什么编程语言？我们在谈论哪些问题领域？因为适用于一种编程语言/问题域的内容在另一种编程语言/问题域中可能效果不佳。

2.如何实现隐藏最佳方式的实现（C ++ / Java）

这个问题有一个答案，这里写的时间太长了。事实上，网站引用是不够的。有许多网站和书籍，当它们组合在一起时，将回答这个问题。哦，我只是在谈论C ++。为Java重复整个过程。对于C＃，对于Python，对于....（等等）

4.任何参考书/链接，向初学者提供简洁的例子

选择一种编程语言。然后我可以提供书籍和链接的参考。弗雷德布鲁克斯写道，没有银弹。从编程语言到编程语言，你没有单一的心态。在一种编程语言中制作好API的原因在于另一种编程语言中的设计错误。相信我，通过尝试在这些语言中应用C ++，Delphi和Java习语，我学到了很难的原因。它会导致糟糕的API和错误的代码。

在设计API方面也存在竞争学派。而且，不幸的是，现实是没有人是100％正确的。事实上，当您了解多个思想流派并知道何时将特定的思想流派应用于特定问题时，您将成为一名出色的API设计师。

设计更好的API？

10 个答案: