公司前端和后端因为接口扯起了皮，还列了5宗罪

点击上方“芋道源码”&＃xff0c;选择“设为星标”

做积极的人&＃xff0c;而不是积极废人&＃xff01;

源码精品专栏

• 原创 | Java 2019 超神之路&＃xff0c;很肝~
  

• 中文详细注释的开源项目
  

• RPC 框架 Dubbo 源码解析

• 网络应用框架 Netty 源码解析
  

• 消息中间件 RocketMQ 源码解析
  

• 数据库中间件 Sharding-JDBC 和 MyCAT 源码解析

• 作业调度中间件 Elastic-Job 源码解析

• 分布式事务中间件 TCC-Transaction 源码解析

• Eureka 和 Hystrix 源码解析

• Java 并发源码

来源&＃xff1a;http://suo.im/5n3Dz3

• 罪状一&＃xff1a;没有文档

• 罪状二&＃xff1a;文档不全

• 罪状三&＃xff1a;接口参数没校验

• 罪状四&＃xff1a;没保证接口原子性

• 罪状五&＃xff1a;接口问题不断

今天一位前端开发人员扯起了后端接口的皮&＃xff0c;那个兄弟对后端人员提供的接口很大的意见&＃xff08;我是司空见惯&＃xff09;&＃xff0c;不过他说的也确实有道理&＃xff0c;所以结合我的见解&＃xff0c;希望提供接口的人员能多加注意。

例如新的前端人员到了一个新的公司&＃xff0c;使用接口时&＃xff0c;问这个这个不知道&＃xff0c;问那个那个不知道&＃xff0c;要文档没文档&＃xff0c;这绝对是前端人员最抓狂的事&＃xff0c;心里肯定是一千只草泥马奔腾而过。

1.为什么要文档&＃xff1f;

1. 文档是当前开发者甚至后面的接盘侠&＃xff08;后面开发者&＃xff09;能够清晰往下做的指引。

2. 即便是简单的东西&＃xff0c;但如果不写文档&＃xff0c;以后口口相传消耗的工作量会比写文档更多。

3. 好记性不如烂笔头&＃xff0c;一段时候后&＃xff0c;可能连开发者都忘记接口的用途。

2.文档怎么写&＃xff1f;

1. 在线文档。

在线文档易于更新和他人查看&＃xff0c;例如可以使用Swagger编写接口文档。

PS&＃xff1a;Swagger是一个规范和完整的框架&＃xff0c;用于生成、描述、调用和可视化RESTful风格的Web服务。

1. 本地文档。

本地文档一般用Word文档&＃xff0c;但是比较不易传播&＃xff0c;但能离线查看。

Final~

文档是及其关键的&＃xff0c;无论是在线文档还是本地文档&＃xff0c;有是关键。虽然写文档是麻烦的事&＃xff0c;但对后端人员来说&＃xff0c;是利人利己。

额&＃xff0c;就是有了文档&＃xff0c;文档里面对接口的描述也可能不全&＃xff0c;可能缺每个参数详尽描述&＃xff08;取值范围、类型&＃xff09;、请求方式&＃xff08;GET、POST、PUT、DELETE&＃xff09;、返回数据的所有状态等等。这里面可能最缺就是返回数据的状态&＃xff01;

一般的返回数据结构~

公司的数据接口返回结构是

{
s : 0/ 1, //表示此操作的处理状态&＃xff08; status &＃xff09;&＃xff0c;一般简单的成功 /不成功&＃xff0c;使用 1/0 表示。
m : &＃39;xxxx&＃39;, //表示此操作的提示信息&＃xff08; message &＃xff09;&＃xff0c;一般只用来显示操作失败时提示信息。
r : [], //表示此操作的返回值&＃xff08; result &＃xff09;
count : x //返回的数据条数
}


这种数据结构看起来没问题&＃xff0c;确实也没大问题&＃xff0c;问题就是出在s这个字段。有许多的接口不仅仅只有两种状态&＃xff0c;成功状态只有一种倒是没问题&＃xff0c;问题就出在失败状态&＃xff0c;失败可能有很多情况&＃xff0c;一个简单的s:0不能说明失败的原因&＃xff08;即便是有m提示信息&＃xff0c;但用这个来区分很不靠谱&＃xff0c;因为提示可能会变化&＃xff09;&＃xff0c;我们不总是仅拿m做显示用。

升级返回数据结构~

那位同事建议以下方式应答

{
s : 0/ 1/ 2/ 3, // 0代表正常&＃xff0c;1是参数有误&＃xff0c;2是用户不存在&＃xff0c;3是用户没权限等等
m : &＃39;xxxx&＃39;, //表示此操作的提示信息&＃xff08; message &＃xff09;&＃xff0c;一般只用来显示操作失败时提示信息。
r : [], //表示此操作的返回值&＃xff08; result &＃xff09;
count : x //返回的数据条数
}


m、r、count 可以保持不变&＃xff0c;但是s里面必须包含所有返回状态&＃xff0c;代表这个接口所有业务的情况&＃xff0c;前端开发人员也就能针对每种情况进行处理。

Final~

文档最重要的部分是返回值的状态&＃xff0c;我也建议上面的升级返回数据结构&＃xff0c;这样就不存在任何不明朗情况。既然写了文档&＃xff0c;就把文档写好&＃xff0c;写明朗&＃xff0c;这也是利人利己地方。

这个前端人员倒不是很关注&＃xff0c;因为本身调接口之前都会先做校验&＃xff0c;后端做参数校验只是双重保证。我之前也做过一段时间后端&＃xff0c;也犯过没校验参数的错&＃xff0c;额&＃xff0c;因为后来没有做后端&＃xff0c;也就没有去修正。不过还是提醒后端人员&＃xff0c;做好参数校验是第一步&＃xff0c;不要偷懒了。

Final~

统一处理好接口校验&＃xff0c;后端好好考虑下。

接口的原子性很重要&＃xff0c;有时一个接口可能会干几件事&＃xff0c;但不一定都能正常完成&＃xff0c;这就导致可能存在原子性问题&＃xff0c;接口不能准确被调用。

PS&＃xff1a;原子性。一个原子事务要么完整执行&＃xff0c;要么干脆不执行。这意味着&＃xff0c;工作单元中的每项任务都必须正确执行。如果有任一任务执行失败&＃xff0c;则整个工作单元或事务就会被终止。即此前对数据所作的任何修改都将被撤销。如果所有任务都被成功执行&＃xff0c;事务就会被提交&＃xff0c;即对数据所作的修改将会是永久性的。

Final~

原子性一定要保证&＃xff0c;保证&＃xff0c;保证&＃xff01;

前端开发人员调接口时候&＃xff0c;可能会存在各自各样的问题&＃xff0c;有问题可以理解&＃xff0c;程序哪会没有bug&＃xff0c;但不能太离谱啊&＃xff0c;后端兄弟们。所以我觉得在给出接口之前自己明确几件事&＃xff1a;

1. 是否校验参数。

2. 是否所有的情况都测试过了&＃xff0c;如果可以请写单元测试。

3. 是否返回数据准确明朗&＃xff0c;响应状态码是否正常。

4. 文档是否已经完备。

后端人员多体谅前端人员&＃xff0c;在出现问题时&＃xff0c;先检查自身&＃xff0c;别一上来就跟前端干起来&＃xff0c;要是自己的问题就尴尬了。

欢迎加入我的知识星球&＃xff0c;一起探讨架构&＃xff0c;交流源码。加入方式&＃xff0c;长按下方二维码噢&＃xff1a;

已在知识星球更新源码解析如下&＃xff1a;

如果你喜欢这篇文章&＃xff0c;喜欢&＃xff0c;转发。

生活很美好&＃xff0c;明天见(&＃xff61;&＃xff65;ω&＃xff65;&＃xff61;)&＃xff89;♡