迷失自我的API

说起API，做开发的人大概都知道也用过，我也是如此。不过除去使用，我还亲眼目睹过API制定，参与搭建过开放API平台，也与合作方商量确定过API方案；算是各个方面都有了解和经历，感受过让人啧啧称奇的赞赏，也经历过举步维艰的尴尬。目睹还有很多同行在API的泥泞里挣扎，我把自己的经验写在这里与大家分享。

大家都知道，API是Application Program Interface，也就是应用程序接口，看起来非常容易理解，实际却并非如此。据我观察，不少API方案之所以陷入了泥潭，就是程序员对API理解错误，把它看成了“对外开放的函数”：某个动作可能之前需要用户鼠标点击触发，现在开个口子给程序用消息触发，这就是API了；推广开来，现在流行的API化、开放平台的潮流，无非是多开一些这样的口子而已。

据我观察，相当多的程序员是这样理解API的。这种理解不能叫错，却往往造成严重的后果。因为它的关注点更侧重“应用程序（Application Program）”，而不是“接口（Interface）”，而两者是有很大差别的：应用程序是一种具体的实现，说到应用程序往往想到的是代码，它是具体、容易理解的；而接口是对抽象行为的封装，说到接口，往往想到的是某个动作，是虚拟、不那么好理解的。此外，接口还蕴含了“解耦合”的意义：应用程序往往是知根知底的“内部人交易”，出了问题也很好变通解决，接口却要暴露给未知的外部世界，只能依靠相对固定的规范加以约束。更重要的是，接口往往会影响甚至塑造外部调用方对系统的认知，在调用方看来，系统对外提供了几个接口，可能就只有几个环节（或几个方面）。如果对接口的理解不到位，开发出来的API往往是残缺的，根据接口（Interface）的首字母I在英语中的意思，我把这类API称为“迷失自我的API”。

举个真实的例子，我们常见的表单填写功能，为了保证用户体验，往往会把整个填写分为几步依次进行。相应的，后台有方法对应每一步的处理。为了提供API，程序员直接把后台每一步的处理包装暴露出来，而没有想到应当“填写表单”是逻辑意义完整独立的操作，之前拆分开来只是为了保证直接交互的体验，结果客户端应用程序在调用时，也不得不把整张表单拆开了分次调用，这样的API既没有效率又没有准确性。

再举个例子，在某个界面上客户可以选择确定的服务，原有系统里表示服务的是枚举类型，因为都是项目内部调用，所以没有问题。提供API时，程序员直接把这些参数和类型通过WSDL暴露出去，初期用起来一切正常，不久就问题丛生：因为服务的种类经常随业务变化，枚举类型本身也会变化，内部更新并不是大问题，客户调用起来则痛苦不堪，哪怕服务的值没有变化，也必须重新编译。

以上两例，都可归类为迷失自我的API，因为都是对接口的理解不到位：第一例是没有设定合适的粒度，第二例是没有设定信息隔离的合理边界。在实际开发中，这样的例子还有很多，结果都是浪费了大量的人力物力（让API调用方跳起脚来大骂的情况也屡见不鲜）。根据我的思考，要避免这类情况，可以从以下几方面采取措施。

第一，要重视API，抽调最好的开发人员负责API。在许多团队里，开发API被视作脏活累活，交给开发能力一般甚至比较弱的人员去开发，这一点是要严格杜绝的。API的设计和开发是一项要求很高的工作，如前文所说，负责人员要理解每个API对应的逻辑意义以便合理划分粒度，还需要根据实际情况进行合理的隔离。更重要的，相对普通的函数调用，API的调试和报错都需要精心设计。我见过很多程序员随便应付错误处理甚至干脆一股脑扔给虚拟机，这种水平去设计API只会让调用方欲哭无泪，最终还可能搬起石头砸自己的脚。如果抽调了最好的开发人员负责API，哪怕内部暂时逊色一点，稍后也可以改过来，这个道理反过来则不成立——用优雅接口包装起来的龌龊实现，通常强过龌龊接口包装起来的优雅实现。

第二，自己开发的API要自己调用。软件开发行业有句话叫“吃自己的狗粮”，意思是自己做的程序自己用，才能真正知道自己做的如何，API也是如此。难用的API通常有个共同特点，就是开发API的人自己是不用的，对他们来说纯粹是摆设，所以他们无法设身处地评判API的好坏，发现有问题也没有动力去改善，即便有压力去改善，也往往难以找到合适的切入点，向合适的方向推进。实际上，目前很多项目已经实现了内部API化，自己调用自己的API已经是必须的选择，这时候开放API也变得易如反掌。我相信这是一种好的架构方式，值得推广开来。

第三，API是有章可循的，借鉴现成的成功经验会少走很多弯路。API的设计和开发虽然是一项要求很高的工作，但经验并不是要求的全部；目前已经有了很多论述API的文档资料，涵盖了从实现到架构的各个方面；业界也有许多公认的规范优秀的API，很多领域都可以找到API的榜样（FourSquare、Twitter、Facebook，都是很好的样板）。如果能多加学习，多加思考，甚至稍加思索直接照搬，都会比自己盲目设计开发要好很多（国内的一些直接照搬国外的API至少像个样子，许多“自主设计”的反而非常糟糕）。

说句玩笑话，API没有了I，就“迷失了自我”。正是众多迷失自我的所谓“API”，给广大程序员造成了无穷无尽的困扰。我衷心希望这种境况能早日得到解决。