转载

公司前端历数后端研发接口5宗罪

前端和后端应该相亲相爱，当然是建立在“专业”的基础上。

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

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

罪状一：没有文档

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

1.为什么要文档？

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

2.文档怎么写？

在线文档。

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

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

本地文档。

本地文档一般用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 //返回的数据条数
}