开发接口文档_更优更稳更好,看文档驱动开发模式在AIMS中的优势

​【摘要】程序员常会说:我最讨厌别人写的代码没有文档,我也最讨厌自己需要写文档。

有一个很老的梗: 我最讨厌别人写的代码没有文档,我也最讨厌自己需要写文档。

有这种想法的程序员应该算是一个老鸟了,对于大多数程序员来说,对于他们来说: 文档是什么。

对于大规模,超大规模的项目,并且历时很长,需要大量人员协同开发的项目,没有文档简直不可想象。但是由于时间紧,任务重,大多数的项目中的开发者都没时间写文档,而且,文档也不计入考核指标,导致开发者也没有动机写文档。这就造成了很多项目都缺少规范化文档,项目的交接和接口的对齐都是靠口口相传,接口定义准确度低,并且项目的整体开发效率低下。

作为一个文档爱好者的笔者来说,平常很重要的一件事儿就是将自己的工作归纳总结并整理成文档。即便如此,笔者也面临着很多问题:

  • 需求很快就变了,光是改代码就已经耗尽了我的精力了,哪有时间同步文档。
  • 要么先改代码,要么先改文档,总之文档和代码之间存在一个不一致错位期。

除此之外,由于我们主要从事AI相关能力的研发,所以在开发过程中还存在以下特殊的问题:

  • 开发者不得不写大量重复的网络编程相关的业务代码,这些代码的质量通常不高,并且在后期的反复修改中变得越来越臃肿,从而难以维护。
  • 因为重复的业务代码开发工作占比过大,严重压缩智能化研发人员在AI方面的精力投入,这就导致了企业投入大量人力却无法得到好的效果。

经过不断的摸索和实践,AIMS项目组采取了一套文档驱动的开发模式,可以有效地解决上述在项目中广泛存在的问题。

1、AI接口开发的特点

不同于传统API的CRUD接口的开发,AI的开发模式通常包含了以下步骤:

  • 数据清洗;
  • 模型训练;
  • 参数调优;
  • API上线。

前三项都是我们组的强项,也是我们的工作重点。但是在实际工作中,却是API上线消耗了我们的大部分精力。AIMS项目组大都从事的是AI方向相关的工作,对于API的相关库flask、tornado也不是很熟悉,这就导致开发人员需要花大量时间去了解网络编程相关内容,开发出来的程序质量可能也不是很高。而且,在接口开发后,还需要准备一份Swagger UI给前端的开发人员,这又是一项繁重的工作。为了解决如上所述的痛点问题,AI接口开发就需要满足以下两个特点和需求:

  • API的核心函数是现成的;
  • 需要将API开发工作量降到最低。

2、文档驱动的开发模式

我们发现API的接口文档中已经包含了实现API接口的所有信息。也就是说,API接口文档的信息熵和API接口代码的信息熵是一样的。因此,我们只需要完成代码或者文档中的一项即可,另外一项可以交给框架自动生成,这就避免了把同样一件事情重复做两遍的问题。考虑到文档不论从可读性、易写性还是可维护性都胜过代码,我们决定写文档,然后根据文档生成对应的代码。

我们参考了OpenAPI Specification3.0.1标准,以及JSON Schema定义了一套API描述语言,开发者基于这个API描述语言撰写API文档。当完成文档时,API的开发工作也随之完成,大大节省了API接口的开发工作量。经过初步估计,使用文档驱动模式开发一个API接口,通常可以减少40%–70%的工作量。

3、AIMS框架介绍

为了实现文档驱动的开发模式,AIMS基于tornado实现了一套Web后端框架,如下图所示。

83104060363908b6d6b727924656046e.png

(1)ApplicationRouter组件

每一个API都会有一个路径,即一个正则表达式[1]。一个微服务中的多个API的所有路径会组成一个API路径列表。

当Application Router接收到请求时,会根据请求中的URI在路由表中查找。如果匹配到某一个Request Handler,路由模块会将请求转发给响应的Request Handler。如果所有的路径都不匹配,则返回404结果[2]。

(2)RequestHandler组件

Request Handler处理来自Application Router的响应,是AIMS架构的核心,而Document则是Request Handler的核心。在AIMS架构中,Document是指函数的文档,即__doc__。Request Handler是在服务的启动阶段动态生成的。

事实上,在AIMS架构图中,只有Document是开发者必须写的[3]。其它的组件都是由AIMS提供的,或者是由Document自动生成的,所以AIMS开发模式也被称为文档驱动型开发模式。开发者只需要维护Document即可,从而实现减少开发者工作量的目的。

(3)Watchman组件

Watchman组件可以通过设置来订阅某些接口的异常,当被订阅接口出现任何异常时,Exception Handler便会触发Watchman组件。

因为Recorder组件记录了Arguments,Watchman甚至可以自动产生一个可以复现该问题的测试用例,方便开发人员定位问题。

(4)Recorder组件

Recorder是一个采集器,可以采集每一次请求的所有细节信息,包括请求ID、请求参数、远程IP、被调用的接口、响应时间、工作目录和进程号等各种信息。这些数据具有以下两个作用:

  • 系统的维护者可以利用Recorder中的数据快速定位,复现现网问题,可以看做是一个更强大的日志系统。
  • 通过请求ID,训练数据收集系统可以将请求参数、响应数据与用户反馈数据关联起来,这就相当于是一条有标记的数据。

(5)Logger组件

Logger是AIMS封装的日志模块,用法和python自带的logging.Logger使用方式一致,最大限度地降低开发者的学习成本。

补充说明

我们注意到,在AIMS架构图中,Argument Parser、Schema Checker、Swagger UI和OpenAPISpecification是同源的,即都是来自Document。这就不会出现文档(Swagger UI、OpenAPI Specification)与函数实现(Argument Parser、Schema Checker)不一致的情况。开发者也不需要同时维护Argument Parser、Schema Checker、Swagger UI和OpenAPI Specification相关代码。

以上就是文档驱动开发在AIMS框架中的优势,既降低了开发者的工作量,又解决了一致性的问题。事实证明,自动产生的组件质量也是优于开发者自行开发的代码,并且不易出错,从而提升整体服务的质量以及稳定性。

[1] 在AIMS开发中,这个字段是写在__doc__中的api_path字段中。
[2] 事实上,路由模块会将请求转发给NotFoundRequestHandler,然后由NotFoundRequestHandler进行响应。
[3] 在AI相关微服务开发过程中,Function,也就是核心功能函数,是已经准备好的。

本文分享自华为云社区《文档驱动开发模式在 AIMS 中的应用与实践》,原文作者:zqmillet 。

点击关注,第一时间了解华为云新鲜技术~

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/506944.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

计算机网络项目——最小网元设计(前情提要和项目概述)

目录序言项目总览一、设计主题二、阶段目标其他想说的话序言 经过此学期的计算机通信网挑战课程,我算是体会到了什么叫做忙碌。想着本学期已经结束,闲暇时间来整理一下本学期计通网做的大项目,或是想着因为没能找好队友,一个人干…

广电为什么禁止投屏_广电的机顶盒怎么投屏

说到广电的机顶盒,相信大家都不陌生,如今普及的比较广,但是很多朋友不太清楚广电的机顶盒怎么投屏,没关系,小编将在下文为大家介绍相关知识,希望对大家有所帮助。一、广电的机顶盒怎么投屏想将手机屏幕投屏…

计算机网络项目——最小网元设计(阶段一)

目录阶段目标模型设计功能设计应用层网络层数据链路层物理层其他想说的话阶段目标 完成最小网元的层次模型设计 模型设计 仿照实际应用较为更广泛的TCP/IP模型,针对本项目的最小网元,初步将模型划分为四层:应用层、网络层、链路层、物理层…

人声处理_人声美化:人声后期处理方法

最近在整理美声方面的相关资料,主要是EQ方法的搜集和归纳。声音的压限(压缩处理)、均衡、混响是做好人声处理的关键。[1]1Ultrafunk fx: Equalizer R3(均衡)声音过暗会感觉吐词含糊不清,声音过亮…

计算机网络项目——最小网元设计(阶段二)

目录阶段目标设计描述1、帧结构2、帧定位3、差错检测4、差错控制5、流量控制6、长帧传输——分片测试情况其他想说的话阶段目标 用链路层例程代码(LnkTester.sln)设计实现链路层上点到点之间的通信过程,具体包括:两点之间帧同步、…

key value vue 输出_Vue2.0 v-for 中 :key 到底有什么用?

v-for中不加:key貌似也能正常显示,那为什么要加:key呢?我们知道vue可以动态的改变页面的结构,比如在一个div里面插入一个span标签,看似简单的操作,底层还是很复杂的,它是如何实现的呢?因为页面的…

计算机网络项目——最小网元设计(阶段三)

目录阶段目标设计描述1、帧结构2、按目的转发3、反向地址学习4、未知广播测试情况其他想说的话阶段目标 本阶段主要完成链路层交换机的功能实现:单播目的地址判收、支持广播、有端口地址表、反向地址学习,并在含交换机的多网元情况下完成测试。 设计描…

token拦截器android_vue.js添加拦截器,实现token认证(使用axios)

什么是token?token是一个用户自定义的任意字符串,目前开发中,token都是在服务端生成并且token的值会保存到服务器后台。只有服务器和客户端知道这个字符串,于是,这个token就成了两者之间的秘钥,它可以让服务…

计算机网络项目——最小网元设计(阶段四)

目录阶段目标设计描述1、实体编址2、路由表设计3、路由配置4、路由器的存储转发5、端到端的图片传输测试情况其他想说的话阶段目标 本阶段需要对实体进行编址,实现NET层的IP地址到MAC层地址的映射,解决各层实体的标定区分和数据投递,同时网络…

扫一扫 移动端_移动端手机APP 身份证识别 手机扫一扫离线识别

证件识别是指能实现拍照自动输入身份信息,让用户完全告别手动输入身份证、驾驶证、行驶证等证件信息。它支持Android、 iOS 、Java、Linux等多终端形式接入,电 一山一,领九九,六八九八菱还能通过多样化的结果输出,满足…

电脑解锁后黑屏有鼠标_电脑开机黑屏只有鼠标

电脑开机黑屏只有鼠标经常使用电脑的朋友都会遇到电脑的各种故障,例如电脑开机黑屏只有鼠标,那么该怎么办呢?下面一起来看看电脑开机黑屏只有鼠标的解决办法。方法一、如果自己对电脑不懂的话,最简单的方法就是强制关机,这个关机…

figma应用——面向用户的咖啡点单APP的设计过程记录

目录概述设计阶段1、Brainstorm2、用户分析(1)用户画像(2)竞品分析(3)用户旅程地图(4)用户需求分析3、点单APP的demo设计(1)整体布局逻辑概览(2&a…

java右移位_java 、移位操作方法

<java" id"highlighter_505373">以上是正整数&#xff0c;运算结果如下。接下来看看将负数进行左移2位操作是什么情况&#xff0c;运算结果如下。为什么会-10的二进制会出现这么多的1呢&#xff1f;仔细数一下刚好有32位。首先需要了解的是java负数存储是…

打docker镜像_使用docker构建自己的镜像

在docker中&#xff0c;我们使用docker build构建一个新的镜像&#xff0c;构建镜像之前需要去编写Dockerfile这个文件才能否建一个新的镜像。官方文档&#xff1a;https://docs.docker.com/engine/reference/builder/#fromFROM&#xff1a;用于指定基础镜像RUN&#xff1a;构建…

3d打印主要的切片参数类型_3D打印混凝土工艺参数对成型精度的影响

3D打印混凝土技术作为新兴技术&#xff0c;由于其不需要模板&#xff0c;节省大量劳动力和可打印复杂造型的特点&#xff0c;得到了大家的关注。但是&#xff0c;利用3D打印技术建造想要的结构&#xff0c;成型精度是必须考虑的一个问题。成型精度受材料性能、打印设备及打印工…

web中hasmoreelements_Web开发模式【Mode I 和Mode II的介绍、应用案例】

开发模式的介绍在Web开发模式中&#xff0c;有两个主要的开发结构&#xff0c;称为模式一(Mode I)和模式二(Mode II).首先我们来理清一些概念吧&#xff1a;DAO(Data Access Object)&#xff1a;主要对数据的操作&#xff0c;增加、修改、删除等原子性操作。Web层&#xff1a;界…

网络传输大端序_大端、小端与网络字节序

大端(Big-Endian)&#xff0c;小端(Little-Endian)以及网络字节序的概念在编程中经常会遇到&#xff0c;网络字节序(Network Byte Order)一般是指大端(Big-Endian&#xff0c;对大部分网络传输协议而言)传输&#xff0c;大端小端的概念是面向多字节数据类型的存储方式定义的&am…

poi的sax模式读取xls_POI SAX 如何修改大excel 文件内容-问答-阿里云开发者社区-阿里云...

I think POI is using too much memory! What can I do?This one comes up quite a lot, but often the reason isnt what you might initially think. So, the first thing to check is - whats the source of the problem? Your file? Your code? Your environment? Or …

cupload怎么保存图片_原生js的图片上传插件cupload

插件描述&#xff1a;支持图片预览、像素限制、大小限制、多图上传、更新模式下页面初始化加载图片更新时间&#xff1a;2020-09-25 00:23:49更新说明&#xff1a;添加 删除时&#xff0c;同时删除服务器图片的功能&#xff0c;文档提供php实例。添加参数Url参数更新 {ele: &q…

mysql 半同步_mysql 主从同步 与 半同步

mysql主从同步复制定义主从同步使得数据可以从一个数据库服务器复制到其他服务器上&#xff0c;在复制数据时&#xff0c;一个服务器充当主服务器(master)&#xff0c;其余的服务器充当从服务器(slave)。通过配置文件&#xff0c;可以指定复制所有的数据库&#xff0c;某个数据…