最近后端接口工作开发完成以后没有事情可做,被领导安排到测试的岗位上进行bug的测试工作。测试过程中看了别人写的文档,测了别人写的接口自叹不如,于是就萌生了这篇文章的创作。构思两天,今天提笔
从我个人的角度理解接口 "好"的含义 概述为以下几点
1 拥有非常详细的接口文档(数据结构复杂、字段多接口必须详细)
跟平时药店买药一样,说明书要书写非常的详细,这样用户才知道该怎么去吃这个药。接口文档也是一个说明书,前端工程师跟测试工程师必须根据接口文档才能完成数据对接跟接口测试工作,所以接口的请求类型、数据结构、字段名称、字段说明等等都是必须要。
2 接口要完成自测
无论是新手还是有工作年限的工程师,只要是写代码就会有bug。特别是刚开发完成的接口,如果直接扔给前端工程师,那就相当于是把自测工作甩给前端工程师。那可能前端工程师会@你很多次说接口报错了,修改完成再去告诉前端可以了。如此反复无疑会增加很多交流成本。不如提前简单一测试,跑通一条简单的demo数据。这样把接口交付给前端工程师,又增加了一大把摸鱼时间。
3 数据要准确 逻辑要严谨
在实现具体业务时,前端传递的参数需要进行合法字段的接收并避免掉非法字段对数据已有字段的覆盖。数据修改的时候需要判断当前数据是否为允许修改的状态,重要数据则需要添加事务 lock 来保证数据的准确。
4 代码可读性要强 注释文字要准确 大多数项目的开发都不会是只有一名后端工程师,当其余同事需要对已经写好的接口进行修改或者二次开发时候。代码简易可读,注释完整是能进行二次开发的前提。
一个不是很标准的示范代码
需求是 对审核中的文章进行修改操作
php
//对文章进行修改
public function update($id){
$param = request()->param();
$result = Db::table('article')->where('id', $id)->update($param);
return json(['code'=>10001,'result'=>$result]);
}
不管是 新手还是工作几年的工程师,可能大部分人写的基本都是上面这个样子的。对于新手来说,经验不足,一些坑可能还意识不到。然而对于有工作经验的工程师来说早已厌倦了每天的增删改查,直接给个接口能修改数据,其余的事儿懒得搞,前端自己判断得了。
后续完整示例请看下一篇文章