文档章节

优秀API设计的十大原则

周进
 周进
发布于 2016/02/19 11:41
字数 816
阅读 266
收藏 10

1.只做你今天需要的
这是最顶级的规则。只解决今天必须解决的问题,最小化需要完成的答案。解决明天的问题的诱惑力是巨大的。但是一定要顶住诱惑!不要提前发布代码,重点是注重缩小发布周期。如果需要花几个小时的时间来回答新问题,那么就不用再猜测明天会出现什么问题了。
2.API模块化
将大型问题转化为规模较小的、可单独解决的问题。模块化API更容易学习,并且可以随时间而改变。你可以用新模块替代旧模块。可以一个一个地教导模块。也可以将API的实验部分从稳定或传统的部分中单独分出来。
3.使用结构化语法
使用结构化的API语法:用thing.action或thing.property代替do_action_with_thing。语法将自然而然地适应模块化的方法,其中每个模块是一个类。
4.使用自然语义
不要发明新概念。只使用开发人员众所周知的概念,作为类系系统的基础。如果你发现自己需要解释概念,那说明你出错了:要么你在解决以后的问题,要么你正在错误地构建API。

5.API的自我约定
每个类都要严格使用相同的样式和约定。一致性是指当一个人学会这一个类时,他就能够融会贯通地掌握全部的类。文档化约定,让它们成为贡献者必须的标准。
6.API的可扩展性
易扩展性有许多好处,并不仅仅在于受到贡献者的欢迎。它还可以让你延缓实现功能,因为“如果需要的话,后面再添加也很方便”。不需要的功能就不添加,这也是一种双赢。
7.完全测试
每个类和方法必须经过恶意代码的完全测试。要像写代码一样写测试,然后像API提供给外界约定文档一样使用测试。每当代码改变的时候就运行这些测试。不要担心代码覆盖率。重要的是外部约定。也可以考虑使用约定生命周期。
8.分层式成长
保持API突出重点,然后在顶部将新的API分层,以便于它们能随着时间的推移成长。可扩展性并不意味着无限期的成长。明确API的范围,并在范围内执行。
9.保持简单易用
最终的测试要看API的简单易用程度。你写的例子,能不能让你的代码看起来更简单?你是不是强迫用户说明他们不在乎的选项?有没有毫无价值的额外步骤?要注重约减少API的可视面积。
10.保持可移植性
不要让系统概念泄漏到API。整洁有目的地抽象:这个API可以运行在任何操作系统上。API必须能够隐藏实现,但要注意第4条规则,以及要使用自然抽象。


本文转载自:http://www.itlipeng.cn/?p=715&from=timeline&isappinstalled=0

周进
粉丝 16
博文 35
码字总数 5679
作品 0
成都
CTO(技术副总裁)
私信 提问
加载中

评论(1)

jasonkavay
jasonkavay
不错,不错,赞!博主,我们做了一个帮助博主推广博客的app叫同行说,只需复制文章链接即可发布给更多程序员们看到哦,欢迎体验哈,一起发扬分享精神~
设计优秀 web 作品的 10 项原则

Dieter Rams是 20 世纪最重要的设计大师之一,其闻名遐迩的“优秀设计应具备的 10 项原则”侧重于工业设计。 Lisbon 的设计师 NunoLoureiro 把这 10 项原则运用到 web 设计中,并在这篇文章中...

红薯
2012/02/08
3K
2
java 十大网站

1、Stackoverflow Stackoverflow.com 可能是编程界中最流行的网站了,该网站有成千上万个好问题和答案。学习API或者编程语言,通常依赖于代码示例,stackoverflow就可以提供大量的代码片段。...

hgqxjj
2017/12/21
0
0
重构 - 用各种方式优化自己的函数库

有时候,我会想:比我优秀的人,比我更努力。我努力有什么用。但是现在我习惯反过来想这句话,别人为什么会比我优秀,就是因为别人比我更努力。与其拼天赋,更不如比行动。 1.前言 最近有几天...

守候i
2018/06/11
0
0
出色的 JavaScript API 设计秘诀

设计是一个很普遍的概念,一般是可以理解为为即将做的某件事先形成一个计划或框架。 (牛津英语词典)中,设计是一种将艺术,体系,硬件或者更多的东西编织到一块的主线。软件设计,特别是作为...

jinker
2013/03/03
7.1K
14
如何设计出用户喜爱的API

原文:User experience design for APIs 作者:Francois Chollet 译者:夜风轻扬 译者注:什么样的API才是好的API?如何开发出用户乐于使用的API?请阅读下文。 编写代码不仅仅是人与电脑间的...

dev_csdn
2017/12/11
0
0

没有更多内容

加载失败,请刷新页面

加载更多

浅谈FlyWeight享元模式

一、前言 享元(FlyWeight)模式顾名思义,即是轻量级,原因就是享元,共享元素,这里的元素指的是对象。如何共享对象,那就是在检测对象产生的时候,如果产生的是同一个对象,那么直接使用已...

青衣霓裳
14分钟前
3
0
Python学习10.14:Python set集合详解

Python 中的集合,和数学中的集合概念一样,用来保存不重复的元素,即集合中的元素都是唯一的,互不相同。 从形式上看,和字典类似,Python 集合会将所有元素放在一对大括号 {} 中,相邻元素...

太空堡垒185
14分钟前
5
0
好程序员大数据教程分享Scala系列之文件以及正则表达式

好程序员大数据教程分享Scala系列之文件以及正则表达式 1 读取行 导入scala.io.Source后,即可引用Source中的方法读取文件信息。 import scala.io.Source object FileDemo extends App{ val ...

好程序员官网
15分钟前
3
0
75.nosql memcached与安装及查看状态

21.1 nosql介绍 21.2 memrcached介绍 21.3 安装memcached 21.4 查看memcachedq状态 21.1 nosql介绍 什么是NoSQL: 1.非关系型数据库就是NoSQL,关系型数据库代表MySQL 也是一种数据库,来存储...

oschina130111
17分钟前
3
0
玩转阿里云 Terraform(二):Terraform 的几个关键概念

上一篇《玩转阿里云Terraform(一):Terraform 是什么》介绍了 Terraform 的基本定义和特点之后,本文将着重介绍几个Terraform中的关键概念。 Terraform 关键概念 在使用Terraform的过程中,通...

阿里云官方博客
17分钟前
4
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部