从零到一: 后端接口文档

在需求文档完成后,测试人员以及开发人员应该分别开始了自己的工作。测试人员开始按照需求文档编写修改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)要想写出合适的接口,必须对业务逻辑以及数据结构有很深的认识。

原文地址:https://www.cnblogs.com/momoweiduan/p/8111756.html