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

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

Swagger描述

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

  

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

  

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

Wiki文档

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

  

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

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

图文描述

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

  

个人小结

1.对前端组件进行分类

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

2.接口数量要控制好

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

3.如何规范

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

后话

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

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

RESTful API接口文档规范小坑的更多相关文章

  1. 整合swagger2生成Restful Api接口文档

    整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...

  2. Swagger 生成 PHP API 接口文档

    Swagger 生成 PHP API 接口文档 Lumen微服务生成Swagger文档 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文 ...

  3. “小葵日记”API接口文档

    "小葵日记"项目API接口文档 时间:2017/10/31 (1)用户登录[待完成] POST:127.0.0.1/index/user/login data 数据别称 数据名 数 ...

  4. Swagger解决你手写API接口文档的痛

    首先,老规矩,我们在接触新事物的时候, 要对之前学习和了解过的东西做一个总结. 01 痛     苦 不做.不行 之前,前后端分离的系统由前端和后端不同的编写,我们苦逼的后端工程师会把自己已经写完的A ...

  5. Restful API 接口设计标准及规范

    Restful API 接口设计标准以及规范 RESTful概念 理解和评估以网络为基础的应用软件的架构设计,得到一个功能强.性能好.适宜通信的架构.REST指的是一组架构约束条件和原则." ...

  6. Eolinker API 接口文档神器

    Eolinker API 接口文档神器 群里小伙伴推荐的,还没有去研究,先记下来. API文档管理.自动化测试.开发协作利器 正在为数万企业管理超过100万APIs,提高开发效率以及规范开发流程

  7. 构建标准OpenStack API接口文档

    1.构建API接口文档标准参考: http://docs.openstack.org/contributor-guide/api-guides.html 2.构建API接口文档步骤参考下面的Patch ...

  8. Api接口文档管理工具,你知道哪些呢?

    上周看到有人在我的Github开源项目中提了个issue,说是否考虑接入swagger.那今天我就用swagger与其他接口文档工具做对比,同时说说Api接口文档工具的那点事.如今,在前后端分离开发的 ...

  9. SpringBoot + Swagger2 自动生成API接口文档

    spring-boot作为当前最为流行的Java web开发脚手架,相信越来越多的开发者会使用其来构建企业级的RESTFul API接口.这些接口不但会服务于传统的web端(b/s),也会服务于移动端 ...

随机推荐

  1. Evensgn 剪树枝 树规

    f[x][0]表示与其父边相连的连通块内没有黑苹果的方案数, f[x][1]则表示有黑苹果, 如果父边被切断,相当于没有黑苹果 初始化时,假设切掉父边,f[x][0]=1,f[x][1]=0; 递归回 ...

  2. BZOJ_1342_[Baltic2007]Sound静音问题_单调队列

    BZOJ_1342_[Baltic2007]Sound静音问题_单调队列 题意: 给出n个数,求∑[ max{a[i]~a[i+m-1]} - min{a[i]~a[i+m-1]} <= c ] ...

  3. BZOJ_1015_[JSOI2008]星球大战_并查集

    BZOJ_1015_[JSOI2008]星球大战_并查集 题意:很久以前,在一个遥远的星系,一个黑暗的帝国靠着它的超级武器统治者整个星系.某一天,凭着一个偶然的 机遇,一支反抗军摧毁了帝国的超级武器, ...

  4. 《The java.util.concurrent Synchronizer Framework》 JUC同步器框架(AQS框架)原文翻译

    一.论文简介 闲来无事,看看源码,发现了一篇JDK作者的论文<The java.util.concurrent Synchronizer Framework>主要描述了作者对Abstrac ...

  5. 面试必问!Java 多线程中两个线程交替执行,一个输出偶数,一个输出奇数

    前言 楼主今天在面经上看到这个题,挺有意思,小小的题目对多线程的考量还挺多.大部分同学都会使用 synchronized 来实现.楼主今天带来另外两种优化实现,让你面试的时候,傲视群雄! 第一种 sy ...

  6. Chapter1:基础

    整本书的核心:语言的设计与实现 我们所看到的设计是显示的,语法定义的, 而实现是隐式的,决定了编译或运行时的行为. 了解设计的目的,可以推测实现的细节,也可以自己实现设计. 学习具体的实现,更充分的达 ...

  7. 谈谈 ANR 之 Service 超时

    1. 核心源码 关键类 路径(/frameworks/base/) ActiveServices.java services/core/java/com/android/server/am/Activ ...

  8. Java的多态浅谈

    概述 Java的四大基本特性:抽象,封装,继承和多态.其中,抽象,封装,继承可以说多态的基础,而多态是封装,继承的具体表现.如果非要用专业术语来描述什么是多态的话 多态是指程序中定义的引用变量所指向具 ...

  9. 链表底层实现Java的Map(上)

    链表实现Map public class LinkListMap<K,V> implements Map<K,V> { private class Node { public ...

  10. pods "xxx" is forbidden: SecurityContext.RunAsUser is forbidden

    报错信息如下: pods "k8s-logs-cndf5" is forbidden: SecurityContext.RunAsUser is forbidden 解决方法: 需 ...