atitit.api设计 方法 指南 手册 v2 q929.docx

atitit.api设计原则与措施

 

 

1. 归一化(锤子钉理论)1

1.1. 链式方法2

1.2. 规则5:建立返回值类型2

1.3.
参数接收 JSON 对象2

1.4.
参数默认值2

1.5. 命名参数 support by map2

1.6.
 甩卖项目
类型自动转换4

1.7.
 处理
undefined null  empty5

1.8.
.利用结构化语法5

1.9.
装以及沾操作,可以共同二呢同;方法更加多,文档可能越来越难写
jq.val()5

2.
扩展性5

2.1.
回调(callbacks)5

2.2.
事件(events)5

3.
处理错误 throw friendly
ex6

4. 并且俩个主意返回null和ex6

5.
可预测性 兼容性6

5.1. 编纂SPI尤为关键6

6. 反面例子 反模式6

7. 参考7

 

 

1. 由一化(锤子钉理论)

2. 避以长参数列表

· 三独或三个里头的参数是绝圆的

· 长参数列表是损伤的,程序员容易出错,并且程序于编译、运行时见面呈现糟糕

· 缩短参数的简单栽艺术:Break up
method、创建参数助手类

作者::  ★(attilax)>>>   绰号:老哇的爪子 ( 全名::Attilax Akbar Al Rapanui 阿提拉克斯 阿克巴 阿尔 拉帕努伊 ) 汉字名:艾龙,  EMAIL:1466519819@qq.com

转载请注明来源: http://blog.csdn.net/attilax

 

2.1. 链式方法

2.2. 平整5:建立返回值类型

 

当干到回值类型时,你应有创建同的、正规的API,下面提供相同效仿装置规则(你或许会见对下的平整是异议):

当方法返回一个单独的目标,但并没有对象吃发现时,应该回到null。

当方法返回多个目标,但连没对象被发觉时不时,应该回到空List、Set、Map、array等,而无是null。

办法应该摒弃大以防万一样

对地方的1、2条,最好的履应该是:

废弃来ObjectNotFoundExceptions当没对象吃察觉经常

 

不用回来null,一般以throw ex 尾号。。除非特别一个XXretNull的方法.. Null方便的if判断..

2.3. 参数接收 JSON 对象

及那收到一堆放参数,不如接收一个 JSON
对象:

2.4. 参数默认值

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

 

2.5. 命名参数 support by map

接受 map
映射参数,回调或者序列化的属性名,不仅给您的 API
更干净,而且动用起来重新舒适、高效。

 

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

JavaScript

1

2

3

4

5

jQuery("#some-selector")

  .css("background", "red")

  .css("color", "white")

  .css("font-weight", "bold")

  .css("padding", 10);

这办法可领一个 JSON
对象:

JavaScript

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

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);

2.6.  处理项目 类型自动转换

定义方法的时段,需要控制它可以吸纳什么样的参数。我们无理解人们怎么采取我们的代码,但得再起远见卓识,考虑支持什么参数类型。

// 修改后的代码

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)  这样的字符串。

2.7.  处理 undefined null  empty

 

为了使您的 API
更健全,需要鉴别是否确实

 

2.8. .使用结构化语法

以结构化的API语法:用thing.action或thing.property代替do_action_with_thing。语法将自然而然地适应模块化的主意,其中每个模块是一个接近。

 

2.9. 装和获得操作,可以一起二乎同样;方法更多,文档可能更难写 jq.val()

3. 扩展性

3.1. 回调(callbacks)

经过回调, API
用户可挂若的有一样有的代码。把一部分需要由定义之功效开放化可安排的回调函数,允许
API 用户轻松覆盖若的默认代码。

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

3.2. 事件(events)

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

4. 处理错误 throw friendly ex

切莫是具的缪都对准开发者调试代码有用

5. 而且俩独法子返回null和ex 

Ex对多数情况发生因此,单判断场合代码太多。Null则发因此。。

对此类库开发者,最好俩个都提供即可。工用户select

6. 可预测性 兼容性

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

Modernizr’s
特性检测 是单例证:

a) 它应用的性能名全同 HTML5、CSS
概念以及 API 相匹配

6.1. 9. 还多的性质,更不见之计

6.2. 编辑SPI尤为重大

· Service
Provider Interface即服务提供商接口,插件服务支撑多落实,例如Java
Cryptography Extension (JCE);

· 发布前编写多只插件;

· “三浅口径”(“The
Rule of Threes”):指的是当有意义第三糟出现不时,才进行”抽象化”

 

7. 反面例子 反模式

十那个最差实践

1. 错误处理不周全或正如不同

2. Rest
API忽视HTTP规则

3. 爆出原始底层数据模型

4. 安全复杂性

5. 竟和非法发布

6. 欠开发经历

7. 企盼一个MVC架构带给您一个巨大之API

8. 借出要你构建API,用户就见面叫唤起上(Assume
if you build it they will come)

9. 技术支持不充分

10. 文档不为力

 

 

8. 参考

出色API设计的十雅口径 – 51CTO.COM.html

计划精良API的五怪规则-CSDN.NET.html

JavaScript API
设计基准 – WEB前端 – 伯乐于线.html

 atitit.api设计条件 准则  v2 q929

 

Google首席软件工程师Joshua Bloch谈如何计划同样慢性可以的API【附PPT】-CSDN.NET.html

API设计之十格外无比差与五分外极品实践-CSDN.NET.html

API设计原则 – jeff技术博客 – 博客频道 – CSDN.NET.html

相关文章

网站地图xml地图