接口文档,后端接口文档看不懂

多年的IT经验告诉你:不合理,而且会造成工期的延误,不利于整体项目的推进。

接口

它是基于超文本传输协议(HTTP)之上而确定的一组约束和属性,是一种设计提供万维网络服务的软件构建风格。

符合或兼容于这种架构风格的网络服务,允许客户端发出以统一资源标识符访问和操作网络资源的请求,而与预先定义好的无状态操作集一致化。

接口文档,后端接口文档看不懂图1

接口文档

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

接口文档,后端接口文档看不懂图2

为啥要提前提供接口规范文档

因为项目初期,需求确定后就要进行开发。而在开发过程中,都是团队协作。每个人不是孤军奋战,尤其在前后端分离的项目系统上接口规范文档尤其重要。

这里简单说下一个概念:前后端分离,就是前台负责做页面,调用后台的接口服务获取数据,然后渲染页面,呈现给用户。后端需要提供接口能力,保证功能稳定性。

在实际过程,前端开发设计需要时间,而后端开发接口也同样需要时间,所以先提供接口规范有利于前端根据接口规范,模拟返回数据,进行模拟测试。而后台在这段时间也可以开发接口服务,等到按照预期的联调时间,就可以前后台进行正式联调。

为啥需要正式联调,因为接口规范可能会在实际开发过程中发生变动,前端第一次根据后台的接口规范构造的模拟数据,不足以证明后期的实际联调没问题。

在正式联调后,确定最终的接口规范文档,对外发布。

接口文档,后端接口文档看不懂图3

合格的接口规范文档

接口文档,后端接口文档看不懂图4

  1. 明确定义接口的名字、作用。这样有利于读者对接口所涉及的业务功能有清晰的概念。
  2. 定义接口的URL地址。
  3. 定义接口的请求方式,如GET请求、POST请求。
  4. 定义接口请求的Header头部信息,比如定义“Content-Type”: “application/json;charset=UTF-8”
  5. 定义接口的参数字段名、字段类型、是否必填、说明字段的意义、备注(可选)。
  6. 定义接口返回的状态码,比如常见的200 OK。
  7. 定义接口返回的的Header头部信息。
  8. 定义接口返回的响应结果。
  9. (可选)提供接口返回的请求例子、响应结果例子。

接口文档,后端接口文档看不懂图5接口文档,后端接口文档看不懂图6

团队合作,文档先行,编码在后,这样有利于整体项目如期完成。

希望该解答,可以帮助到你。

肯定是不合理的,通常在前后端合作开发的时候,或者两个系统要做服务调用的时候,首先是要确认接口文档。现在我负责的一个项目,只提供查询服务,当我们在做一个新接口的时候,通常会提供这么几个时间点:提供接口文档的时间,联调测试的时间和正式提测的时间,可以看到接口文档肯定是要第一时间提供的。

接口文档,后端接口文档看不懂图7

在早期的项目开发中,开发人员要负责前端加后端的开发,一个人负责一个模块或者一个需求的时候,通常是需要从前端管到后端的,而前后端分离架构的出现,意味着开发人员的分离,每个开发人员会负责某一个领域的事情;而先确定接口文档最重要的一点,就是可以让所有的前端开发和后端开发并行工作,不然的话,就可能项目前期,前端开发人员闲着没事儿做,因为要等接口文档,而项目后期后端开发又没事儿做,因为要等前端开发好了才能提测。

所以,一定要文档确认,双方并行开发,再在一个时间点联调测试;系统和系统之间调用的场景也类似,也是要确认文档后,两个系统并行开发,在规定时间点开始联调测试。

在接口文档确认之后,建议前后端两方、或系统和系统两方的开发人员组织评审,两方认为文档没有什么问题后再进行开发,如果在开发过程中有不合理的地方,再对接口进行微调。

接口文档,后端接口文档看不懂图8

再说说我们项目,因为我们不是前后端分离的场景,只是对外提供服务,所以基本上都是服务提供方确定文档,不需要再做什么评审,当然在接口确认过程中也有几点要注意:

1. 遵守接口规范,如果公司有接口规范的话就最好了,可以节省很多不必要的麻烦;如果公司没有制定统一的规范,也至少在项目组内制定自己的规范。

2. 接口参数见名知意,我们对于 DTO 中的字段名称都是有统一规范的,比如性别就都叫 gender,如果是老项目的话,数据库中的表结构不容易修改,比如姓名字段已经起名叫做 sex 了,也建议在代码中对 Model/VO 转一次到 DTO。

3. 接口文档确认后,尽量不要做修改,这就意味着你在正式开发前,就要做评估和设计。

接口文档,后端接口文档看不懂图9

接口文档,后端接口文档看不懂图10

未经允许不得转载:百场汇 » 接口文档,后端接口文档看不懂