为什么“开发人员友好性”是API设计的核心
jopen 12年前
<p> <strong>导读：</strong>现今 API 在软件开发领域中扮演的角色越来越重要。计算和开发领域的进化在被不断升级的抽象计算和高级语言主导，但除此以外，也被开发平台、库、和架构的发展所推动。Douglass C. Smith 教授在 2006 年 IEEE 的<a href="/misc/goto?guid=4958319687469678007" rel="nofollow" target="_blank">报告</a>中指出：后者的进程和发展将超越具体算法语言的发展。实际上是，开发人员也应该注意到这一点了：开发过程中的阻碍从学习算法和数据结构转换到了选择，学习和使用层出不穷的 API 上。但是很多<a title="程序员的本质" href="/misc/goto?guid=4958190753037208092">程序员</a>没有意识到 API 的优劣所导致的区别，以及为此需要设计好的 API 所要付出的努力。</p> <p> 微软在 API 设计上是很费心血的，这种努力和专注始于上世纪 80 年代 Windows 的诞生。他们理解一个平台的成功取决于这个平台所能吸引和拥有的开发者（Steve Ballmer 的<a href="/misc/goto?guid=4958319689022714623" rel="nofollow" target="_blank">视频</a> ”developers,developers,developers” )。 .Net 的首席架构师 Krzysztof Cwalina 出了一本专门《<a title=".NET 设计规范:约定、惯用法与模式" href="http://www.amazon.cn/gp/product/B003LXC6ZU/ref=as_li_qf_sp_asin_il_tl?ie=UTF8&tag=vastwork-23&linkCode=as2&camp=536&creative=3200&creativeASIN=B003LXC6ZU" rel="nofollow" target="_blank">.NET 设计规范:约定、惯用法与模式</a>》 指导开发人员。相似的，Sun（Oracle）也有相关的 Java SDK 的书籍。在一次<a href="/misc/goto?guid=4958319690603982730" rel="nofollow" target="_blank">采访</a>中，Sun 的前任首席架构师，Joshua Bloch (现任职 Google)洋洋洒洒地总结了 19 页 Sun 在 API 设计上的理念。同样的，SAP 雇佣了 Carnegie Mellon 大学的研究人员具体研发新的网络服务接口(web services interfaces)。这些业内大佬们的实例无不给了我们一个信号，API 设计在推动软件使用和程序开发中的价值。</p> <p> 译者注：本文通过学术统计报告理论上证实 API 质量的重要性，循序渐进地例证：API 的优劣如何评判，API 的改进能多大程度地提高编程效率，以及为什么我们需要一个对开发人员友好（Developer-Friendly）的 API。然后概括例举了优质 API 的特性，以及如何在实际操作中实现这些特性。</p> <p> <strong>我们的主张</strong></p> <p> 如果说书籍是以封皮判断，那么软件平台、服务、架构和库是由它们的 API 定义的。当开发人员评价一个 API 的时候，他们实际上是对 API 所有的服务和包裹进行评价。API 设计是很聪明的投资，你得到的回报是忠实的开发人员。</p> <p> 研发人员和机构越来越意识到 API 质量的好坏直接影响到自己代码的质量。虽然将他人代码质量的好坏视为 API 作者的责任有些奇怪，但 API 质量影响到使用 API 代码质量的例子却越来越多。尽管使用复制黏贴，样板等类似的编程方法被视为是缺乏编程技能，但是即便是最出色的程序员（在使用 API 的时候）也无法避免使用这样的编程方式除非自己用代码重新包装 API。不难看出每个研发人员用代码包装 API 都是在填补 API 天生的不足之处。因为 API 一旦出炉将被反复使用，所以越来越多的研发人员希望 API 的作者能填补 API 的天生不足。在有众多的开放式网络服务和免费开源组件可以选择的时代，研发人员默默的使用有天生不足 API 的日子已经一去不复返了。</p> <p> 为使 API 更加易学，易用，易除错作出的任何努力都可以直接提高使用 API 的程序员的效率。让我们回头看看开篇的主题：当今，研发人员将大量的时间花费在学习 API，使用 API 和代码调试上，这些活动都是在通过包裹在多个复杂的 API 来实现一个业务逻辑。所以，更好的 API 会使研发人员有更高的效率。很多学术数据可以证实 API 的设计质量直接联系到编程的实际效率。2007的一份<a href="/misc/goto?guid=4958319691389505735" rel="nofollow" target="_blank">研究报道</a>的 数据表明 API 上哪怕是细微的变化，例如使用构造函数(constructor)取代工厂方法（factory methods）也可以大幅度地提高程序员的编程效率。他们的数据显示，使用 constructor，不管程序员的经验、技术的区别，他们大多能在同样短的时间内完成；而使用 factory methods，程序员们所需要的时间可以相差 10 倍。也就是说 factory methods 的 API 很打程度上取决于使用者。而取决于个人的工具不是一个好工具。相似的<a href="/misc/goto?guid=4958319692184280477" rel="nofollow" target="_blank">报道</a>显示了编程效率可以相差 10 倍如果一个方法被放到不同的 class 里面。</p> <p> 很多时候在 API 软件不能很好地被使用的情况下，程序员会被指责太自我，或者恐惧新事物，不确定，疑惑（FUD）。但是实际情况是，API 的质量不够好才是主导因素。常见的问题是 API 的文档不够清晰明了；API 的方法太情景锁定（specific to scenario）；API 有太多 Dependencies，与其使用它，还不如自己写来地快。我们可以得出结论，只要 API 的质量不得到提高，软件的采用率也就不会上升。</p> <dl> <dt> <a><img style="width:558px;height:341px;" title="为什么“开发人员友好性”是API设计的核心" border="0" alt="为什么“开发人员友好性”是API设计的核心" src="https://simg.open-open.com/show/11c45a200b83672d251f89307c244280.gif" /></a> </dt> </dl> <p> <strong>什么是好的 API</strong></p> <p> 什么是好的 API？什么是程序员需要的？API 需要什么质量去吸引程序员？我们的设计努力应该付出在哪里？</p> <p> <strong>第一点：<em>intuitive: </em>直观</strong></p> <p> 什么是直观的？具体又如何实现？Wikipedia 上解释直观（intuitive）“不需要刻意努力的理解”（understanding without apparent effort），Merriam Webster 的解释是“不需要刻意有理推导来获取知识或者认识的力量”(“the power or faculty of attaining to direct knowledge or cognition without evident rational thought and inference”)。细说开去，我们可以用一个博士学位来讨论人类的认知过程，我们就不展开了。就 API 设计来讲，intuitive design 就是站在使用者的角度，保持逻辑一致。</p> <p> <strong>第二点，<em>simple: </em>简洁</strong></p> <p> 这个会在以后的博文里面具体展开。这里我们就说一个纲领：需要平衡复杂的功能和简单的用户界面。</p> <p> <strong>第三点是 <em>easy to understand, remember, and use </em>易于理解、记忆和使用</strong></p> <p> 这是任何专家都会给出的建议，但是实际操作却很难自始至终做到这点。尽量使用程序员们熟悉的逻辑和概念，用他们的语言(逻辑和语法)和他们对 话，尽量减少引进新的概念和规则。尊重他们熟悉的命名方式，这样可以帮助他们记忆。这些减少刻意学习和使用的设计理念在 API 设计中很重要，因为它直接决定了开发人员适应 API 的速度和程度。</p> <p> 简单适用：程序员没有太多时间去评估一个 API 的好坏去决定是否使用。大多数时候，我们就试用两个方法，看看好不好用。API 设计应该鼓励试用：核心情景必须能被简单采用，而且要有实例(sample code)来帮助采用。其二，API 要安全(<em><strong>safe</strong></em>)。这个包括两点，一是本身那个情景(scenario)要稳定。其次，如果出现问题，错误报告要全面、明确。</p> <p> <strong>最后一点：<em>documented </em>文档备案。</strong></p> <p> 拿到新的 API，我们程序员会直接动手，而不是读说明书。如果没有人读，APIs 到底需要文档吗？动手是浅尝辄止，我们叫了个方法，然后它做了意料之中的事情，至于它有可能会出现什么问题，然后有什么解决方法，或者同样的事情，是否有 更加有效的方法完成，一行程序是不能了解的。这个就是为什么我们需要文档，全方位、多角度的解释（Redundancy），不是简单的重复同一种内容 (repetition)。</p> <p> <strong>特定功能性 API (purpose-made APIs)</strong></p> <p> 好的 API 是设计出来的。以上所列举的 API 的特性和优点不会自然流露在程序里面，把一组能被重复使用的独立函数放在一起不是一个好的 API。软件与软件之间的界面会在独立板块的结界出现，但是这些界面如果不是结构上设计好的，他们放在一起不会是好的 API。这个不是因为程序员的个人技术好坏，而是实际操作过程中容易迷失全景的概念。并且这样生成的 API 很难维护，每次更新或者改错都会引出新的问题。Erich Gamma 说过“好的 API 不会是偶然的发生，而是刻意的出现。他们是一笔巨大的投资”。API 设计应该作为一个单独任务，从实际写程序的过程中独立出来。设计出来的 APIs 是 purpose-made APIs. 他们应该包括文档备案(documentation)，实例(code samples)，教程(tutorials)和单元测试(unit tests)。他们鼓励不同的采用方式，支持快速有效的用户端，如此才能与时俱进。</p> <p> 最后，正如 Joshua Bloch 所说：“公共 API，就像钻石，恒久美，永流传。你只有一个机会去把她做好，请竭尽全力。”</p> <p> （“<em>Public APIs, like diamonds, are forever. You have one chance to get it right so give it your best</em>”.）</p> <p> 原文作者：<a href="/misc/goto?guid=4958319692966435782" rel="nofollow" target="_blank">Ferenc Mihaly</a> 编译：<a href="/misc/goto?guid=4958319693759906993" target="_blank">伯乐在线</a> – 潘文佳<br /> <br /> 来自: <a id="link_source2" href="http://blog.jobbole.com/10197/?utm_source=rss&utm_medium=rss&utm_campaign=%25e4%25b8%25ba%25e4%25bb%2580%25e4%25b9%2588%25e2%2580%259c%25e5%25bc%2580%25e5%258f%2591%25e4%25ba%25ba%25e5%2591%2598%25e5%258f%258b%25e5%25a5%25bd%25e6%2580%25a7%25e2%2580%259d%25e6%2598%25afapi%25e8%25ae%25be%25e8" target="_blank">blog.jobbole.com</a></p>