说起来，提供API供客户端调用，已经都做了两年多了，这两年多里，辛酸泪一把，API上线后，随着客户端版本的不停升级，功能越做越多，API越来越复杂，这时候，你TMD还得兼容旧系统，一点点的累积，过了半年，一看，还有N多人在用旧系统，想死的心都有了。开新接口？旧接口就不管了？这也不是一个办法。。。
所以，看到这篇文章的时候，我转一下，顺便自己也学一下，别人说的不一定就是对的，偏听则暗，兼听则明嘛 。（作者提供的API和我提供的不算一致，但也差不了很多，原来。。。。都是两年多，被这两年折腾的吧？）
原文来自：http://www.biaodianfu.com/how-to-design-a-good-api.html
到目前为止，已经负责API接近两年了，这两年中发现现有的API存在的问题越来越多，但很多API一旦发布后就不再能修改了，即时升级和维护是必须的。一旦API发生变化，就可能对相关的调用者带来巨大的代价，用户需要排查所有调用的代码，需要调整所有与之相关的部分，这些工作对他们来说都是额外的。如果辛辛苦苦完成这些以后，还发现了相关的bug，那对用户的打击就更大。如果API经常发生变化，用户就会失去对提供方失去信心，从而也会影响目前的业务。
但是我们为什么还要修改API呢？为了API看起来更加漂亮？为了提供更多功能？为了提供更好的性能？还是仅仅觉得到了改变了时候了？对于用户来说，他们更愿意使用一个稳定但是看起来不那么时髦的API，这并不意味着我们不再改进API了。当糟糕的API带来的维护成本越来越大时，我想就是我们去重构它的时候。
如果可以回头重新再做一遍，那么我心目中的优秀的API应该是怎么样的？
判断一个API是否优秀，并不是简单地根据第一个版本给出判断的，而是要看随着时间的推移，该API是否还能存在，是否仍旧保持得不错。槽糕的API接口各种各样，但是好的API接口对于用户来说必须满足以下几个点：
- 易学习：有完善的文档及提供尽可能多的示例和可copy－paste的代码，像其他设计工作一样，你应该应用最小惊讶原则。
- 易使用：没有复杂的程序、复杂的细节，易于学习；灵活的API允许按字段排序、可自定义分页、 排序和筛选等。一个完整的API意味着被期望的功能都包含在内。
- 难误用：对详细的错误提示，有些经验的用户可以直接使用API而不需要阅读文档。
而对于开发人员来说，要求又是不一样的：
- 易阅读：代码的编写只需要一次一次，但是当调试或者修改的时候都需要对代码进行阅读。
- 易开发：个最小化的接口是使用尽可能少的类以及尽可能少的类成员。这样使得理解、记忆、调试以及改变API更容易。
如何做到以上几点，以下是一些总结：
1、 面向用例设计
如果一个API被广泛使用了，那么就不可能了解所有使用该API的用户。如果设计者希望能够设计出被广泛使用的API，那么必须站在用户的角度来理解如何设计API库，以及如何才能设计出这样的API库。
2、 采用良好的设计思路
在设计过程中，如果能按照下面的方式来进行设计，会让这个API生命更长久
- 面向用例的设计，收集用户建议，把自己模拟成用户，保证API设计的易用和合理
- 保证后续的需求可以通过扩展的形式完成
- 第一版做尽量少的内容，由于新需求可以通过扩展的形式完成，因此尽量少做事情是抑制API设计错误的一个有效方案
- 对外提供清晰的API和文档规范，避免用户错误的使用API，尤其是避免API（见第一节）靠后级别的API被用户知晓与误用
除此之外，下面还列出了一些具体的设计方法：
- 方法优于属性
- 工厂方法优于构造函数
- 避免过多继承
- 避免由于优化或者复用代码影响API
- 面向接口编程
- 扩展参数应当是便利的
- 对组件进行合理定位，确定暴露多少接口
- 提供扩展点
3、 避免极端的意见
在设计API的时候，一定要避免任何极端的意见，尤其是以下几点：
- 必须漂亮（API不一定需要漂亮）
- API必须被正确地使用（用户很难理解如何正确的使用API，API的设计者要充分考虑API被误用的情况：如果一个API可能会被误用，那么它一定会被误用）
- 必须简单（我们总会面临复杂的需求，能两者兼顾的API是更好的API）
- 必须高性能（性能可以通过其他手段优化，不应该影响API的设计）
- 必须绝对兼容（尽管本文一直提到如何保证兼容，但是我们仍然要意识到，一些极少情况下会遇到的不兼容是可以容忍的）
4、 有效的API评审
API设计完成以后，需要经过周密的设计评审，评审的重点如下：
- 用例驱动，评审前必须提供完善的使用用例，确保用例的合理性和完备性。
- 一致性，是否与系统中其他模块的接口风格一致，是否与对称接口的设计一致。
- 简单明了，API应该简单好理解，容易学习和使用的API才不容易被误用，给我们带来更多的麻烦。
- API尽可能少，如果一个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才能有更强的生命力
- 为API分级：内部使用；二次开发使用；开发或试用中；稳定；弃用API。避免API被滥用的同时，我们可以通过调整API的级别，来扩大其影响力，也能更优雅的结束一个API的生命周期。
开发API的过程其实就是一个沟通交流的过程。沟通的双方就是API用户和API设计者。
9、 一些具体的实施方案
在一个API不可避免要消亡或者改变的时候，我们应该接受并且面对这个事实，下面列举了几种保证兼容性的前提下，对API进行调整的办法：
- 将API标记为弃用，重新建立一个新的API。如果一个API不可避免要被消亡，这是唯一的办法。
- 为其添加额外的参数或者参数选项来实现功能添加
- 将现有API拆成两部分，提供一个精简的核心API，过去的API通过封装核心API上实现。这通常用于解决用户需要一个代码精简的版本时。
- 在现有的API基础上进行封装，提供一个功能更丰富的包或者类
一些好的API示例：
- Flickr API，这里是文档的示例，同时提供了一个非常方便的API测试工具。
- Mediawiki API
- Ebay API，这里有一个非常详尽的文档示例。
.png)
