JavaScript API 设计原则

前段时间组织优化我们的原生模块 API(iOS、Android 模块封装成 JavaScript 接口),于是学习了几篇 JavaScript API 设计的文章,尽管是旧文,但受益匪浅,这里记录一下。


好的 API 设计:在自描述的同时,达到抽象的目标。

设计良好的 API ,开发者可以快速上手,没必要经常抱着手册和文档,也没必要频繁光顾技术支持社区。

流畅的接口

方法链:流畅易读,更易理解

设置和获取操作,可以合二为一;方法越多,文档可能越难写

一致性

相关的接口保持一致的风格,一整套 API 如果传递一种熟悉和舒适的感觉,会大大减轻开发者对新工具的适应性。

命名这点事:既要短,又要自描述,最重要的是保持一致性

“There are only two hard problems in computer science: cache-invalidation and naming things.”
“在计算机科学界只有两件头疼的事:缓存失效和命名问题”
— Phil Karlton

选择一个你喜欢的措辞,然后持续使用。选择一种风格,然后保持这种风格。

处理参数

需要考虑大家如何使用你提供的方法,是否会重复调用?为何会重复调用?你的 API 如何帮助开发者减少重复的调用?
接收 map 映射参数,回调或者序列化的属性名,不仅让你的 API 更干净,而且使用起来更舒服、高效。

jQuery 的  css()  方法可以给 DOM 元素设置样式:

这个方法可以接受一个 JSON 对象:

 处理类型

定义方法的时候,需要决定它可以接收什么样的参数。我们不清楚人们如何使用我们的代码,但可以更有远见,考虑支持哪些参数类型。

加了短短的 6 行代码,我们的方法强大到可以接收  Date 对象,数字的时间戳,甚至像 Sat Sep 08 2012 15:34:35 GMT+0200 (CEST)  这样的字符串。

如果你需要确保传入的参数类型(字符串,数字,布尔),可以这样转换:

 处理 undefined

为了使你的 API 更健壮,需要鉴别是否真正的 undefined  值被传递进来,可以检查  arguments  对象:

给参数命名

Event.initMouseEvent 这个方法简直丧心病狂,不看文档的话,谁能说出每个参数是什么意思?

给每个参数起个名字,赋个默认值,可好

ES6, 或者 Harmony 就有 默认参数值 和 rest 参数 了。

参数接收 JSON 对象

与其接收一堆参数,不如接收一个 JSON 对象:

调用起来也更简单了:

参数默认值

参数最好有默认值,通过 jQuery.extend() , _.extend() 和 Protoype 的 Object.extend,可以覆盖预设的默认值。

扩展性

回调(callbacks)

通过回调, API 用户可以覆盖你的某一部分代码。把一些需要自定义的功能开放成可配置的回调函数,允许 API 用户轻松覆盖你的默认代码。

API 接口一旦接收回调,确保在文档中加以说明,并提供代码示例。

事件(events)

事件接口最好见名知意,可以自由选择事件名字,避免与原生事件 重名。

处理错误

不是所有的错误都对开发者调试代码有用:

这样的错误调试起来很痛苦,不要浪费开发者的时间,直接告诉他们犯了什么错:

 备注: typeof callback === "function"  在老的浏览器上会有问题, object 会当成个  function 。

可预测性

好的 API 具有可预测性,开发者可以根据例子推断它的用法。

Modernizr’s 特性检测 是个例子:

a) 它使用的属性名完全与 HTML5、CSS 概念和 API 相匹配

b) 每一个单独的检测一致地返回 true 或 false 值

依赖于开发者已熟悉的概念也可以达到可预测的目的。

jQuery’s 选择器语法 就是一个显著的例子,CSS1-CSS3 的选择器可直接用于它的 DOM 选择器引擎。

比例协调

好的 API 并不一定是小的 API,API 的体积大小要跟它的功能相称。

比如 Moment.js,著名的日期解析和格式化的库,可以称之为均衡,它的 API 既简洁又功能明确。

像 Moment.js 这样特定功能的库,确保 API 的专注和小巧非常重要。

编写 API 文档

软件开发最艰难的任务之一是写文档,实际上每个人都恨写文档,怨声载道的是没有一个好用的文档工具。

以下是一些文档自动生成工具:

  • YUIDoc (requires Node.js, npm)
  • JsDoc Toolkit (requires Node.js, npm)
  • Markdox (requires Node.js, npm)
  • Dox (requires Node.js, npm)
  • Docco (requires Node.js, Python, CoffeeScript)
  • JSDuck (reqires Ruby, gem)
  • JSDoc 3 (requires Java)

最重要的是:确保文档跟代码同步更新。

参考资料:

打赏支持我写出更多好文章,谢谢!

打赏作者

打赏支持我写出更多好文章,谢谢!

任选一种支付方式

1 1 收藏 评论

关于作者:涂鸦码龙

不高级前端攻城狮,原名金龙,不姓郭。【忙时码代码,无事乱涂鸦】http://jinlongz.lofter.com/,涂手:Alon 个人主页 · 我的文章 · 3 ·    

相关文章

可能感兴趣的话题



直接登录
跳到底部
返回顶部