开发接口的正确姿势

背景

在这个SOA都已经成为过时概念的年代，为什么还要写一篇文章来讲述接口开发呢？

这个问题很难一两句话解释清楚，打个简单的比方，这个问题就好比在问：现今智能手机、即时通讯工具都已经普及了，为什么还要写一篇文章来讲述如何沟通呢？

是的，SOA、REST以及各种五花八门的RPC技术，都只是进行系统间集成的技术实现，这方面技术发展已经足够繁荣了，但是作为问题的本质——接口本身，如何去设计 如何描述 如何治理却较少被关注。 本文正是针对这个主题。

现状

先来看一下目前在软件开发现实世界中，典型的接口开发过程是什么样的：

• 首先 一个接口的需求被提出：某天，在一个大型组织内的某个IT项目A，一个开发人员甲在分析业务部门的刚刚发来的需求S时发现，需要从项目B处获取几类数据；
• 然后发起项目组间沟通协调：于是甲以正式或非正式方式 召集两个项目组相关人员进行沟通讨论，确认项目B能否提供数据、如何提供、何时开始提供；此时实际上就是在确定接口的大致规格（主要字段信息）、技术实现（同步or异步 协议。。。）和开发进度；
• 会后，工作一向认真负责的甲 按例发出会议纪要，将双方商定的技术细节发出来确认，并作为下一步开发工作的基础；
• 由于业务部门要求尽快上线该需求，小甲把这个接口安排到了两周后的最近一次发布，于是发完邮件就离开开始起草接口规格文档，大概像下面这样的文档：
• 两天后 接口文档基本定稿，发给项目组B，双方的开发人员立刻开始了开发工作，这个所谓的开发工作主要包括：
  • 把接口文档中描述的那些数据结构和字段翻译成JavaBean、双方开发人员各自翻译自己那部分接口模型；
  • 序列化与反序列化
  • 分别实现客户端、服务端业务逻辑——服务端返回特定数据，客户端对返回的结果进行处理；当然跨系统获取数据，只是常见接口之一，另外还有远程过程调用（事务性操作），不过从技术上没有本质区别；
• 联调测试
• 上线发布

问题

但是现实世界中 事情没有这么简单，由于普遍存在的熵增原理，很多时候看似简单的事情在达到一定量 在较长时间范围内就会不知不觉的变得复杂最后失控。

就像项目代码，用的都是面向对象高级语言，各种号称灵活可扩展的技术架构和框架，但是几乎所有项目都很不可避免的变成一团乱麻，统计显示，软件项目的失败率依然很高，没有随着这几十年的技术进步而有任何起色，软件危机其实一直没有结束。这里不展开论述了。

具体到接口，为什么在数量增加 时间推移之后 就会很快变乱失控呢？是什么引起了熵快速增加？

根据我的观察和分析，问题出在接口定义上面——普遍采用的文档定义接口的做法 为日后的危机埋下隐患。