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

atitit.api设计 方法 指南 手册 v2 q929.docx相关推荐

  1. atitit.架构设计---方法调用结果使用异常还是返回值

    atitit.架构设计---方法调用结果使用异常还是返回值 1. 应该返回BOOL类型还是异常 1 2. 最终会有四种状况,抛出异常.返回特殊值.阻塞.超时 1 3. 异常的优缺点点 1 4. jav ...

  2. Atitit r2017 r1 doc list on home ntpc.docx

    Atitit r2017 r1 doc list on home ntpc.docx 驱动器 D 中的卷是 p2soft 卷的序列号是 9AD0-D3C8 D:\ati ext\r2017 doc e ...

  3. HTTP API 设计指南（基础部分）

    为了保证持续和及时的更新,强烈推荐在我的Github上关注该项目,欢迎各位star/fork或者帮助翻译 前言 这篇指南介绍描述了 HTTP+JSON API 的一种设计模式,最初摘录整理自 Hero ...

  4. Atitit q2016 qb doc list on home ntpc.docx

    Atitit q2016 qb doc list on home ntpc.docx 驱动器 D 中的卷是 p2soft 卷的序列号是 9AD0-D3C8 D:\ati ext notbek\q201 ...

  5. Atitit r2017 r3 doc list on home ntpc.docx

    Atitit r2017 r3  doc list on home ntpc.docx 驱动器 D 中的卷是 p2soft 卷的序列号是 9AD0-D3C8 D:\ati ext\r2017 doc ...

  6. Atitit r2017 r6 doc list on home ntpc.docx

    Atitit r2017 r6 doc list on home ntpc.docx 驱动器 D 中的卷是 p2soft 卷的序列号是 9AD0-D3C8 D:\ati\r2017 v4 raf\r2 ...

  7. Atitit r2017 ra doc list on home ntpc.docx

    Atitit r2017 ra doc list on home ntpc.docx 驱动器 C 中的卷是 p1sys 卷的序列号是 A87E-7AB4 C:\Users\Administrator\ ...

  8. RESTful API 设计指南 (转)

    RESTful API 设计指南 2016-02-23 ImportNew (点击上方公号,可快速关注) 作者:阮一峰 链接:http://www.ruanyifeng.com/blog/2014/0 ...

  9. Atitit. 包厢记时系统 的说明，教程，维护，故障排查手册v2 pb25.doc

    Atitit. 包厢记时系统 的说明,教程,维护,故障排查手册v2 pb25.doc 1. 服务器方面的维护1 1.1. 默认情况下,已经在系统的启动目录下增加了 个启动项目1 1.2. 后台服务.保 ...

  10. RESTful API 设计指南

    原文地址:http://www.ruanyifeng.com/blog/2014/05/restful_api.html RESTful API 设计指南 作者: 阮一峰 日期: 2014年5月22日 ...

最新文章

  1. 神经网络入门——14多层感知机
  2. s5pv210 uboot-2012-10移植(三) 之支持SPL
  3. Spring Boot 2.0(三)：Spring Boot 开源软件都有哪些？
  4. 华为发布“吓人技术”GPU Turbo
  5. 49.Kth Largest Element in an Array
  6. 玩转spring boot——结合jQuery和AngularJs
  7. Android 四大组件学习之Service六
  8. 采集过程中遇到的利器
  9. JavaWeb编年史（青铜时代）
  10. 网易云音乐修改名字怎么老是服务器错误,网易云音乐为什么改了名字?网抑云是怎么回事...
  11. JavaFX示例--简易图片处理工具
  12. Python中的 len() 是什么？如何使用 len() 函数查找字符串的长度
  13. 计算机房图怎么画,任务6掌握机房平面图的绘制方法.ppt
  14. MySQL的查询重写规则
  15. vue显示农历_vue中通过时间转换农历得方法封装
  16. 【专业的项目管理工具】Curio for Mac 13.0
  17. 【编程入门】开源记事本（安卓版）
  18. 计算机科学文科学士,计算机科学文科学士与理科硕士
  19. 订阅号留言板：公众号留言功能开通新思路！（建议收藏）
  20. 【Python 针对 excel 数据处理案例】

热门文章

  1. Bootstrap （remote）事件监听多次
  2. NornJ-javascript模版引擎
  3. paper 63 ：函数比较：imfilter与fspecial
  4. Visual Studio 2008 Designer.cs不能更新/自动添加控件声明的解决办法
  5. linux最常用命令
  6. MySQL-快速入门（11）用户管理
  7. 因打印日志而引发的故障
  8. [USACO08MAR]Land Acquisition
  9. 推荐系统-协同过滤原理与实现
  10. 对/proc和/sys的一些理解