摘要: 到目前为止，已经负责 API 接近两年了，这两年中发现现有的 API 存在的问题越来越多，但很多 API 一旦发布后就不再能修改了，即时升级和维护是必须的。一旦 API 发生变化，就可能对相关的调用者带来巨大的代价，用户 …

到目前为止，已经负责 API 接近两年了，这两年中发现现有的 API 存在的问题越来越多，但很多 API 一旦发布后就不再能修改了，即时升级和维护是必须的。一旦 API 发生变化，就可能对相关的调用者带来巨大的代价，用户需要排查所有调用的代码，需要调整所有与之相关的部分，这些工作对他们来说都是额外的。如果辛辛苦苦完成这些以后，还发现了相关的 bug，那对用户的打击就更大。如果 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 基础上进行封装，提供一个功能更丰富的包或者类

来源:apkbus