还在盲目的写代码？API接口设计原则和方法你可能都不知道

点选下方“软件开发者街道社区标为隆哥蒙”

第一天数送抵新颖蔬果

一旦API发生改变，就可能将对有关的分配器增添巨大的付出，采用者须要摸查大部份初始化的标识符，须要调整大部份与之有关的部分，那些组织工作对她们而言都是附加的。假如好不容易完成那些以后，还发现了有关的bug，那对采用者的打击就Villamblard。假如API经常发生改变，采用者就会丧失对提供更多方丧失信心，从而也会影响目前的业务。

但她们为什么还要修正API呢？为的是API看上去更加很漂亮？为的是提供更多更多用途？为的是提供更多更快的性能？还是仅仅觉得到了改变了这时候了？对采用者而言，她们更愿意采用两个稳定但看上去不所以流行时尚的API，这并不意味著她们不再改良API了。当差劲的API带来的维护成本越来越是定值，我想就是她们去解构它的这时候。

假如能回头重新再做两遍，所以我心目中的杰出的API如果是好不好的？

推论两个API与否杰出，并不是简单地根据第两个版得出推论的，而是要看随着天数的流逝，该API与否还能存在，与否依旧保持得不错。槽糕的APIUSB各式各样，但好的APIUSB对采用者而言必须满足以下几个点：

易自学：有完善的文件格式及提供更多尽量将多的实例和可copy－paste的标识符，像其他结构设计组织工作那样，你如果应用最轻吃惊准则 [1]。

Rapidshare：没有繁杂的程序、繁杂的技术细节，更易自学；灵巧的API允许按表头次序、可自订巨集、次序和甄选等。两个完备的API意味著被期许的功能都包涵在内。

难误用：对详尽的严重错误提示信息，有些经验的采用者能直接采用API而不须要写作文件格式。

而对开发者而言，要求又是不那样的：

易写作：标识符的撰写只须要一场一场，但当增容或者修正的这时候都须要对标识符进行写作。

易开发：个最轻化的USB是采用尽量将少的类以及尽量将少的类成员。这样使得理解、记忆、增容以及改变API更容易。

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

1、面向用例结构设计

假如两个API被广泛采用了，所以就不可能将了解大部份使用该API的采用者。假如结构设计者希望能够结构设计出被广泛采用的API，所以必须站在采用者的角度来理解如何结构设计API库，以及如何才能结构设计出这样的API库。

2、采用良好的结构设计思路

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

面向用例的结构设计，收集采用者建议，把自己模拟成采用者，保证API结构设计的易用和合理

保证后续的需求能通过扩展的形式完成

第一版做尽量少的内容，由于新需求能通过扩展的形式完成，因此尽量少做事情是抑制API结构设计严重错误的两个有效方案

对外提供更多清晰的API和文件格式规范，避免采用者严重错误的采用API，尤其是避免API（见第一节）靠后级别的API被采用者知晓与误为

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

方法优于属性

工厂方法优于构造函数

避免过多继承

避免由于优化或者复用标识符影响API

面向USB编程

扩展参数应当是便利的

对组件进行合理定位，确定暴露多少USB

提供更多扩展点

3、避免极端的意见

在结构设计API的这时候，一定要避免任何极端的意见，尤其是以下几点：

必须很漂亮（API不一定须要很漂亮）

API必须被正确地采用（采用者很难理解如何正确的采用API，API的结构设计者要充分考虑API被误为的情况：假如两个API可能会被误为，所以它一定会被误为）

必须简单（她们总会面临繁杂的需求，能两者兼顾的API是更快的API）

必须高性能（性能能通过其他手段优化，不如果影响API的结构设计）

必须绝对兼容（尽管本文一直提到如何保证兼容，但她们仍然要意识到，一些极少情况下会遇到的不兼容是能容忍的）

4、有效的API评审

API结构设计完成以后，须要经过周密的结构设计评审，评审的重点如下：

用例驱动，评审前必须提供更多完善的采用用例，确保用例的合理性和完备性。

一致性，与否与系统中其他模块的USB风格一致，与否与对称USB的结构设计一致。

简单明了，API如果简单好理解，容易自学和采用的API才不容易被误为，给她们增添更多的麻烦。

API尽量将少，假如两个API能暴露也能不暴露，所以就不要暴露他，等到采用者真正有需求的这时候再将它成为两个公开USB也不迟。

支持持续改良，API与否能够方便地通过扩展的方式增加功能和优化。

5、提高API的可测试性

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

6、保证API的向后兼容

对每两个API的结构设计者而言，都渴望做到“向后兼容”，因为不管是现在的API采用者，还是潜在的API采用者，都只信任那些可兼容的API。但向后兼容有多个层次上的意义，而且不同层次的向后兼容，也意味著不同的重要性和繁杂度。

7、保持逐步改善

过去她们总希望能将现有的“不合理”的结构设计完全推翻，然后按照现在“美好”的思路，重新结构设计这个API，但在一段天数以后，又会碰到那样的状况，须要再推翻一场。假如她们没有有效的逐步改善的办法，依靠推翻现有结构设计，重新结构设计API只能让她们回到起点，然后重现之前的过程。要有一套行之有效的持续改善的办法来在API兼容的同时，改善API使之更快。

8、把握API的生命周期

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

告诉采用者她们是如何结构设计的，避免误为，提供更多指导，严重错误的采用往往是缩短API寿命的一大杀手

提供更多试用期，API不可能将一开始就是稳定，经过试用的API才能有更强的生命力

为API分级：内部采用；二次开发采用；开发或试用中；稳定；弃用API。避免API被滥用的同时，她们能通过调整API的级别，来扩大其影响力，也能更优雅的结束两个API的生命周期。

开发API的过程其实就是两个沟通交流的过程。沟通的双方就是API采用者和API结构设计者。

9、一些具体的实施方案

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

将API标记为弃用，重新建立两个新的API。假如两个API不可避免要被消亡，这是唯一的办法。

为其添加附加的参数或者参数选项来实现功能添加

将现有API拆成两部分，提供更多两个精简的核心API，过去的API通过封装核心API上实现。这通常用于解决采用者须要两个标识符精简的版时。

在现有的API基础上进行封装，提供更多两个功能更丰富的包或者类

一些好的API实例：

Flickr API [2]，这里是文件格式的实例 [3]，同时提供更多了两个非常方便的API测试工具 [4]。

Mediawiki API [5]

Ebay API [6]，这里有两个非常详尽的文件格式实例 [7]。

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

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

因此，结构设计USB在两个项目中，是非常重要的。所以我就目前的经验总结下如何合理结构设计USB。

一、结构设计原理

1. 深入了解需求

除了结构设计数据库的人最了解需求外，其次就是结构设计USB的人了，甚至有时USB开发者还要参与到数据库结构设计中。从“客户端-USB-数据库”的层次上看，USB明显扮演着承上启下的角色，一方面要明白USB要什么数据，另一方面要考虑如何由此衍生出的逻辑数据结构。

2. 了解数据库结构

3. 了解客户端原型

了解原型，其实更多是为的是帮助你结构设计USB时须要提供更多的数据和结构。但有时当你结构设计时并没有原型，所以此条并不是必须要求的。但假如结构设计完USB后原型出来了，她们也能拿原型还验证USB结构设计与否正确、合理。

二、结构设计准则

1. 充分理由

不是随便两个功能就要有个USB，也不是随便两个需求就要加个USB。每新建两个USB，就要有充分的理由和考虑，即这个USB的存在是十分有意义价值的，无意义的USB不仅增加了维护的难度，更重要是对程序的可控性的大大降低，USB也会十分臃肿。因此我放在了第一条。

2. 职责明确

的同时还有修正权限等类似的其他业务功能，如果分成两个USB还做。

3. 高内聚低耦合

两个USB要包涵完备的业务功能，而不同USB之间的业务关联要尽量将的小。还是查询会员的例子，有时查询会员的同时，可能将该会员的有关信息要随之发生改变(如状态)，假如这时一条完备的业务流水线，所以就如果在两个USB里完成，而不应再单独设立USB去操作完成。就是说两个USB不如果随着另两个变化而变化或以某几个USB为前提而存在。

4. 分析角度明确

结构设计USB分析的角度要统一明确。否则会造成USB结构的混乱。例如，不要一会以角色的角度结构设计，一会儿就要以功能的角度结构设计。

5. 入参格式统一

大部份USB的参数格式要求及风格要统一，不要两个USB参数是逗号分隔，另两个就是数组;不要两个USB日期参数是x年x月x日风格，另两个就是x-x-x。

6. 状态及消息

提供更多必要的USB初始化状态信息。初始化与否成功?假如失败，所以失败的原因是什么。那些必要的信息必须要告诉给客户端。

7. 控制数据量

两个USB返回不如果包涵过多的数据量，过多的数据量不仅处理繁杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多这时候都是USB划分不明确。

8. 禁止随意拓展参数

与第1条类似，只不过是针对参数而言了。日后拓展USB可能将是难以避免的，但不要随意就加参数，加参数一定是必要且有意义的，需求改变前首先应考虑现有USB内部维护与否能满足需求，而不要通过加个参数来方便自己实现需求的难度，因为参数的更变会直接导致客户端初始化的变化，容易产生版兼容性问题。

三、结构设计方法

1. 抽象业务

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

2. 数据格式

USB定义的数据格式必须都经过充分考虑，否则会出现数据转换失败或超出长度等严重错误。假如无法确定，直接设置成字符串是最合适的。

3. 有意义的命名

无论是USB还是参数，名称都如果是有意义的，让人能看明白的。

总之，USB结构设计是两个细致的组织工作，结构设计时也会有很多矛盾，但个人倾向于粗粒度结构设计方向(即内聚性更高一些)，这样不仅给客户端浏览USB方便明确，维护也轻松些，这么做的缺点就是某一USB扩展时不是很灵巧，但能通过重新定义两个USB来弥补，但正如上所说，新增USB还是要三思而后行的。以上很多虽然都是理论性讲解，但牢牢记住那些，并结合实际组织工作，就会慢慢深刻的体会到其中的含义。即理论指导实践，实践来验证理论。

作者小记：

接口结构设计遵循准则：

1、USB统一性：避免乱加，重复加

后果就是标识符变得繁杂，难以管理，乃至对数据库造成不必要的消耗或影响。

2、USB结构设计不做太多的组合，尽量小而精

一方面，降低繁杂度，另一方面，三方能自由组合实现多种所需，且减少双方都开发。

3、尽量预留查询基本元素USB，查询实体大部份表头USB；

4、组合查询返回详情信息

或特定业务，或相对繁杂业务，或频繁查询，或其中部分查询没有必要封装USB的（或私密性的）

批注链接：

http://en.wikipedia.org/wiki/Principleofleast_astonishment

http://www.flickr.com/services/api/