导读

• 背景
• 痛点
• 协同开发文档
• API规范
• 工具,工具
• 后记

背景

随着业务的发展,研发团队的项目也是越来越多。同时,项目架构体系的扩展,我们对系统业务水平拆分,垂直分层,让业务系统更加清晰,产生了一系列平台和子系统,并使用接口进行数据交互。

在公司业务快速增加和迭代的过程中,只有顺应形势,采取"中台战略",构建符合DT时代的更具创新性、灵活性的“大中台，小前台”组织机制和业务机制，即作为前台的一线业务会更敏捷、更快速适应瞬息万变的市场，而中台将整合公司的运营数据能力、产品技术能力,对各前台业务形成强有力的支撑。 而笔者认为，"中台战略"的落地就在于将业务进行拆分,然后通过开放接口,为更多的业务系统"赋能"，从而真正建立起共享服务体系。

痛点

我们运营和维护着诸多的对外接口,很多现有的接口服务寄宿在各个不同的项目,哪些应用在使用api也没有管理起来。并且以前的调用模式，加密方式都有各自风格,从长期来看,维护和排错困难。

每次和其他同事合作，对方都会要求给出api文档,特别是开发完成的api接口,往往解释半天,大家也很痛苦。新接口还好,可以制作一个文档,可以解决一时的问题。

或许有的开发部门有很好的习惯,每次开发都会有要求写开发文档,接口文档等。但是我们知道,很多接口是不同人在不同时间添加和维护的,信息不同步,也会造成越来越多的问题。

以下是总结的几个痛点:

• 没有接口文档
  • 接口在代码里,只能看代码
• 没有集中的的api项目
  • 相同业务的api分散在不同的项目
  • 查找困难
• 代码和文档不匹配
  • 代码接口更新,文档不更新
• 文档不规范
  • 有的是word,有的是excel,有的是txt等等
• api不规范
  • 命名,参数不规范

     撸码一分钟,对接三小时

协同开发文档

真正优秀的团队,是通过协同充分发挥出每个成员的能力。这就需要倡导和形成团队文化，让整个团队能够有强大的凝聚力。那么,这期间必须形成一些标准和规范。而API接口相关的规范和文档就是很重要的一环。

• 统一的文档管理平台
• 规范的API规范
• 统一的对接模式

API规范

这里也是见仁见智,但是我认为一个团队最好有统一的API规范。特别是同一个项目的编码风格,不管多少人参与,风格上要保持一致。我相信,很多人开发人员都会有"代码洁癖",没有人愿意看到那种"辣眼睛"的代码。

• 接口名称
  • 这里统一使用小写 如:api/order/get
  • 可参考跟着Github学习Restful HTTP API 设计
• uri
  • 提供客户端使用的全路径
  • 如http://172.16.0.194:8057/api/order/get
• 请求协议
  • Http,Https
• 请求方式
  • POST,GET等
• 头部(系统参数)
  • 加密签名,时间戳等

• 请求参数(业务)

  • 业务相关的输入参数

• 响应参数(业务)

  • 输出参数

• 返回示例

  定义返货结果数据结构,更直观

  • 1.返回成功
  • 2.返回失败

这里给一张图来说明,

工具,工具

工欲善其事,必先利其器。带着需求,去google了一下,果然有现成的开源工具(当然如果有时间我还是觉得可以自己开发一套)。同类工具对比之后,发现eolinker比较好用。

• 整体全貌

       整个系统风格简洁,还有点小清新的感。页面功能布局合理,完全不用培训就知道么使用。

• 协作管理

  如同现在的很多在线工具一样,如tower,processon, eolinker也提供了团队协作功能。

• 新建项目

• 查看明细

  

  

后记

项目中使用restfulapi的情况较多,webservice,wcf,webapi均支持，所以这里该规范重点针对resfulapi。

经过多个项目的API协同开发,实践证明,有了规范更能减少沟通成本,让参与的人真正协同起来,提高工作效率。

eolinker是一个开源的接口管理工具(github上源码),可以自己搭建在自己的服务器上使用。当然,如果要使用更多功能,可以购买付费版本。

参考

• 《企业IT架构转型之道：阿里巴巴中台战略思想与架构实战》
• 如何基于eolinker 的进行接口管理
• github上源码
• 跟着Github学习Restful HTTP API 设计

附

如果您对eolinker开源的项目感兴趣,可以进一步查阅我编写的安装文档。http://www.doc88.com/p-4753808839165.html