我和后端因为接口吵起来啦，还列了 5 锅罪

╰半夏微凉° 2022-10-18 04:54 29阅读 0赞

公众号关注 “前端开发博客”

设为 “星标”，每天分享一个前端知识点！

来源：suo.im/5n3Dz3

*  罪状一：没有文档
 *  罪状二：文档不全
 *  罪状三：接口参数没校验
 *  罪状四：没保证接口原子性
 *  罪状五：接口问题不断

--------------------

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

# 罪状一：没有文档 #

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

**1.为什么要文档？**

1.  文档是当前开发者甚至后面的接盘侠（后面开发者）能够清晰往下做的指引。
2.  即便是简单的东西，但如果不写文档，以后口口相传消耗的工作量会比写文档更多。
3.  好记性不如烂笔头，一段时候后，可能连开发者都忘记接口的用途。

**2.文档怎么写？**

1.  在线文档。

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

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

1.  本地文档。

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

**Final~**

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

# 罪状二：文档不全 #

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

**一般的返回数据结构~**

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

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

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

**升级返回数据结构~**

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

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

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

**Final~**

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

# 罪状三：接口参数没校验 #

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

**Final~**

统一处理好接口校验，后端好好考虑下。

# 罪状四：没保证接口原子性 #

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

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

**Final~**

原子性一定要保证，保证，保证！

# 罪状五：接口问题不断 #

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

1.  是否校验参数。
2.  是否所有的情况都测试过了，如果可以请写单元测试。
3.  是否返回数据准确明朗，响应状态码是否正常。
4.  文档是否已经完备。

# 总结 #

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

\- EOF -

推荐阅读  点击标题可跳转

[面向后端的前端技术分享][Link 1]

[程序员遇到 Bug 时的 30 个反应，你是哪一种？][Bug _ 30]

[一个普通前端程序员走过的路程][Link 2]

觉得本文对你有帮助？请分享给更多人

推荐关注「前端开发博客」，提升前端技能

![853505444028e67fc44ed5d21dd55d03.png][]

**如果觉得这篇文章还不错，来个【分享、点赞、在看】三连吧，让更多的人也看到~**

![e4d55a02d8c7b2c83c11664a59263dbe.gif][]

**公众号也开始通过互动率推送了，互动少了可能就很晚或者收不到文章了。**

**大家点个在看，星标我的公众号，就可以及时获得推文。**

[Link 1]: http://mp.weixin.qq.com/s?__biz=MzAxODE4MTEzMA%3D%3D&chksm=83dbbb15b4ac32030f91fd95bf93c488eaded09622148099b97e08682c28745d2f1d54ec1bb3&idx=2&mid=2650089072&scene=21&sn=e33e638b3090666dd98776b4b2b66ac4#wechat_redirect
[Bug _ 30]: http://mp.weixin.qq.com/s?__biz=MzAxODE4MTEzMA%3D%3D&chksm=83dbb514b4ac3c02bb1a6f4d9a7e37b9dcf6858df553f030b1ece9b3a5701f72ca44288a4893&idx=2&mid=2650089585&scene=21&sn=e9ce89e0989c85472f99dcd5a7f1480c#wechat_redirect
[Link 2]: http://mp.weixin.qq.com/s?__biz=MzAxODE4MTEzMA%3D%3D&chksm=83dbbb72b4ac32641e08c5e8c78551e0288e09822c30684ccee1d8dd76ec17b568049a2bef13&idx=2&mid=2650088983&scene=21&sn=fb55c9a52400b2080dabf17bef25e24c#wechat_redirect
[853505444028e67fc44ed5d21dd55d03.png]: /images/20221014/4c474debc0a74a81aaba2d61adff07f0.png
[e4d55a02d8c7b2c83c11664a59263dbe.gif]: /images/20221014/eec573e8ecd04ceda0bd7a87f3f4840f.png