代码之家 › 专栏 › 技术社区 › fmsf

如何定义好的或坏的API?[关闭]

api-design api

fmsf · 技术社区 · 15 年前

背景:

我正在我的大学上一门叫做“软件约束”的课。在第一堂课中,我们学习了如何构建好的API。

对于一个非常糟糕的API函数,一个很好的例子是套接字 public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); 在C中。该函数接收3个套接字列表,并将其销毁,这使得用户必须先克隆所有套接字,然后才能将它们送入 Select() . 它还有一个超时(以微秒为单位),它是一个int,设置服务器可以等待套接字的最长时间。限制为+/-35分钟(因为它是一个int)。

问题:

如何将API定义为 “坏”?
你如何定义 API是“好”吗?

需要考虑的要点:

难以记住的函数名。
难以理解的功能参数。
错误的文档。
所有的东西都是如此相互连接,以至于如果你需要更改一行代码,你实际上需要在其他地方更改数百行代码。
破坏参数的函数。
由于“隐藏”的复杂性,扩展性较差。
用户/dev需要在API周围构建包装器,以便使用它。

14 回复 | 直到 8 年前

104

bwegs 8 年前

在API设计中,我一直认为这个主题演讲非常有用:
How to Design a Good API and Why it Matters - by Joshua Bloch

这是一个摘录,我建议你阅读整个故事/观看视频。

二。一般原则

API应该做一件事并做好它

API应尽可能小,但不能小

实现不应影响API

最小化所有内容的可访问性

名字很重要“api是一种小语言

文件事宜

认真记录

考虑API设计决策的性能后果

API设计决策对性能的影响是真实的和永久的。

API必须与平台和平共存

三、课堂设计

最小化可变性

子类仅在有意义的地方

继承或禁止继承的设计和文件

四、方法设计

不要让客户机做模块能做的任何事情

不要违反最小惊异原则

快速失败-发生错误后尽快报告错误

提供对字符串形式的所有可用数据的编程访问

小心超载

使用适当的参数和返回类型

跨方法使用一致的参数排序

避免长参数列表

避免返回需要特殊处理的值

Quibblesome 15 年前

您不必阅读文档就可以正确使用它。

一个了不起的API的标志。

Barry Kelly 15 年前

许多编码标准和 longer documents 甚至 books (Framework Design Guidelines) 关于这个主题已经写过了,但其中大部分只在一个相当低的水平上有所帮助。

还有一个关于品位的问题。API可能会遵守任何规则手册中的每一条规则,但仍然很糟糕,因为它对各种时尚意识形态的奴性坚持。最近的一个罪魁祸首是模式定向,其中过度使用了单例模式(略多于初始化的全局变量)和工厂模式(一种参数化构造的方法,但通常在不需要时实现)。最近,控制反转(IOC)和相关的小型接口类型数量激增更有可能增加设计的冗余概念复杂性。

对于味觉最好的导师是模仿(阅读大量的代码和API,找出什么有用,什么不管用),经验(犯错并从中学习)和思考(不要仅仅为了自己的目的做一些时髦的事情,在行动之前思考)。

Tim 15 年前

有用-它可以满足尚未满足的需求(或改进现有需求)
很容易解释-对它的基本理解应该很容易掌握
遵循一些问题域或现实世界的对象模型。它使用有意义的结构
正确使用同步和异步调用。(不要为需要时间的事情而阻塞)
良好的默认行为-在可能的情况下允许扩展性和调整,但为简单情况所必需的所有内容提供默认值
样本使用和工作样本应用程序。这可能是最重要的。
优秀的文档
吃自己的狗食(如果适用)
保持它的小或分割,使它不是一个巨大的污染空间。保持功能集的独特性和独立性,如果有依赖关系,则很少。

还有很多,但那是个好的开始

T.E.D. 15 年前

一个好的API允许客户机做他们需要做的几乎所有事情,但不要求他们做很多无意识的繁忙工作。“无意识的忙碌工作”的例子是初始化数据结构字段,按顺序调用多个例程,这些例程之间没有真正的自定义代码,等等。

坏API最可靠的标志是,如果您的客户机都想用自己的助手代码包装它。至少,您的API应该已经提供了帮助器代码。最有可能的是,它应该被设计为提供更高级别的抽象,客户每次都在自己滚动。

Dan Vinton 15 年前

一个好的API有一个接近它描述的语义模型。

例如,用于创建和操作Excel电子表格的API的类如下 Workbook , Sheet 和 Cell ,方法如下 Cell.SetValue(text) 和 Workbook.listSheets() .

jasonco 15 年前

我一直都很喜欢队列中的这篇文章,标题是 API设计事项

http://queue.acm.org/detail.cfm?id=1255422

本专栏还讨论API设计问题:

http://queue.acm.org/detail.cfm?id=1229903

duffymo 15 年前

不好的API是指它的目标读者没有使用的API。

一个好的API是它的目标读者为了它的设计目的而使用的API。

一个伟大的API是指它的目标受众为了它的预期目的而使用的API,以及出于设计者意想不到的原因而使用的非预期受众。

如果亚马逊将其API同时发布为SOAP和REST,而REST版本胜出,这并不意味着底层的SOAP API是坏的。

我想你也会这样。你可以阅读所有你想要的关于设计的文章,并尽你最大的努力,但酸性测试是有用的。花一些时间构建方法,以获得关于什么有效,什么无效的反馈,并准备好根据需要进行重构以使其更好。

dsimcha 15 年前

一个好的API可以使简单的事情变得简单(完成最常见事情的最小样板文件和学习曲线)和复杂的事情成为可能(最大的灵活性,尽可能少的假设)。一个普通的API可以很好地完成其中的一个任务(要么非常简单,但是只有当你尝试做一些非常基本的事情,要么非常强大,但是有一个非常陡峭的学习曲线等等)。一个糟糕的API是一个既不能很好地完成这些任务的API。

Lorin 15 年前

在这个问题上已经有其他几个好的答案了,所以我想我只会加入一些我没有看到提到的链接。

文章

书:

Laserallan 15 年前

我认为一个好的API应该允许自定义IO和内存管理挂钩(如果适用的话)。

一个典型的例子是,您有磁盘上数据的自定义压缩存档格式,而具有较差API的第三方库希望访问磁盘上的数据,并希望得到一个文件的路径,在该文件中可以加载其数据。

此链接有一些优点: http://gamearchitect.net/2008/09/19/good-middleware/

Alan 15 年前

如果API生成错误消息,请确保消息和诊断帮助开发人员找出问题所在。

我的期望是API的调用者传入正确的输入。开发人员是API(而不是最终用户)生成的任何错误消息的使用者,针对开发人员的消息有助于开发人员调试其调用程序。

Filip Ekberg 15 年前

API是 记录不好的时候就不好了 .

API是 当它有良好的文档记录并遵循编码标准时是很好的 .

现在这是两个非常简单也很难遵循的点,这将一个引入到软件体系结构领域。您需要一个优秀的架构师来构建系统,并帮助框架遵循自己的指导方针。

评论代码,写一个解释清楚的 API手册是强制性的。

如果一个API有一个解释如何使用它的好文档,那么它可能是好的。但是,如果代码是干净、好的,并且遵循其内部的标准,那么它是否有一个合适的文档就无关紧要了。

我写过一些关于编码结构的文章 here

G S 15 年前

我认为最重要的是可读性,我指的是使大多数程序员能够在尽可能短的时间内理解代码的质量。但是判断哪一个软件是可读的,哪一个没有那么难以形容的人性:模糊性。你提到的要点在一定程度上成功地使它具体化。然而,从整体上讲,它必须是一个具体的事件,而且要想出普遍的规则是非常困难的。