开源中国

我们不支持 IE 10 及以下版本浏览器

It appears you’re using an unsupported browser

为了获得更好的浏览体验,我们强烈建议您使用较新版本的 Chrome、 Firefox、 Safari 等,或者升级到最新版本的IE浏览器。 如果您使用的是 IE 11 或以上版本,请关闭“兼容性视图”。
出色的 JavaScript API 设计秘诀 - 技术翻译 - 开源中国社区

出色的 JavaScript API 设计秘诀 【已翻译100%】

jinker 推荐于 5年前 (共 16 段, 翻译完成于 03-04) 评论 14
收藏  
129

设计是一个很普遍的概念,一般是可以理解为为即将做的某件事先形成一个计划或框架。 (牛津英语词典)中,设计是一种将艺术,体系,硬件或者更多的东西编织到一块的主线。软件设计,特别是作为软件设计的次类的API设计,也是一样的。但是API设计常常很少关注软件发展,因为为其他程序员写代码的重要性要次于应用UI设计和最终用户体验。

但是API设计,作为我们自己写的库中提供的公共接口,能够向调用我们代码的开发者表现出我们库的一些特点和功能,所以API设计和UI设计一样重要。事实上,两者都是为应用可以提供更好的用户体验具有基本的方式。应用UI在用户UX中占有很重要的位置,应用API是开发者的UX。因此,应用API设计应该被给予和我们提供给用户的接口相同水平的考虑和关注。正像我们关注UI的功效,简洁性和优美,我们也应该同样的评估API的功效,简洁性和代码的优美性!

API设计——javascript API设计的内容,呈现了唯一的挑战对所有的开发者,不管是否你正在开发一个公共的库或者一个内部的库。javascript的动态性,库使用者的匿名和需求的模棱两可都给API设计者呈现了一个令人畏惧的挑战。然而对于一个好的API设计是没有捷径的,但是可以从现代流行的一些javascript库中提取出一些设计准则是可能的!

骚年614
 翻译得不错哦!

API设计: 天使和恶魔的斗争

javascript API中差的设计会给使用你API的开发者和你带来高的花费。差的设计会导致浪费,使用你API的开发者会因为设法搞弄明白你接口而浪费时间,而API的开发者会因为处理不断增加的需求和解决使用者的困惑而浪费时间。然而几乎所有的API当初被开发的时候,都是为了能够提取相同的功能,方便调用并节约时间。但设计不好的API会使你的库使用者和你产生疑惑,这些库真的能节约时间吗?

优秀的API设计,一方面,完成了提取的目标,同时也实现了自我描述。当一个API被良好的设计,使用者可以快速地和直观地完成工作,完全不用不停的使用文档或者持续的访问支持或者解答网站。你也可以通过封装一些开发者需要自己花大量时间开发的一些特征来节约库开发者的时间。好的设计不仅节约开发者的时间,可以使他们看起来更加聪明和有责任。同样帮助你的用户看起来聪明和能干也会使你看起来更加的牛逼!

骚年614
 翻译得不错哦!

对于javascript来说,API设计特别重要

不管什么编程语言或者框架,API设计是重要的,API设计的重要性对于javascript来说是高于其它许多语言的。首先,作为一个动态的和后期绑定的语言,javascript没有编译器可以实现一个安全网或者检测单元功能,所以javascript不可以发现你代码中的错误。Linting 或检验框架 如 JSLintJSHint 可以帮助我们。这些框架的功能可以指出javascript中的一些普遍的错误,但是当我们使用API时,他们却不能发现javascript的错误。

这一切都取决于你,你可以开发一个具有良好设计的API,这个API可以帮助你的用户掉进众所周知的“成功坑”,这就意味着你的库对于开发者来说是舒服的和熟悉的,同时也提供了积极的强化和当开发者和你的代码交互时建立的信心。

骚年614
 翻译得不错哦!

“掉进成功的坑里”最好的例子是jQuery 通过CSS选择器语法获取DOM元素的运用。例如,如果我想要获取所有带有类名的article元素,我可以运用jQuery这样做:

$("article.blogPost").fadeIn();

选择器article.blogPost和下面展现使用完全一样的语法,这绝不是偶然的!

article.blogPost {
  border-radius: 10px;
  background-color: salmon;
  box-shadow: 0px 0px 10px 2px #ccc;
}

jQuery的选择器引擎被设计为了使我和其他开发者能够使我对CSS选择器的理解和它的引擎进行交互。结果可想而知,如果jQuery需要我用一种新的,为特定目的形成的语法,我将失去快速,明显和高效。

我们可以获得灵感从这些框架中,如jQuery,或者其他框架,并应用这些灵感到我们的设计中。然而,获得灵感并不是抄袭,有个度的问题,任何设计过API的人如果是仅仅的基于别人的想法,不管好与坏,他都将继承。如果我们将在好的javascript中获得的准则运用到其他领域中,我们能开发拥有好的API的框架,这些API设计能被运用在任何情况下。

骚年614
 翻译得不错哦!

出色的Javascript APIs设计秘诀

虽然软件不具有与绘画或建筑类似的视觉评价标准,我们仍倾向于使用与物理实体一样的形容词来描述软件质量。例如,使用“优雅的”与“漂亮的”来赞美软件并不罕见。如果用与物理实体相似的形容词描述软件接口是合理的话,那么当然也可以使用与之相同的原则来评价软件设计。

在本节,将四个来自艺术领域的流行设计原则扩展至API设计中:

  • 和谐一致
  • 平衡
  • 对称
  • 重点突出

对每一个原则,将列出一到多个实例来说明,这些例子表明流行的Javascript库API设计是怎样遵循这些原则的。

jinker
 翻译得不错哦!

原则1:一致性&协调性

在艺术作品中,一致性是一个作品背后不可缺少的观念,或者说设计者如何把一些事物组成连贯的一个整体。协调性,从另一方面来说,是一个作品相似元素的布局,这会在考虑整体时产生一种简洁的感觉。

对于API的设计者,这些原则可以通过在类库使用类似的和(或者)统一的元素来实现。就拿Kendo UI来说吧,一个创建富web应用程序的javascript框架。Kendo UI提供了一系列的UI控件和工具,这些都可以通过一个简单的语法初始化。比如,如果我想从一个无序列表创建一个树形控件(TreeView),我只需调用以下方法:

$("ul.tree").kendoTreeView({ /* Configuration goes here */ });

Kendo TreeView
Kendo UI树形组件

如果我想通过一个列表创建一个面板PanelBar,我只需稍微改成不同的调用方法.

$("ul.panel").kendoPanelBar({ /* Configuration goes here */ });

Kendo PanelBar
Kendo UI 面板组件
缪斯的情人
 翻译得不错哦!

Kendo UI 对所有组件使用一致的kendoX语法,促进整体的协调。更重要的,这样的设计依赖jQuery对象为DOM元素封装了统一的一层,使设计有利于所有熟悉jQuery开发者。数百万开发者使用类似的“土语”(jQuery语法),Kendo UI可以顺利地跨库使用。

另一个协调的案例是Backbone的[object].extend语法创建对象,继承和扩展Backbone的Models,Views,CollectionsRouters的功能。用如下代码就可以创建一个Backbone Model,带有Backbone的完整支持,也可以自定义我需要的功能:

var Book = Backbone.Model.extend({
  initialize: function() { ... },
  author: function() { ... },
  pubDate: function() { ... },
});

统一和协调的目的是让API新手感觉熟悉和舒服。通过虽然功能不同,但是语法相同或相似,使API变得熟悉,大大减轻了开发者使用新工具的负担。

傅小黑
 翻译得不错哦!

原则 2 :平衡

下一条原则是平衡,组织元素时不会让某个部分过于重量级而盖过其它部分,使用时不稳定。艺术作品里,平衡就是视觉权重。即使不对称,作品中仍能感觉到不对称下的平衡,因为它遵循某种模式。上下文中的API设计的平衡,我特指代码的视觉权重和可预测性(看得出功能)。

平衡的API让人觉得其组成部分属于彼此,他们行为相同,或互补地完成一个目标。通过扩展,APIs也可以感觉平衡,它们允许开发人员简单的预测其他API并使用。如Modernizr属性测试,它们的平衡性在两个方面,a)属性名对应HTML5和CSS术语和API名称,b)每个属性测试统一地返回true或false值。

// All of these properties will be 'true' or 'false' for a given browser
  Modernizr.geolocation
  Modernizr.localstorage
  Modernizr.webworkers
  Modernizr.canvas
  Modernizr.borderradius
  Modernizr.boxshadow
  Modernizr.flexbox


Modernizr

傅小黑
 翻译得不错哦!

访问一个单一的属性来告诉开发者需要了解到的相关属性,以便通过它访问每一个其他属性,一个高质量API的强大之处就在于它的简单。平衡性也保证了我写和Modernizr交互的代码在每次读写时具有相同的视觉加权。如何在我使用和访问API时看起来和感觉上一样,而不顾我的惯例。另一方面,如果Modernizr添加了一个polyfill Canvas的API,不仅仅是类库的视觉加权受到新API的影响,Modernizr的范围和用途也将大大扩大,并且我在和API交互时可预测性也受到了限制。

达到平衡的另一种方式是通过依靠开发人员对概念的熟悉获得可预测性的结果。一个典型的例子就是jQuery’s selector syntax(jquery选择器的语法),它映射css1-3的选择器到自己的DOM选择器引擎:

$("#grid") // Selects by ID
$("ul.nav > li") // All LIs for the UL with class "nav"
$("ul li:nth-child(2)") // Second item in each list

通过使用一个熟悉的概念并且映射到自己的类库,jquery避免了新的选择器语法,同事也创建了一个机制让新用户通过一个可预测的API快速的把类库应用到生产.。

缪斯的情人
 翻译得不错哦!

原则 3: 相称性

接下来的原则是相称性,它是用来衡量一个作品中元素的大小和数量的。与其说一个好的API是一个小的api,相称性是相对于用途的大小。一个相称的API它的API表面和它的能力范围相匹配。

例如,Moment.js,一个流行的日期转换和格式化类库,可以把它视为具有相称性,因为它的API表层是紧凑的,它和类库的目的明确的匹配。Moment.js用于处理日期,它的API提供了便利的功能用来处理javascript Date对象:

moment().format('dddd');
moment().startOf('hour').fromNow();

Moment.js

对于一个有针对性的类库,像Moment.js,保持API的专注和简单是非常重要的。对于更大和更广阔的类库,API的大小应当能够反映出类库自身的能力。

缪斯的情人
 翻译得不错哦!
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们
评论(14)
Ctrl/CMD+Enter

和谐一致
平衡
相衬性
重点突出
看样子我的汉语退步了,愣是看糊涂了。

引用来自“江源”的评论

看样子我的汉语退步了,愣是看糊涂了。

原文写得有点乱
一致 平衡 相衬 突出
此文确实不好翻译,很多概念都是确定再三才敢翻译的。尽量保证意译,类似文章作者写的时候比较随意,语法上不是那么严谨。
一致 平衡 相衬 突出
说真的,现在看中文还不如看英文舒服了……不知道是不是翻译的问题
文章写的非常好.多谢翻译!
不错,只是感觉有点难读懂
这篇文章有价值
有点像写文章呵呵
和谐一致: 前后语法通顺一致
平衡:用词、形式一致
对称:文章的大小合适
重点突出:有中心思想
mark 下
mark 下
mark
顶部