RESTful API接口文档规范小坑

时间:2021-05-18 18:06:50

希望给你3-5分钟的碎片化学习,可能是坐地铁、等公交,积少成多,水滴石穿,谢谢关注。

  前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问题?这里分享一些不成熟的浅见。

Swagger描述

  我们在前后端配合的过程中,使用了大多数人使用的Swagger作为服务描述文档,这样的好处很明显,就是后台编写注释,接口调用界面自动生成字段描述。如下图:

  RESTful API接口文档规范小坑

  随着前后端磨合,默契程度逐步增加,基本上这种描述文档足够联调了。事物总是多变的,随着新人的加入和接口的增加,业务的复杂化,过了大半年,回头望月,接口已经开始出现坏味道。

  RESTful API接口文档规范小坑

  新人不知道如何维护,连老人也要梳理回忆半天,接口膨胀导致分类不清晰,很难想象如果这个时候,如果你们需要把部分前端功能进行外包会怎样?前端单看Swagger会不会一脸懵逼?

Wiki文档

于是内部开个了专题会,参照市面上大多数的api描述文档,大家同意写到wiki,虽然这种做法除了增加后端人员的工作量,对提升效率不是那么明显,但是整个接口的描述相对就规范一些。

  RESTful API接口文档规范小坑

  过了一段时间,有一个前端新人进来,带来了小小的烦恼,由于后端接口变更,文档没有及时更新,前端在联调时候经常一脸懵逼,如果能及时发现还好,否则将错就错,测试没注意,发布后经常犯一些写错别字的低级错误。

  更加麻烦的是,项目工期赶,决定对前端部分模块进行外包。于是准备好了UI图和接口描述文档,觉得应该可以安心了。承包方拿到UI和文档的时候,除了简单的增删改查接口大概能猜的懂,其他的接口和UI上如何一一匹配?好吧,这该死的接口文档。

图文描述

  于是后台兄弟加班加点在UI上给每个功能一一标注对应的接口名称,如下所示,虽然缓解了前端的困惑,但是前后端分离导致的一些效率损失,始终让人耿耿于怀。也许就像DBA经常说的,任何事物都是有代价,不知道大伙有更好的解决方案赐教?

  RESTful API接口文档规范小坑

个人小结

1.对前端组件进行分类

比如树、表格、下拉、radio、复选框、时间……越早分类对后面的管理应该会更加有利,因为不同的新人进来,可能同样的树会重新造一种格式。

2.接口数量要控制好

不能太多导致失控,也不能重复两份接口(不同的开发者完全有这种可能),不同的前端组件比如easyUI和elementUI对格式要求是不一样的,如果前后台用的不是同一套UI框架,接口有可能会出现重复。

3.如何规范

每个公司规范不尽相同,可以参考大厂的规范,比如高德,微信或者百度地图。对新入职的新要培训在前,开发中出现新的问题,最好要有专题会进行讨论协商一致,最后口头的东西务必要文档化,否则都不能算是真正的规范。

后话

随着团队人数、业务扩大,如果没有很好的规范,碰到沟通冲突的情况,规范就显得特别重要。我们团队原本两个前后端配合融洽,相安无事,后面来了两个新的前后端,由于言语冲突,一件简单的小事会因为个性不合而被无限放大。尽快统一风格,规范文档化也许可以避免很多类似的问题。

这里给哪些想要做前后端分离的人一个不错的RESTful API的规范,是阮一峰大神的博客,非常值得收藏,推荐下:RESTful API 最佳实践