什么是接口文档,如何写接口,有什么规范?

在项目开发中,web项目的前后端分离开发,APP开发,需要由前后端工程师共同定义接口,编写接口文档,之后大家都根据这个接口文档进行开发,到项目结束前都要一直维护。

一、为什么要写接口文档?

  1. 正规的团队合作或者是项目对接,接口文档是非常重要的,一般接口文档都是通过开发人员写的。一个工整的文档显得是非重要。
  2. 项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发,项目维护中或者项目人员更迭,方便后期人员查看、维护

二、接口规范是什么?

首先接口分为四部分:方法、uri、请求参数、返回参数

  1. 方法:新增(post) 修改(put) 删除(delete) 获取(get)

  2. 接口详情
    地址www.baidu.com
    方式GET
  3. uri:以/a开头,如果需要登录才能调用的接口(如新增、修改;前台的用户个人信息,资金信息等)后面需要加/u,即:/a/u;
    中间一般放表名或者能表达这个接口的单词;get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾;url参数就不说了中间一般放表名或者能表达这个接口的单词;get方法,如果是后台通过搜索查询列表,那么以/search结尾,如果是前台的查询列表,以/list结尾;url参数就不说了

  4. 请求参数和返回参数,都分为5列:字段、说明、类型、备注、是否必填
    字段是类的属性;说明是中文释义;类型是属性类型,只有String、Number、Object、Array四种类型;
    备注是一些解释,或者可以写一下例子,比如负责json结构的情况,最好写上例子,好让前端能更好理解;是否必填是字段的是否必填。

  5. 返回参数结构有几种情况:

    1. 返回接口调用成功还是失败(如新增、删除、修改等),如下图:

      返回结果格式JSON
      状态码200success(成功)
      状态码500error(失败)
      状态码501param error(参数错误)
    2. 如果要返回某些参数,则有两个结构体:1是code/mesage/data,2是data里写返回的参数,data是object类型;

    3. 如果要返回列表,那么有三个结构体,1是code/mesage/data,data是object,里面放置page/size/total/totalPage/list 5个参数,其中list是Arrary类型,list里放object,object里是具体的参数。

    注意:uri地址里不允许出现大写字母,如果是两个单词拼接,用/分开

三.如何合理设计接口?

一、 设计原理

  1. 深入了解需求:从“客户端-接口-数据库”的层次上看,接口明显扮演着承上启下的角色,一方面要明白接口要什么数据,另一方面要考虑如何从数据库获取、组织数据。所以如果不了解需求,你就无法正确抽象对象来组织数据给客户端,也无法验证数据库的数据结构能否满足需求。
  2. 了解数据库结构:既然接口要明白如何从数据库获取、组织数据,就当然要了解数据库结构啦。
  3. 了解客户端原型:了解原型,其实更多是为了帮助你设计接口时需要提供的数据和结构。

二、设计原则

  1. 充分理由:不是随便一个功能就要有个接口,也不是随便一个需求就要加个接口。每新建一个接口,就要有充分的理由和考虑,无意义的接口不仅增加了维护的难度,更重要是对于程序的可控性的大大降低,接口也会十分臃肿。
  2. 职责明确:一个接口只负责一个业务功能,比如查询会员,但不要在查询会员的同时还有修改权限等类似的其他业务功能,应该分成两个接口做。
  3. 高内聚低耦合:一个接口要包含完整的业务功能,而不同接口之间的业务关联要尽可能的小。
  4. 分析角度明确:设计接口分析的角度要统一明确。否则会造成接口结构的混乱。
  5. 入参格式统一:所有接口的参数格式要求及风格要统一,不要一个接口参数是逗号分隔,另一个就是数组;不要一个接口日期参数是x年x月x日风格,另一个就是x-x-x。
  6. 状态及消息:提供必要的接口调用状态信息。调用是否成功?如果失败,那么失败的原因是什么。这些必要的信息必须要告诉给客户端。
  7. 控制数据量:一个接口返回不应该包含过多的数据量,过多的数据量不仅处理复杂,对数据传输的压力也非常大,会导致客户端反应缓慢。过多的数据量很多时候都是接口划分不明确。
已标记关键词 清除标记
©️2020 CSDN 皮肤主题: 技术工厂 设计师:CSDN官方博客 返回首页