如何在 DevOps 中进行 API 全生命周期管理?

Posted eolink

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了如何在 DevOps 中进行 API 全生命周期管理?相关的知识,希望对你有一定的参考价值。

随着 DevOps 理念在中国企业当中的普及和发展,中国企业 DevOps 落地成熟度不断提升,根据中国信通院的数据已有近 6 成企业向全生命周期管理迈进。

而在研发全生命周期管理之中,API 管理的地位愈发显得重要。随着 API 数量的大幅增长,也带来了新的 API 管理需求。

如何在 DevOps 工作流中进行 API 全生命周期管理,对项目研发来说具有重大意义。



1、DevOps 中 API 管理困境

在实际的 DevOps 工作流中,API 管理面临着以下 6 大方面的困境:规范、协作、自动化质量、迭代、自动化。



困境一:规范落地执行难

因为团队中的 API 文档质量参差不齐,导致规范很难落地执行。原因在于公司有很多的研发项目和团队,不同的团队有不同的API管理习惯,尤其是常用的 Swagger 方式的管理,很难进行统一的平台化管理。

针对这个困境,可以通过统一的 API 管理平台规范文档的模板,引导编写流程和习惯,也可以通过自动化文档管理工具来简化流程,提高管理效率。

困境二:岗位协作难、信息沟通效率低

在 DevOps 工具链中,每一个工具都会有不同的通知消息,导致重要信息淹没在繁杂的通知中。其次是工作流程环节多、流程长,各岗位角色处理工作节奏不一,导致任务链上下游沟通效率低。

针对这个困境,可以缩短流程环节,多启用自动化流程。同时制定精细化通知规则,根据优先级提供差异化通知样式。最后,再通过每日推送复盘消息,梳理当日工作项和消息通知,防止遗漏。

困境三:自动化测试体系搭建门槛高

传统的自动化接口测试脚本需要用 Python 来编写,门槛高,成本高。又因纯手工编写,开发变动后还须对照文档二次调整接口的所有脚本。另外,自动化测试前期投入时间多,准备工作繁杂。

针对这个困境,可以使用界面化的自动化测试工具,降低脚本编写门槛。还可以通过一站式 API 全生命周期管理平台,免去大量前期工作,提高自动化测试效率。

困境四:API 生产质量和在线异常的发现、跟踪、解决流程过长

当下,在后端的接口自测、前段的 MOCK 测试、冒烟测试、集成测试、异常监控这 5 个环节中都会使用到不同的工具,于是产生了跨工具之间对接复杂、数据隔离,导致 API 生产质量薄弱,以及大量重复工作。

可以通过一体化的 API 管理工具来打通不同环节的工作流,提高研发质量和效能。

困境五:接口文档无法跟踪迭代版本,回溯排查难度大

传统的接口管理工具如 Swagger 没有接口修改记录,缺少版本管理,无法通过日志定位问题,无法进行回滚和历史对比。另外团队也缺少接口迭代计划,导致开发量和影响面分析都难以评估。

接口文档作为研发项目的重要资产,应该对其变更进行盘点,包括提供接口文档的历史记录。可以通过一站式 API 全生命周期管理工具,提供项目级的接口版本管理和接口迭代计划,输出更加优质的接口文档,推进 DevOps 工作流的效率提升。

困境六:DevOps 工作流使用工具多

DevOps 作为宏观层面的研发管理思路,目前并没有大而全的工具,因此带来企业内部工具越积越多,数据流通阻滞,另外,传统接口管理工具功能也很单一。

针对这个问题,可以使用一体化的 API 全生命周期管理工具来实现与接口相关的所有问题,减少对接的工具数量。


2、DevOps 中 API 管理需要什么

基于前文对 DevOps 中 API 管理存在的问题,可以梳理出企业 R&D 需要以下六个方面:

  • 规范化: 一个可配置规范、可自动根据规范生成 API 文档的 API 规范工具
  • 高协作: 一个接口相关状态自动流转、精准通知信息的 API 协作工具
  • 自动化: 一个低门槛、智能录入数据的 API 自动化测试工具
  • 高质量: 一个一站式接口全流程质量管理的 API 测试工具
  • 迭代快: 一个提供从项目级迭代计划,版本管控,到接口级历史记录的 API 管理工具
  • 工具链: 一个接口全生命周期且多种对外集成方式的 DevOps 工具

对于满足这些条件的工具,我们定义为 API 全生命周期智能协作平台。在这个一体化平台上,可以从 API 的开发态到发布态到运营态,对 API 进行全生命周期管理


3、API 全生命周期如何接入 DevOps

根据经典的 DevOps 流程图,我们从计划、开发、构建、测试、部署、发布、运维跟监控环节,探讨 API 管理工具对接。



3.1 计划:制定 API 文档规范,搭建层次清晰的 API 仓库

  • 根据公司组织架构和系统服务的分布,组成一个层次清晰的接口仓库。
  • 统一规范制定,把不同团队的规范统一制定成公司的规范。
  • 整理公共材料,把历史文档快捷地导入到 API 仓库里,以及把一些可复用的材料例如经常用的数据结构,API 文档的模板、常用字段描述,都可以存储到 API 仓库,以便于在开发阶段创建新的 API 文档。



3.2 开发:基于代码仓库搭建自动化流程,解决前后端调试和沟通问题

基于代码仓库或 Swagger 或本地研发工具,快速自动生成 API 文档并快速调试,调试没问题后再自动生成 MOCK API和批量接口用例,可以在线分享给前端和测试,文档支持在线评论。最终还可以基于这个 API 文档生成业务代码,协助开发。



3.3 构建:自动打接口版本及自动冒烟测试,支持回滚和减轻测试工程师压力

构建阶段可以基于 CI 触发器自动构建接口版本,方便后续版本回滚,还可基于接口版本做批量测试,以及做版本差异化的对比。

这两个步骤可以让测试对任务进行评估,更好地去减轻测试的压力。目前接口上自动化能测出来的问题,可预先通过 API 测试出来。



3.4 测试:推进自动化测试,降低用例编写成本

在测试阶段我们推荐自动化测试,一体化 API 全生命周期管理工具可以去快速同步前面开发阶段生成的测试用例,然后对这些测试用例进行流程编排,组成自动化测试用例。

也可以基于 API 网关的监控日志做流量回放,自动生成自动化测试用例,识别增量接口并跑模糊测试。可以组成场景案例,做回归测试。模糊测试跟回测试的测试结果发送测试报告,给到对应的测试人员。



3.5 部署:快速测试核心流程,排除环境差异问题

部署之后可以通过 CD 触发器对环境进行预测,试跑核心的测试场景,生成对应的测试报告。可以通过多环境的测试结果进行对比,排查环境差异的问题,也可以在部署好之后进行压力测试。

注:目前 Eolink Apikit 压力测试功能将在年中上线,敬请期待!



3.6 发布:确保对外访问畅通和安全

在发布阶段,主要对接 API 网关,让系统可以正常对外访问,开放接口能力。



3.7 运维:保障服务持续稳定和安全

在运维阶段依然是使用 API 网关,做流量控制、负载均衡或服务治理。在接口开放上可以去做 Open API 调用管控,在线试用跟鉴权。在接口交易上可以去做接口托管、转发跟计算计费以及订单管理。



3.8 监控:实时观察接口运行情况,及时异常告警

可以设置标准的接口监控指标,做更加灵活的监控配置,并对告警进行规则配置预设,当满足这些告警的预设条件时就会发送消息通知,包括手机短信、主流的 IM 工具,以及 Webhook。

在消息通知方面,我们认为不仅仅需要 DevOps 主流程的对接,而是要保证整个 DevOps 信息流的有效和及时传递,因此需要对 API 文档的变更、测试报告、监控告警,进行智能分发。例如进行分级推送、智能归纳、高风险标记等。

【重磅】DevOps 工作流对接 API 全生命周期管理全流程图


4、不同规模团队如何落地实施

4.1 大规模团队:全 DevOps 周期的接口自动化

对于大规模团队来说,推荐基于 DevOps 全周期的接口自动化方案,需部署 Eolink Apikit 私有云版本。在这个方案中,可以把 Swagger 的 URL 自动同步到 Eolink Apikit,自动生成文档,进一步基于文档生成业务代码,然后发送到代码仓库,再去触发 CI 流水线,给文档打版本,做模糊测试,并把报告发送给对应的人员。

接下来在 CD 环节部署好服务之后,可以对环境进行预测试,并根据需求做压力测试,并把测试报告发送给对应的相关人员。除了 CICD,还可以集成 Eolink 的网关产品,对 API 进行运维管理。



4.2 小规模团队:高性价比的接口自动化

对于小规模团队来说,性价比更高的 SaaS 企业版,可以使用插件生成 API 文档上传 Eolink Apikit,并进行测试,自动生成测试用例。

目前该高性价比解决方案,已覆盖从设计、开发到构建、发布、部署的环节,对运维、监控、压力测试等环节尚且缺失,对于核心的 API 全自动化的管理流程已完全足够。


5、总结

本文提出使用一体化的 API 管理平台在 DevOps 工作流中对 API 进行全生命周期管理,解决过去多个工具之间数据隔离、流程阻滞的问题。

API 全生命周期管理平台 Eolink Apikit 是结合 API 设计、文档管理、自动化测试、监控、研发管理和团队协作的一站式 API 研发协作平台,是 API 研发管理最佳实践产品,可以帮助个人开发者到跨国企业用户,快速、规范地对 API 进行全生命周期管理,提高研发效能。

DevOps-8:需求开发生命周期与DevOps系统能力

近期梳理了一下,之前的整个需求开发过程的完整流程,以及二次开发的DevOps系统,在该流程中覆盖的点,主要是从接收到需求,到需求完成上线的整个过程。
整个过程如图:

图中,蓝色节点是团队负责人或项管人员跟进的流程,绿色节点是DevOps系统上操作的节点,
白色的椭圆是普通备注说明,黄色的椭圆是跟DevOps系统关联的节点备注。


关键点说明:

1、代码与需求/任务/Bug关联

当时使用的是腾讯的TAPD作为项目管理和敏捷开发平台,该平台有个特点是支持关联gitlab提交:
在开发过程中的代码提交,按TAPD的格式填写comment(包含需求ID、BugID等),并通过Webhook提交给TAPD的API。
注:可以在Gitlab配置提交规则,强制要求每次提交,都必须符合该格式,即在每个项目的git地址下,配置 custom_hooks/pre-receive 钩子,pre-receive钩子文件内容参考文章最后。

2、生成发布申请

根据1,我们有了需求和代码的提交关系,那么我们在DevOps系统里,选择要发布的需求或Bug,就能自动关联得出,涉及哪几个Git项目,需要发布,就可以:

  • 自动生成发布申请单,包含所有关联的Git项目
  • 自动生成每个Git项目的MR申请
  • 自动推送MR通知消息给这些GIt项目的代码评审人,进行评审
  • 自动推送待发布消息给这些Git项目的开发责任人,进行关注
    • 自动生成每个Git项目的测试与预上的配置差异清单
    • 自动生成每个Git项目对应数据库的表结构差异清单,及刷库SQL
    • 开发负责人确认上述2项,是否需要推送给运维责任人处理
  • 自动推送待发布消息给需求对应的QA、产品经理,进行关注

相关脚本参考

pre-receive文件内容参考

#!/bin/bash

while read oldVersion newVersion branch; do
#  read oldVersion newVersion branch
  echo "do pre-recievt: $oldVersion  $newVersion  $branch"

  # oldrev=`git rev-parse $oldVersion` # 获取该版本的sha1值,貌似多余,传入的参数就是sha1
  # newrev=`git rev-parse $newVersion`
  commitList=`git rev-list $oldVersion..$newVersion` # 获取新旧版本之间,提交了几个版本
  echo $commitList

  # 按空格分割字符串,并遍历
  for commitSha1 in $commitList
  do
    # 获取每次提交的log,正常情况下,log格式如下:
    # $ git cat-file commit 51ffa547167535fffb0f4b87d09022938f8d404b
    # tree ffd5876a90a555eedd605b0e2df606c83840437f
    # parent b78c620aa64b75e6f312a0541e59df3ad8bfca57
    # author youbl <youbl@126.com> 1557478996 +0800
    # committer youbl <youbl@126.com> 1557478996 +0800
    # 
    # 删除验证
    
    # sed '1,/^$/d'表示从第1行删除到第一个空行为止,剩下的就是log了
    msg=`git cat-file commit $commitSha1 | sed '1,/^$/d'`

    # 分支Merge,跳过
    match=`echo "$msg" | egrep 'Merge branch ' `
    if [ -n "$match" ];then continue; fi
    match=`echo "$msg" | egrep 'Merge remote-tracking branch ' `
    if [ -n "$match" ];then continue; fi
    match=`echo "$msg" | egrep '合并分支 ' `  # gitlab上发起的合并请求,会以“合并分支”开头
    if [ -n "$match" ];then continue; fi

    # 验证log是否匹配规则
    match=`echo "$msg" | egrep '\\-\\-story=[0-9]7,' `
    if [ -n "$match" ];then continue; fi
    match=`echo "$msg" | egrep '\\-\\-bug=[0-9]7,' `
    if [ -n "$match" ];then continue; fi
    match=`echo "$msg" | egrep '\\-\\-task=[0-9]7,' `
    if [ -n "$match" ];then continue; fi

    echo "!!! Your submit msg: $msg !!!($commitSha1)"
    echo !!! This submit must be related to tapd with id !!!
    exit 1
  done


# ===========================================================
# 如果要遍历提交的文件,用下面的代码
function eachFiles () 
  diff=`git diff --name-status $oldVersion $newVersion` # 获取2个版本之间,所有版本的差异文件列表,格式: M README.md D db/20181018.sql M db/full.sql A test.md
  echo $diff

  isDel=false
  # 按空格分割字符串,并遍历
  for file in $diff
  do
    if [ "$file" = "D" ];then
      isDel=true  # 删除的文件,要置标志位,忽略下一个遍历
    fi

    # echo $#file  # 输出字符串长度
    if [ "$#file" -lt "2" ];then # 字符串长度小于1时跳过
      continue
    fi
    
    if [ "$isDel" = "true" ];then # 当前文件前面的标志是D,表示删除,不操作
      isDel=false
      continue
    fi

    echo $file
    # fileDiff=`git show $newVersion:$file` # 获取当前文件的内容
    # echo $fileDiff
  done


done

# echo !!!test prevent push!!!
exit 0

定时任务:为新项目添加钩子的sh脚本参考

因为每个git项目,都必须添加上面的钩子文件,那么用户新建git项目时,是不会有这个钩子的,因此需要一个脚本,去遍历新项目,并添加钩子,
在linux的crontab里,指定每小时执行一次下面这个脚本即可。

#!/bin/bash

function eachGitDir()
  for ele in `ls $1`
  do
    subdir="$1/$ele"

    if [ ! -d $subdir ];then continue; fi # 不是目录,跳过

    if [[ $subdir == "/data/gitlab/data/git-data/repositories/Frontend" ]]; then continue; fi # 跳过前端内部项目
    if [[ $ele == "boot" ]]; then continue; fi # 跳过boot项目
    if [[ $ele == "ops" ]]; then continue; fi
    if [[ $ele == "tests" ]]; then continue; fi
    if [[ $ele == *".wiki.git" ]]; then continue; fi
    if [[ $ele == "ToolsProject.git" ]]; then continue; fi # 跳过Tools项目

    if [[ $ele != *".git" ]]; then 
      eachGitDir $subdir
      continue
    fi # 不是git目录,递归
    
    hookdir=$subdir/custom_hooks
    if [ ! -d $hookdir ];then mkdir $hookdir; fi
    hookfile=$hookdir/pre-receive
    if [ -e $hookfile ];then continue; fi # 文件存在,不处理
    `/usr/bin/cp /root/hooks/pre-receive $hookfile`
    echo $hookdir

  done


# repository="/root/tmp"
repository="/data/gitlab/data/git-data/repositories"
eachGitDir $repository

清除所有项目的钩子

有时,需要清理所有项目钩子,重新配置,可以使用这个脚本:

#!/bin/bash

function eachGitDir()
  for ele in `ls $1`
  do
    subdir="$1/$ele"

    if [ ! -d $subdir ];then continue; fi # 不是目录,跳过

    if [[ $ele != *".git" ]]; then 
      eachGitDir $subdir
      continue
    fi # 不是git目录,递归

    hookdir=$subdir/custom_hooks

    if [ ! -d $hookdir ];then continue; fi
    hookfile=$hookdir/pre-receive
    if [ ! -e $hookfile ];then 
      `rmdir $hookdir`
      continue
    fi # 文件不存在,不处理
    `rm -f $hookfile`
    `rmdir $hookdir`
    echo "deleted $hookfile"

  done


# repository="/root/tmp"
repository="/data/gitlab/data/git-data/repositories"
eachGitDir $repository

清除指定项目的钩子

有时,需要清理指定项目的钩子,又懒得去查找目录和删除,可以使用这个脚本:

#!/bin/bash

function eachGitDir()
  for ele in `ls $1`
  do
    subdir="$1/$ele"

    if [ ! -d $subdir ];then continue; fi # 不是目录,跳过

    if [[ $ele != *".git" ]]; then
      eachGitDir $subdir
      continue
    fi # 不是git目录,递归
    
    processHook $subdir
  done


function processHook()
  subdir=$1
  hookdir=$subdir/custom_hooks

  if [ ! -d $hookdir ];then continue; fi
  hookfile=$hookdir/pre-receive
  if [ ! -e $hookfile ];then
    `rmdir $hookdir`
    echo "rmdir $hookdir"
  else
    `rm -f $hookfile`
    `rmdir $hookdir`
    echo "deleted $hookfile"
  fi


ele=$1
if [ "$#ele" -lt "1" ];then # 字符串长度小于1时跳过
  echo 参数不能为空
  exit 1
fi

# 移除前面的http协议和域名
if [[ $ele = http* ]]; then
  ele=`echo $ele | cut -d/ -f4-`
fi

ele="/data/gitlab/data/git-data/repositories/$ele"
if [ ! -d $ele ];then
  ele=$ele".git";
  if [ ! -d $ele ];then
    echo "目录不存在: $ele"
    exit 1
  fi
fi

# echo $ele
if [[ $ele != *".git" ]]; then
  eachGitDir $ele
else
  processHook $ele
fi

以上是关于如何在 DevOps 中进行 API 全生命周期管理?的主要内容,如果未能解决你的问题,请参考以下文章

DevOps建立全生命周期管理

目前有没有DevOps解决方案能保证整个软件包生命周期的安全?

DevOps-8:需求开发生命周期与DevOps系统能力

unity中常用脚本生命周期全解

DevOps生命周期,你想知道的全都在这里了!

DevOps生命周期,你想知道的全都在这里了!