日期:2013-06-20  浏览次数:20553 次

文章描述:本文次要引见什么是API,以及API兼容的重要性,最终给出方案如何评估API,以及如何做到API兼容。

本文次要引见什么是API,以及API兼容的重要性,最终给出方案如何评估API,以及如何做到API兼容。

What’s API?

API的全称是application programming interface。

而很多时候,程序开发者仅仅把函数、类的接口做为API的一部分,而忽略了其他重要的编程接口。

理想上,在前端Javscript编程中常见的API包括:

  • 函数、类接口,包括参数,前往值,函数对外部对象(常常是DOM)的具体操作等
  • 网络接口协议,如和后端交互的JSON、XML数据格式,或者script回调中的函数名
  • 款式以及HTML接口
  • 外部依赖(对浏览器具体特性的依赖)
  • 一些无意泄露的内部实现

越往后的API,越隐晦,越不容易遭到注重,但是一旦这些API发生变化,可能会导致调用方出现不符合预期甚至程序直接报错的情况。

Why API cannot be changed?

API是程序协同开发的重要保证,API的用户希望API的提供方提供的是一段功用明确、接口明了的程序。更重要的是,用户更期望在程序升级当前,他们能够“不经思考”地升级这些第三方代码。

一旦上述提到的5个API中的任何一个发生变化,可能会给他们带来巨大的代价,用户需求排查所有调用的代码,需求更改一些协议,需求调整所有与之相关的部分,这些任务对他们来说都是额外的,在预期之外的。如果辛辛劳苦完成这些当前,还在测试过程中发现了相关的bug,那对用户的打击就更大了。

如果API经常发生变化,用户就会得到对这段程序的信任,他们会更倾向本人获得源代码当前,按照本人的需求进行修正,自行维护一个内部的API比调用一个不断发生变化的外部API要容易接受的多,虽然这样做和我们协同开发、模块化开发的初衷是完全相悖的。

最后,我们为什么要修正API呢?为了API看起来愈加漂亮?为了提供更多风趣的功用?还是仅仅我们觉得到了改变了时候了?对于用户来说,他们更情愿使用一个稳定但是看起来不那么时髦的API,而不是使用一个很时髦,但是会经常变动的API。在这个问题上,项目开发者是实用派。但这并不意味着我们不再改进API了,在后面,我会具体引见如何能让API保持稳定的同时,让API持续改进。

Quality of API

在正式说兼容性之前,首先要明确一下,什么是好的API,由于导致API的不兼容的本源总是来自一个想法:“期望通过这次改变把API变得更好”。

容易理解
如果一个API不能让大多数使用者快速学会,这一定不是一个好的API。 比如iOS的滑动解锁,老人和小孩都能都能一次解锁,而Nokia的经典两键解锁,你懂的。

分歧性
分歧功用大大降低用户的学习和使用成本,用户过去的努力学习,能持续的收效。

容易查找和学习
API必需要有文档,并且引见清晰,提供尽可能多的示例和可copy-paste的代码,降低用户的使用门槛。

提供简单的方案
API要能处理复杂的问题,提供很多可配置项,但是对于那些最常见的case,如果有一个简单的方案供应用户使用,这样能大大提高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可能