从零到一： 后端接口文档

在需求文档完成后，测试人员以及开发人员应该分别开始了本身的工做。测试人员开始按照需求文档编写修改Case，并制定合适的测试计划，评估自动化测试的可行性等。开发人员根据职位的不一样开展各自的工做。

做为普通程序员：

一.掌握核心业务流程：在前期项目中 编写需求文档 这段时间中，应该对项目有一个基本的了解，并对项目的核心业务有一个明确的认识。每每我对核心业务掌握的不够全面，致使后期代码编写过程当中，会出现一些意想不到的意外，致使工做量增长。例如：业务功能不全，业务逻辑不清楚，最糟糕的是业务流程走不通，那才是悲剧。

二. 深刻分析数据结构：数据库中每一个字段都应该是有意义的，并且都应该会被使用到（除非是备用字段），因此要了解每一个字段的含义，是用来干什么的！其次，要时刻注意业务中须要的字段，必定不能缺乏，因为数据库设计不够全面，到后期发现数据库设计逻辑有缺陷，那真的会衍生出不少问题以及Bug，可是这也是最不容易被发现的地方，只有后期作到这一步才会被发觉。

三. 编写接口文档：在充分了解业务流程，以及数据库结构后，就开始编写接口文档了。对业务了解的越透彻，写出的接口才会越合理。在写接口文档的时候，须要考虑的事情不少：

a.最基本的：前端须要传来的参数，返回的数据格式

b.合适的名字：返回的数据要有合适的名字，清晰明了，能让前端人员大体明白数据表明的含义

c.最小数据：不管前端数据渲染，后端数据操做，多余的冗余字段会影响项目的性能，因此应该尽可能保持数据的冗余程度较低。

下面是一个接口文档的示例：

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

水井水量

1)      URL地址：class/water.api

2)      请求方式：get/post

3)      请求参数：

参数名	参数类型	参数长度	参数说明	必填
group	字符串		水井编号	Y

4)      接口返回：

                 A:成功：

　　　　　　　　{

   　　　　　　　　　　 "resultCode": 1,

   　　　　　　　　　　 "success": true,

   　　　　　　　　　　　　 "data": {

　　　　　　　　　　　　　　　　　  "waterOne": {

                          　　　　　　　　　　　　　　 "waterName": "水一",

　　　　　　　　　　　　　　　　　 　　　　 "todayWater": {

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_01": "01点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_02": "02点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_03": "03点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_04": "04点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　　　........

　　　　　　　　　　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　　　　"waterTwo":{

                          　　　　　　　　　　　　　　 "waterName": "水二",

　　　　　　　　　　　　　　　　　　　　　  "todayWater": {

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_01": "01点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_02": "02点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_03": "03点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　"water_04": "04点水量",

　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　........

　　　　　　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　　　　　}

　　　　　　　　　　　　　　}

　　　　　　　　　}

　　　　B:失败

　　　　　　{"resultCode": "-1","resultMsg": "内部异常"}

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

这是一个简单关于水井水量的api，除了一些基本的信息，例如 接口名，接口访问路径，请求方式，请求参数，返回数据等，还应该注意接口中应该简化的地方，例如，用water_01表示一点时水井水量的字段，有大量重复数据，能够直接改为01，02，03，04.....这样能节省一点就节省一点。固然还要考虑其余的因素。

在前段时间我总以为写接口文档没有什么用处，由于即便写了，到后期，总会由于需求变动，或者由于之前没考虑到的地方而从新设计接口文档，每每到最后，最终接口与最初的接口文档彻底不同，这样写接口文档有什么用处呢?而后，与前端人员聊天的时候，他们跟我说，写接口文档给他们前端人员是颇有用处的。而后本身仔细想了想，确实写接口文档是有益的。

1）能让前端人员心中大体有数，这些数据的格式是怎么样的。并能够制造相似的假数据直接进行前端开发

2）写接口文档，能让本身对业务有一个更清晰的认识与总结，对之后的代码编写有必定规划

3）要想写出合适的接口，必须对业务逻辑以及数据结构有很深的认识。