zoukankan      html  css  js  c++  java
  • 从零到一: 后端接口文档

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

  • 相关阅读:
    FiddlerScript修改特定请求参数下的返回值
    nginx设置反向代理后,页面上的js css文件无法加载
    通过外网访问内网服务器
    linux下使用正确的用户名密码,本地无法连接mysql
    合并重叠时间段C#
    数据库一直显示为单用户,解决办法
    windows下使用tomcat部署网站
    数据库一直还原中,解决办法
    通过mdf ldf文件还原数据库
    知道css有个content属性吗?有什么作用?有什么应用?
  • 原文地址:https://www.cnblogs.com/momoweiduan/p/8111756.html
Copyright © 2011-2022 走看看