Question

在设计API时，我可以遵循哪些指南和最佳做法？至少，我知道API应该易于使用且灵活。不幸的是，这些术语可能相当主观，因此我正在寻找一些与良好API设计相关的具体指导原则。

Answer 1

我发现以下值得一看约书亚布洛赫 - How To Design A Good API and Why it Matters

虽然这些例子都是用Java编写的，但你仍然可以画出相似之处。既然你没有提到具体的技术;我假设你不想要利基解决方案。

Answer 2

作为必须消耗大量API的人......

请以一致的方式编写您的API：

API本身内的一致命名。使用动词，名词，关键字完全相同的风格。
与将使用的目标环境一致。如果是.NET，请参阅Microsoft的命名准则。
一致的概念。工厂模式？生成器模式？静态方法？接口？只需选一个，坚持下去。真。规则中没有 small 例外。它会像一个大拇指一样伸出来。超过1例外？您的API越来越业余。

这是另一个：特异性。

我可以实现的基类，如果您选择提供它们，应该具有很少且定义良好的函数来实现。不要告诉我“GetData（）”返回一个“object []”然后期望我实现它，弄清楚为什么我必须将它转换为字符串[]，然后调试为什么它被调用20次。最好有DataPoint [] GetChartData（），string [] GetLabelData（）等，让我选择应该实现哪些。
请注意名称：PostRenderColorWheelModifyHSVBaseHandler。您通常可以将超级特定的事物重构为更通用的名称+参数。
字符串参数是禁忌！使用枚举。我不想使用像
这样的处理程序
PostRenderHandler（“ColorWheel”，“HSV”，someDelegate）;

我更喜欢我可以调查的枚举：

PostRenderHandler(ModuleType.ColorWheel, Options.ColorWheelHSV, someDelegate);

伙计，我可以继续... Josh Bloch家伙的力量 - 精心编写的API真的很棒......糟糕的可能真的很痛苦。

Answer 3

约书亚布洛赫有一个关于这个主题的good presentation。该演示文稿使用Java，但这些想法与语言无关。 Another source (pdf)快速浏览。

Answer 4

还有这本书：框架设计指南：可重用.NET库的约定，惯用语和模式

Answer 5

我认为你的问题在这个数量的空间内无法得到你所提供的信息量。我在google中输入了几个链接'api design'，并在第一页上看到这些链接看起来很不错