JavaScript API 设计原则
网+线下沙龙 | 移动APP模式创新:给你一个做APP的理由>>
好的 API 设计:在自描述的同时,达到抽象的目标。
设计良好的 API ,开发者可以快速上手,没必要经常抱着手册和文档,也没必要频繁光顾技术支持社区。
流畅的接口
方法链:流畅易读,更易理解
- //常见的 API 调用方式:改变一些颜色,添加事件监听
- var elem = document.getElementById("foobar");
- elem.style.background = "red";
- elem.style.color = "green";
- elem.addEventListener('click', function(event) {
- alert("hello world!");
- }, true);
- //(设想的)方法链 API
- DOMHelper.getElementById('foobar')
- .setStyle("background", "red")
- .setStyle("color", "green")
- .addEvent("click", function(event) {
- alert("hello world");
- });
设置和获取操作,可以合二为一;方法越多,文档可能越难写
- var $elem = jQuery("#foobar");
- //setter
- $elem.setCss("background", "green");
- //getter
- $elem.getCss("color") === "red";
- //getter, setter 合二为一
- $elem.css("background", "green");
- $elem.css("color") === "red";
一致性
相关的接口保持一致的风格,一整套 API 如果传递一种熟悉和舒适的感觉,会大大减轻开发者对新工具的适应性。
命名这点事:既要短,又要自描述,最重要的是保持一致性
“There are only two hard problems in computer science: cache-invalidation and naming things.”
“在计算机科学界只有两件头疼的事:缓存失效和命名问题”
— Phil Karlton
选择一个你喜欢的措辞,然后持续使用。选择一种风格,然后保持这种风格。
处理参数
需要考虑大家如何使用你提供的方法,是否会重复调用?为何会重复调用?你的 API 如何帮助开发者减少重复的调用?
接收map映射参数,回调或者序列化的属性名,不仅让你的 API 更干净,而且使用起来更舒服、高效。
jQuery 的 css()
方法可以给 DOM 元素设置样式:
- jQuery("#some-selector")
- .css("background", "red")
- .css("color", "white")
- .css("font-weight", "bold")
- .css("padding", 10);
这个方法可以接受一个 JSON 对象:
- jQuery("#some-selector").css({
- "background" : "red",
- "color" : "white",
- "font-weight" : "bold",
- "padding" : 10
- });
- //通过传一个 map 映射绑定事件
- jQuery("#some-selector").on({
- "click" : myClickHandler,
- "keyup" : myKeyupHandler,
- "change" : myChangeHandler
- });
- //为多个事件绑定同一个处理函数
- jQuery("#some-selector").on("click keyup change", myEventHandler);
处理类型
定义方法的时候,需要决定它可以接收什么样的参数。我们不清楚人们如何使用我们的代码,但可以更有远见,考虑支持哪些参数类型。
- //原来的代码
- DateInterval.prototype.days = function(start, end) {
- return Math.floor((end - start) / 86400000);
- };
- //修改后的代码
- DateInterval.prototype.days = function(start, end) {
- if (!(start instanceof Date)) {
- start = new Date(start);
- }
- if (!(end instanceof Date)) {
- end = new Date(end);
- }
- return Math.floor((end.getTime() - start.getTime()) / 86400000);
- };
加了短短的6行代码,我们的方法强大到可以接收 Date
对象,数字的时间戳,甚至像 Sat Sep 08 2012 15:34:35 GMT+0200 (CEST)
这样的字符串
如果你需要确保传入的参数类型(字符串,数字,布尔),可以这样转换:
- function castaway(some_string, some_integer, some_boolean) {
- some_string += "";
- some_integer += 0; // parseInt(some_integer, 10) 更安全些
- some_boolean = !!some_boolean;
- }
处理 undefined
为了使你的 API 更健壮,需要鉴别是否真正的 undefined
值被传递进来,可以检查 arguments
对象:
- function testUndefined(expecting, someArgument) {
- if (someArgument === undefined) {
- console.log("someArgument 是 undefined");
- }
- if (arguments.length > 1) {
- console.log("然而它实际是传进来的");
- }
- }
- testUndefined("foo");
- // 结果: someArgument 是 undefined
- testUndefined("foo", undefined);
- // 结果: someArgument 是 undefined , 然而它实际是传进来的
给参数命名
- event.initMouseEvent(
- "click", true, true, window,
- 123, 101, 202, 101, 202,
- true, false, false, false,
- 1, null);
Event.initMouseEvent 这个方法简直丧心病狂,不看文档的话,谁能说出每个参数是什么意思?
给每个参数起个名字,赋个默认值,可好
- event.initMouseEvent(
- type="click",
- canBubble=true,
- cancelable=true,
- view=window,
- detail=123,
- screenX=101,
- screenY=202,
- clientX=101,
- clientY=202,
- ctrlKey=true,
- altKey=false,
- shiftKey=false,
- metaKey=false,
- button=1,
- relatedTarget=null);
ES6, 或者 Harmony 就有 默认参数值 和 rest 参数 了。
参数接收 JSON 对象
与其接收一堆参数,不如接收一个 JSON 对象:
- function nightmare(accepts, async, beforeSend, cache, complete, /* 等28个参数 */) {
- if (accepts === "text") {
- // 准备接收纯文本
- }
- }
- function dream(options) {
- options = options || {};
- if (options.accepts === "text") {
- // 准备接收纯文本
- }
- }
调用起来也更简单了:
- nightmare("text", true, undefined, false, undefined, /* 等28个参数 */);
- dream({
- accepts: "text",
- async: true,
- cache: false
- });
参数默认值
参数最好有默认值,通过 jQuery.extend() http://underscorejs.org/#extend) 和 Protoype 的 Object.extend ,可以覆盖预设的默认值。
- var default_options = {
- accepts: "text",
- async: true,
- beforeSend: null,
- cache: false,
- complete: null,
- // …
- };
- function dream(options) {
- var o = jQuery.extend({}, default_options, options || {});
- console.log(o.accepts);
- }
- dream({ async: false });
- // prints: "text"
扩展性
回调(callbacks)
通过回调, API 用户可以覆盖你的某一部分代码。把一些需要自定义的功能开放成可配置的回调函数,允许 API 用户轻松覆盖你的默认代码。
API 接口一旦接收回调,确保在文档中加以说明,并提供代码示例。
事件(events)
事件接口最好见名知意,可以自由选择事件名字,避免与原生事件 重名。
处理错误
不是所有的错误都对开发者调试代码有用:
- // jQuery 允许这么写
- $(document.body).on('click', {});
- // 点击时报错
- // TypeError: ((p.event.special[l.origType] || {}).handle || l.handler).apply is not a function
- // in jQuery.min.js on Line 3
这样的错误调试起来很痛苦,不要浪费开发者的时间,直接告诉他们犯了什么错:
- if (Object.prototype.toString.call(callback) !== '[object Function]') { // 看备注
- throw new TypeError("callback is not a function!");
- }
- 备注:typeof callback === "function" 在老的浏览器上会有问题,object 会当成个 function 。
可预测性
好的 API 具有可预测性,开发者可以根据例子推断它的用法。
Modernizr’s 特性检测 是个例子:
a) 它使用的属性名完全与 HTML5、CSS 概念和 API 相匹配
b) 每一个单独的检测一致地返回 true 或 false 值
- // 所有这些属性都返回 'true' 或 'false'
- Modernizr.geolocation
- Modernizr.localstorage
- Modernizr.webworkers
- Modernizr.canvas
- Modernizr.borderradius
- Modernizr.boxshadow
- Modernizr.flexbox
依赖于开发者已熟悉的概念也可以达到可预测的目的。
jQuery’s 选择器语法 就是一个显著的例子,CSS1-CSS3 的选择器可直接用于它的 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
比例协调
好的 API 并不一定是小的 API,API 的体积大小要跟它的功能相称。
比如 Moment.js ,著名的日期解析和格式化的库,可以称之为均衡,它的 API 既简洁又功能明确。
像 Moment.js 这样特定功能的库,确保 API 的专注和小巧非常重要。
编写 API 文档
软件开发最艰难的任务之一是写文档,实际上每个人都恨写文档,怨声载道的是没有一个好用的文档工具。
以下是一些文档自动生成工具:
JavaScript API 设计原则的更多相关文章
- javascript的api设计原则
前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来.很难做到 ...
- JavaScript 的 API设计原则
一.接口的流畅性 好的接口是流畅易懂的,他主要体现如下几个方面: 1.简单 操作某个元素的css属性,下面是原生的方法: document.querySelectorAll('#id').style. ...
- 出色的 JavaScript API 设计秘诀
设计是一个很普遍的概念,一般是可以理解为为即将做的某件事先形成一个计划或框架. (牛津英语词典)中,设计是一种将艺术,体系,硬件或者更多的东西编织到一块的主线.软件设计,特别是作为软件设计的次类的AP ...
- 【JS】327- javascript 的 api 设计原则
点击上方"前端自习课"关注,学习起来~ 前言 本篇博文来自一次公司内部的前端分享,从多个方面讨论了在设计接口时遵循的原则,总共包含了七个大块.系卤煮自己总结的一些经验和教训.本篇博 ...
- GOTO Berlin: Web API设计原则
在邮件列表和讨论区中有很多与REST和Web API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver Wolf在GOTO Berlin大会上开始自己的 ...
- Atitit. Api 设计 原则 ---归一化
Atitit. Api 设计 原则 ---归一化 1.1. 叫做归一化1 1.2. 归一化的实例:一切对象都可以序列化/toString 通过接口实现1 1.3. 泛文件概念.2 1.4. 游戏行业 ...
- API设计原则
译序 Qt的设计水准在业界很有口碑,一致.易于掌握和强大的API是Qt最著名的优点之一.此文既是Qt官网上的API设计指导准则,也是Qt在API设计上的实践总结.虽然Qt用的是C++,但其中设计原则和 ...
- API设计原则(觉得太合适,转发做记录)
API设计原则 对于云计算系统,系统API实际上处于系统设计的统领地位,正如本文前面所说,K8s集群系统每支持一项新功能,引入一项新技术,一定会新引入对应的API对象,支持对该功能的管理操作,理解掌握 ...
- RESTful API设计原则与规范
RESTful API设计原则与规范 一.背景与基础概念 2 二.RESTful API应遵循的原则 3 1.协议(Protocol) 3 2.域名(ROOT URL) 3 3.版本(Versioni ...
随机推荐
- block的传值简单示例仅供参考,大牛勿喷
#import "ViewController.h" typedef void(^sumBlock)(int s);//声明为一个类型; /** * 用声明的block类型 su ...
- XtraReport 实例化 打印
// Create a report instance, assigned to a Print Tool. ReportPrintTool pt = new ReportPrintTool( ...
- ubuntu14.04 wifi频繁掉线解决
uname -r sudo lspci -knn sudo lshw -numeric -class network sudo ifconfig -a sudo route -nv sudo rfki ...
- Informix SDK對比
一.基本信息對比 表 1. Informix .NET Provider 和 IBM Data Server .NET Provider 的对比 特性 IBM Informix .NET Provid ...
- Go Mobile 例子 basic 源码分析
OpenGL ES(OpenGL for Embedded Systems)是 OpenGL 三维图形API的子集,针对手机.PDA和游戏主机等嵌入式设备而设计.该API由Khronos集团定义推广, ...
- centos7 下安装MongoDB
查看MongoDB的最新版官方下载地址: https://www.mongodb.com/download-center#community 使用wget命令下载安装包 wget https://fa ...
- [CF 475D] CGCDSSQ (RMQ)
题目链接:http://codeforces.com/contest/475/problem/D 是昨天晚上的CF题目,题意是给定你n个数,问你所有子区间内的最小公约数是x的个数是多少 问的康神,了解 ...
- Oracle Grid Infrastructure: Understanding Split-Brain Node Eviction (文档 ID 1546004.1)
In this Document Purpose Scope Details What does "split brain" mean? Why is this ...
- Grunt 之通配符
在描述源码路径的时候,经常有一些特殊的奇怪的要求.Grunt 通过内建的 node-glob 和 minimatch 库提供了文件名的扩展机制. 常见的通配符如下: * 匹配除了 / 之外的任意数量的 ...
- 翻译:Knockout 快速上手 - 2: 安装 knockoutJS
只需要五个简单的步骤,就可以做好使用 Knockout 开发的准备! 第一步 我们需要什么? 最低限度,为了完成后面的教程,你需要如下的准备 Web 浏览器 文本编辑器 你的电脑上大约 2M 的磁盘空 ...