标签：
一旦API发生变化，就可能对相关的调用者带来巨大的代价，用户需要排查所有调用的代码，需要调整所有与之相关的部分，这些工作对他们来说都是额外的。如果辛辛苦苦完成这些以后，还发现了相关的bug，那对用户的打击就更大。如果API经常发生变化，用户就会失去对提供方失去信心，从而也会影响目前的业务。
但是我们为什么还要修改API呢？为了API看起来更加漂亮？为了提供更多功能？为了提供更好的性能？还是仅仅觉得到了改变了时候了？对于用户来说，他们更愿意使用一个稳定但是看起来不那么时髦的API，这并不意味着我们不再改进API了。当糟糕的API带来的维护成本越来越大时，我想就是我们去重构它的时候。
如果可以回头重新再做一遍，那么我心目中的优秀的API应该是怎么样的？
判断一个API是否优秀，并不是简单地根据第一个版本给出判断的，而是要看随着时间的推移，该API是否还能存在，是否仍旧保持得不错。槽糕的API接口各种各样，但是好的API接口对于用户来说必须满足以下几个点：
而对于开发人员来说，要求又是不一样的：
如何做到以上几点，以下是一些总结：
1、 面向用例设计
如果一个API被广泛使用了，那么就不可能了解所有使用该API的用户。如果设计者希望能够设计出被广泛使用的API，那么必须站在用户的角度来理解如何设计API库，以及如何才能设计出这样的API库。
2、 采用良好的设计思路
在设计过程中，如果能按照下面的方式来进行设计，会让这个API生命更长久
除此之外，下面还列出了一些具体的设计方法：
3、 避免极端的意见
在设计API的时候，一定要避免任何极端的意见，尤其是以下几点：
4、 有效的API评审
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设计者。
9、 一些具体的实施方案
在一个API不可避免要消亡或者改变的时候，我们应该接受并且面对这个事实，下面列举了几种保证兼容性的前提下，对API进行调整的办法：
一些好的API示例：
原文链接：http://www.biaodianfu.com/how-to-design-a-good-api.html
在手机广泛流行的今天，手机应用也随之越来越多，而且成长的速度也非常快。手机应用软件开发实现方式同普通PC软件一样，也分为BS和CS方式。而采用CS方式，在服务器端大多采用接口的形式提供数据交互(主流数据交互方式有：Json、WebService等)，今天要说的就是如何设计接口。
接口作为连通客户端与数据库进行数据流通的桥梁，起着举足轻重的作用，直接影响着程序的效率性、稳定性、可靠性以及数据的正确性、完整性。客户端注重的是界面美观，操作方便顺畅，是用户最直接的感受体验，而接口则是所有数据的提供者，是用户深层的内涵体验。
因次，设计接口在一个项目中，是非常重要的。那么我就目前的经验总结下如何合理设计接口。
一、 设计原理
1. 深入了解需求
除了设计数据库的人最了解需求外，其次就是设计接口的人了，甚至有时接口开发人员还要参与到数据库设计中。从“客户端-接口-数据库”的层次上看，接口明显扮演着承上启下的角色，一方面要明白接口要什么数据，另一方面要考虑如何从数据库获取、组织数据。所以如果不了解需求，你就无法正确抽象对象来组织数据给客户端，也无法验证数据库的数据结构能否满足需求。数据库设计者要了解需求中的数据结构，而接口则更多的要了解需求中的逻辑结构以及由此衍生出的逻辑数据结构。
2. 了解数据库结构
既然接口要明白如何从数据库获取、组织数据，就当然要了解数据库结构啦。
3. 了解客户端原型
了解原型，其实更多是为了帮助你设计接口时需要提供的数据和结构。但有时当你设计时并没有原型，所以此条并不是必须要求的。但假如设计完接口后原型出来了，我们也可以拿原型还验证接口设计是否正确、合理。
二、设计原则
1. 充分理由
不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。每新建一个接口，就要有充分的理由和考虑，即这个接口的存在是十分有意义额价值的，无意义的接口不仅增加了维护的难度，更重要是对于程序的可控性的大大降低，接口也会十分臃肿。因此我放在了第一条。
2. 职责明确
一个接口只负责一个业务功能，它与设计模式里的职责单一原则类似但却不同，因为一个业务功能里可能会包含多个操作，比如查询会员，可能除了查询会员表外还要获取该会员的其他必要信息，但不要在查询会员的同时还有修改权限等类似的其他业务功能，应该分成两个接口还做。
3. 高内聚低耦合
一个接口要包含完整的业务功能，而不同接口之间的业务关联要尽可能的小。还是查询会员的例子，有时查询会员的同时，可能该会员的相关信息要随之发生变化(如状态)，如果这时一条完整的业务流水线，那么就应该在一个接口里完成，而不应再单独设立接口去操作完成。就是说一个接口不应该随着另一个变化而变化或以某几个接口为前提而存在。
4. 分析角度明确
设计接口分析的角度要统一明确。否则会造成接口结构的混乱。例如，不要一会以角色的角度设计，一会儿就要以功能的角度设计。
5. 入参格式统一
所有接口的参数格式要求及风格要统一，不要一个接口参数是逗号分隔，另一个就是数组;不要一个接口日期参数是x年x月x日风格，另一个就是x-x-x。
6. 状态及消息
提供必要的接口调用状态信息。调用是否成功?如果失败，那么失败的原因是什么。这些必要的信息必须要告诉给客户端。
7. 控制数据量
一个接口返回不应该包含过多的数据量，过多的数据量不仅处理复杂，对数据传输的压力也非常大，会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。
8. 禁止随意拓展参数
与第1条类似，只不过是针对参数而言了。日后拓展接口可能是难以避免的，但是不要随意就加参数，加参数一定是必要且有意义的，需求改变前首先应考虑现有接口内部维护是否能满足需求，而不要通过加个参数来方便自己实现需求的难度，因为参数的更变会直接导致客户端调用的变化，容易产生版本兼容性问题。
三、设计方法
1. 抽象业务
相比抽象对象而言，抽象业务更宏观，我觉得相对也容易一些，但抽象尺度往往不太好把握。
2. 数据格式
接口定义的数据格式必须都经过充分考虑，否则会出现数据转换失败或超出长度等错误。如果无法确定，直接设置成字符串是最合适的。
3. 有意义的命名
无论是接口还是参数，名称都应该是有意义的，让人能看明白的。
总之，接口设计是一个细致的工作，设计时也会有很多矛盾，但个人倾向于粗粒度设计方向(即内聚性更高一些)，这样不仅给客户端浏览接口方便明确，维护也轻松些，这么做的缺点就是某一接口扩展时不是很灵活，但可以通过重新定义一个接口来弥补，但正如上所说，新增接口还是要三思而后行的。以上很多虽然都是理论性讲解，但牢牢记住这些，并结合实际工作，就会慢慢深刻的体会到其中的含义。即理论指导实践，实践来验证理论。
转：链接
标签：
原文地址：http://www.cnblogs.com/SharkBin/p/5081715.html
