一.字段命名(随意命名,看当时心情,怎么舒服怎么来)
1.单个字母,如a、b、x、z.....
2.中文拼音拼写,如:价钱-jiaqian 等待时间(分钟)-dengdaifenzhong。
3.拼音夹杂英文,如:预估价-yuguPrice或者ygPrice。
4.很多同类字段在不同接口用统一命名。
A接口的用户ID返回user
B接口的用户名也返回user
二.接口命名(不见名知义,不然自己还要思考,太累了)
1.简单点,多路径太麻烦,直接api+描述,如 /api/getInfo
2.抽象点。提交个人信息-/api/postData
3.版本迭代需要新接口, 那就/api/postDataNew,第三个版本 /api/postDataNewNew 第四个 /api/postDataNewNewNew.....
三.请求数据(我们只管接收,你们必须传对)
1.参数接收不做各种校验(类型、非空)、必填校验只让他们控制就好。
2.动不动就抛出服务器繁忙,吓死他们,让他们觉得是自己的传参问题。
3.最好减少数据库查询次数,不然影响性能。让他们把id和内容一起传过来让我们拿去给其他表做冗余。
4.下拉选择框的搜索不要传ID,传展示内容text过来,就是这么简洁直观。
四.返回数据(怎么方便怎么来,留点时间给自己)
1.数据库查出什么就返回什么,不要去减少返回字段,他们没用到可以不管。
User user = userService.getById(userId); //user有50个字段
List<Order> orderList = orderService.findList(); //order有50个字段
responseData("user", user)
responseData("orderList", orderList)
2.返回字段根据当时想法决定,没必要请求时怎么命名,返回同个字段就一定要那样命名,不然我们还要去翻翻上个接口是命名的,效率太慢了。
3.返回同种类型的字段用后缀1/2/3表示,不管页面内容是什么结构,即使是类似表格的形式展示,也不要自己去整成前端可以直接用的接口,不然我们太累了,如:
responseData("price1", price1)
responseData("price2", price2)
responseData("price3", price3)
4.数据结构尽可能嵌套多层,让他们知道后端的不容易。
5.不同情况下(不同参数)请求成功时,返回的字段不要统一,不然很麻烦。
如:待审核记录返回
{
"code":200,
"msg":"请求成功"
"data":{"status":0,"text":"正在审核"}
}
审核不通过返回
{
"code":200,
"msg":"请求成功"
"data":{"status":-1,"text":"审核不通过","reason":"不通过原因"}
}
五.接口文档(追求效率,随便写写就好,他们不懂会来问的)
1.不写注释,反正看命名就知道大概意思吧。
2.不分类,全部挤在一起,你找不到再来问我。
3.后期改了接口或部分字段,直接聊天窗口告诉他们就好,后面自己想到再去更新文档。