优秀的API接口设计原则及方法（转）

一旦API发生变化，就可能对相关的调用者带来巨大的代价，用户须要排查全部调用的代码，须要调整全部与之相关的部分，这些工做对他们来讲都是额外的。若是辛辛苦苦完成这些之后，还发现了相关的bug，那对用户的打击就更大。若是API常常发生变化，用户就会失去对提供方失去信心，从而也会影响目前的业务。

可是咱们为何还要修改API呢？为了API看起来更加漂亮？为了提供更多功能？为了提供更好的性能？仍是仅仅以为到了改变了时候了？对于用户来讲，他们更愿意使用一个稳定可是看起来不那么时髦的API，这并不意味着咱们再也不改进API了。当糟糕的API带来的维护成本愈来愈大时，我想就是咱们去重构它的时候。

若是能够回头从新再作一遍，那么我心目中的优秀的API应该是怎么样的？

判断一个API是否优秀，并非简单地根据第一个版本给出判断的，而是要看随着时间的推移，该API是否还能存在，是否仍旧保持得不错。槽糕的API接口各类各样，可是好的API接口对于用户来讲必须知足如下几个点：

• 易学习：有完善的文档及提供尽量多的示例和可copy－paste的代码，像其余设计工做同样，你应该应用最小惊讶原则。
• 易使用：没有复杂的程序、复杂的细节，易于学习；灵活的API容许按字段排序、可自定义分页、 排序和筛选等。一个完整的API意味着被指望的功能都包含在内。
• 难误用：对详细的错误提示，有些经验的用户能够直接使用API而不须要阅读文档。

而对于开发人员来讲，要求又是不同的：

• 易阅读：代码的编写只须要一次一次，可是当调试或者修改的时候都须要对代码进行阅读。
• 易开发：个最小化的接口是使用尽量少的类以及尽量少的类成员。这样使得理解、记忆、调试以及改变API更容易。

如何作到以上几点，如下是一些总结：

一、 面向用例设计

若是一个API被普遍使用了，那么就不可能了解全部使用该API的用户。若是设计者但愿可以设计出被普遍使用的API，那么必须站在用户的角度来理解如何设计API库，以及如何才能设计出这样的API库。

二、 采用良好的设计思路

在设计过程当中，若是能按照下面的方式来进行设计，会让这个API生命更长久

• 面向用例的设计，收集用户建议，把本身模拟成用户，保证API设计的易用和合理
• 保证后续的需求能够经过扩展的形式完成
• 初版作尽可能少的内容，因为新需求能够经过扩展的形式完成，所以尽可能少作事情是抑制API设计错误的一个有效方案
• 对外提供清晰的API和文档规范，避免用户错误的使用API，尤为是避免API（见第一节）靠后级别的API被用户知晓与误用

除此以外，下面还列出了一些具体的设计方法：

• 方法优于属性
• 工厂方法优于构造函数
• 避免过多继承
• 避免因为优化或者复用代码影响API
• 面向接口编程
• 扩展参数应当是便利的
• 对组件进行合理定位，肯定暴露多少接口
• 提供扩展点

三、 避免极端的意见

在设计API的时候，必定要避免任何极端的意见，尤为是如下几点：

• 必须漂亮（API不必定须要漂亮）
• API必须被正确地使用（用户很难理解如何正确的使用API，API的设计者要充分考虑API被误用的状况：若是一个API可能会被误用，那么它必定会被误用）
• 必须简单（咱们总会面临复杂的需求，能二者兼顾的API是更好的API）
• 必须高性能（性能能够经过其余手段优化，不该该影响API的设计）
• 必须绝对兼容（尽管本文一直提到如何保证兼容，可是咱们仍然要意识到，一些极少状况下会遇到的不兼容是能够容忍的）

四、 有效的API评审

API设计完成之后，须要通过周密的设计评审，评审的重点以下：

• 用例驱动，评审前必须提供完善的使用用例，确保用例的合理性和完备性。
• 一致性，是否与系统中其余模块的接口风格一致，是否与对称接口的设计一致。
• 简单明了，API应该简单好理解，容易学习和使用的API才不容易被误用，给咱们带来更多的麻烦。
• API尽量少，若是一个API能够暴露也能够不暴露，那么就不要暴露他，等到用户真正有需求的时候再将它成为一个公开接口也不迟。
• 支持持续改进，API是否可以方便地经过扩展的方式增长功能和优化。

五、 提升API的可测试性

API须要是可测试的，测试不该依赖实现，测试充分的API，尤为是通过了严格的“兼容性整合测试”的API，更能保证在升级的过程当中不出现兼容性问题。兼容性整合测试，是指一组测试用例集合，这组测试用例会站在使用者的立场上使用API。在API升级之后，再检测这组测试用例是否能彻底符合预期的经过测试，尽量的发现兼容性问题。

六、 保证API的向后兼容

对于每个API的设计者来讲，都渴望作到“向后兼容”，由于无论是如今的API用户，仍是潜在的API用户，都只信任那些可兼容的API。但向后兼容有多个层次上的意义，并且不一样层次的向后兼容，也意味着不一样的重要性和复杂度。

七、 保持逐步改善

过去咱们总但愿能将现有的“不合理”的设计彻底推翻，而后按照如今“美好”的思路，从新设计这个API，可是在一段时间之后，又会碰到同样的情况，须要再推翻一次。 若是咱们没有有效的逐步改善的办法，依靠推翻现有设计，从新设计API只能让咱们回到起点，而后重现以前的过程。 要有一套行之有效的持续改善的办法来在API兼容的同时，改善API使之更好。

八、 把握API的生命周期

每个API都是有生命周期的，咱们须要让API的生命周期更长，而且在API的生命周期结束时能让其平滑的消亡。

• 告诉用户咱们是如何设计的，避免误用，提供指导，错误的使用每每是缩短API寿命的一大杀手
• 提供试用期，API不可能一开始就是稳定，通过试用的API才能有更强的生命力
• 为API分级：内部使用；二次开发使用；开发或试用中；稳定；弃用API。避免API被滥用的同时，咱们能够经过调整API的级别，来扩大其影响力，也能更优雅的结束一个API的生命周期。

开发API的过程其实就是一个沟通交流的过程。沟通的双方就是API用户和API设计者。

九、 一些具体的实施方案

在一个API不可避免要消亡或者改变的时候，咱们应该接受而且面对这个事实，下面列举了几种保证兼容性的前提下，对API进行调整的办法：

• 将API标记为弃用，从新创建一个新的API。若是一个API不可避免要被消亡，这是惟一的办法。
• 为其添加额外的参数或者参数选项来实现功能添加
• 将现有API拆成两部分，提供一个精简的核心API，过去的API经过封装核心API上实现。这一般用于解决用户须要一个代码精简的版本时。
• 在现有的API基础上进行封装，提供一个功能更丰富的包或者类

一些好的API示例：

1. Flickr API，这里是文档的示例，同时提供了一个很是方便的API测试工具。
2. Mediawiki API
3. Ebay API，这里有一个很是详尽的文档示例。

原文连接：http://www.biaodianfu.com/how-to-design-a-good-api.html

 

 

　　在手机普遍流行的今天，手机应用也随之愈来愈多，并且成长的速度也很是快。手机应用软件开发实现方式同普通PC软件同样，也分为BS和CS方式。而采用CS方式，在服务器端大多采用接口的形式提供数据交互(主流数据交互方式有：Json、WebService等)，今天要说的就是如何设计接口。

　　接口做为连通客户端与数据库进行数据流通的桥梁，起着举足轻重的做用，直接影响着程序的效率性、稳定性、可靠性以及数据的正确性、完整性。客户端注重的是界面美观，操做方便顺畅，是用户最直接的感觉体验，而接口则是全部数据的提供者，是用户深层的内涵体验。

　　因次，设计接口在一个项目中，是很是重要的。那么我就目前的经验总结下如何合理设计接口。

　　1、 设计原理

　　1. 深刻了解需求

　　除了设计数据库的人最了解需求外，其次就是设计接口的人了，甚至有时接口开发人员还要参与到数据库设计中。从“客户端-接口-数据库”的层次上看，接口明显扮演着承上启下的角色，一方面要明白接口要什么数据，另外一方面要考虑如何从数据库获取、组织数据。因此若是不了解需求，你就没法正确抽象对象来组织数据给客户端，也没法验证数据库的数据结构可否知足需求。数据库设计者要了解需求中的数据结构，而接口则更多的要了解需求中的逻辑结构以及由此衍生出的逻辑数据结构。

　　2. 了解数据库结构

　　既然接口要明白如何从数据库获取、组织数据，就固然要了解数据库结构啦。

　　3. 了解客户端原型

　　了解原型，其实更可能是为了帮助你设计接口时须要提供的数据和结构。但有时当你设计时并无原型，因此此条并非必需要求的。但假如设计完接口后原型出来了，咱们也能够拿原型还验证接口设计是否正确、合理。

　　2、设计原则

　　1. 充分理由

　　不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，即这个接口的存在是十分有意义额价值的，无心义的接口不只增长了维护的难度，更重要是对于程序的可控性的大大下降，接口也会十分臃肿。所以我放在了第一条。

　　2. 职责明确

　　一个接口只负责一个业务功能，它与设计模式里的职责单一原则相似但却不一样，由于一个业务功能里可能会包含多个操做，好比查询会员，可能除了查询会员表外还要获取该会员的其余必要信息，但不要在查询会员的同时还有修改权限等相似的其余业务功能，应该分红两个接口还作。

　　3. 高内聚低耦合

　　一个接口要包含完整的业务功能，而不一样接口之间的业务关联要尽量的小。仍是查询会员的例子，有时查询会员的同时，可能该会员的相关信息要随之发生变化(如状态)，若是这时一条完整的业务流水线，那么就应该在一个接口里完成，而不该再单独设立接口去操做完成。就是说一个接口不该该随着另外一个变化而变化或以某几个接口为前提而存在。

　　4. 分析角度明确

　　设计接口分析的角度要统一明确。不然会形成接口结构的混乱。例如，不要一会以角色的角度设计，一下子就要以功能的角度设计。

　　5. 入参格式统一

　　全部接口的参数格式要求及风格要统一，不要一个接口参数是逗号分隔，另外一个就是数组;不要一个接口日期参数是x年x月x日风格，另外一个就是x-x-x。

　　6. 状态及消息

　　提供必要的接口调用状态信息。调用是否成功?若是失败，那么失败的缘由是什么。这些必要的信息必需要告诉给客户端。

　　7. 控制数据量

　　一个接口返回不该该包含过多的数据量，过多的数据量不只处理复杂，对数据传输的压力也很是大，会致使客户端反应缓慢。过多的数据量不少时候都是接口划分不明确。

　　8. 禁止随意拓展参数

　　与第1条相似，只不过是针对参数而言了。往后拓展接口多是难以免的，可是不要随意就加参数，加参数必定是必要且有意义的，需求改变前首先应考虑现有接口内部维护是否能知足需求，而不要经过加个参数来方便本身实现需求的难度，由于参数的更变会直接致使客户端调用的变化，容易产生版本兼容性问题。

　　3、设计方法

　　1. 抽象业务

　　相比抽象对象而言，抽象业务更宏观，我以为相对也容易一些，但抽象尺度每每不太好把握。

　　2. 数据格式

　　接口定义的数据格式必须都通过充分考虑，不然会出现数据转换失败或超出长度等错误。若是没法肯定，直接设置成字符串是最合适的。

　　3. 有意义的命名

　　不管是接口仍是参数，名称都应该是有意义的，让人能看明白的。

　　总之，接口设计是一个细致的工做，设计时也会有不少矛盾，但我的倾向于粗粒度设计方向(即内聚性更高一些)，这样不只给客户端浏览接口方便明确，维护也轻松些，这么作的缺点就是某一接口扩展时不是很灵活，但能够经过从新定义一个接口来弥补，但正如上所说，新增接口仍是要三思然后行的。以上不少虽然都是理论性讲解，但紧紧记住这些，并结合实际工做，就会慢慢深入的体会到其中的含义。即理论指导实践，实践来验证理论。

 

转：连接