设计API的最佳实践和指南

Question

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

Answer 1

我发现以下值得观看Joshua Bloch - 如何设计一个好的API及其重要性

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

Answer 2

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

请以一致的方式编写API:

1. API本身内的一致命名.使用动词,名词,关键字完全相同的风格.

2. 它将与目标环境一致使用.如果是.NET,请参阅Microsoft的命名指南.

3. 一致的概念.工厂模式？生成器模式？静态方法？接口？只需选一个,坚持下去.真.规则中没有一个小例外.它会像一个大拇指一样伸出来.超过1例外？你的API越来越业余了.

这是另一个:特异性.

1. 如果您选择提供基类,我可以实现的基类应该具有很少且定义良好的函数来实现.不要告诉我"GetData()"返回一个"object []"然后期望我实现它,弄清楚为什么我必须将它转换为字符串[],然后调试为什么它被调用20次.最好有DataPoint [] GetChartData(),string [] GetLabelData()等,让我选择应该实现哪些.

2. 请注意名字:PostRenderColorWheelModifyHSVBaseHandler.您通常可以将超级特定的事物重构为更通用的名称+参数.

3. 字符串参数是禁忌!使用枚举.我不想使用Handler之类的

   PostRenderHandler("ColorWheel","HSV",someDelegate);

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

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

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

Answer 3

约书亚布洛赫对这一主题进行了很好的介绍.该演示文稿使用Java,但这些想法与语言无关.另一个来源(pdf)用于快速概述.

Answer 4

这是Microsoft的链接:http: //msdn.microsoft.com/en-us/library/ms229042.aspx

本书还有:框架设计指南:可重用.NET库的约定,成语和模式