10 月 23 - 25 日,QCon 上海站即将召开,现在购票,享9折优惠 了解详情
写点什么

简化跨微服务重用,API 标准化过程中的左移法

作者:Thiyagarajan Kamaraj

  • 2022-10-29
    北京
  • 本文字数:2737 字

    阅读完需:约 9 分钟

简化跨微服务重用,API标准化过程中的左移法

什么是 API 标准化?

API 设计就是创建一个有效的接口,使你可以更好地维护和实现 API,同时使消费者能够轻松地使用这个 API。


一致的 API 设计意味着,在组织或团队中对所有 API 及其公开的资源进行标准化设计。它是开发人员、架构师和技术作者共同遵守的蓝图,可以保证在 API 使用过程中品牌和体验的一致性。风格指南旨在确保 API 设计和实现方式的一致性,组织就是用它来标准化设计。下面是比较流行的两份风格指南:


  1. 微软REST API指南

  2. 谷歌API设计指南在业余项目里,为了开发出一致的 API,并遵循 API 开发的行业最佳实践,我经常参考这本风格手册

为什么要标准化?

清晰的设计方法可以确保 API 与业务需求相一致。API 越标准,歧义就越少,合作成果就越多,质量就更有保障,API 的采用也会相应增加。


清晰一致的 API 设计标准是良好开发体验和消费体验的基础。它们使开发人员和消费者都能够快速有效地理解 API,缩短学习曲线,并按照一套指南进行构建。


API 标准化还可以改善团队协作,提供提升准确性和降低延迟的指导原则,有助于降低总开发成本。标准对于 API 策略的成功如此重要,以至于许多科技公司(如微软、谷歌和 IBM)以及行业组织(如 SWIFT、TMForum 和 IATA)都使用并支持 OpenAPI 规范(OAS),并将其作为定义 RESTful API 的基本标准。


如果不进行标准化,那么个体开发人员在设计过程中就可以随意选择。虽然我们鼓励创造,但如果没有适当的风格指南,很快就会变得混乱。


如果不进行标准化,那么组织就无法在 API 设计和交付过程中提供质量保证。强化设计标准有助于提升预测成功结果的能力,让组织能够在保证质量的前提下快速扩展 API 开发。

API 标准化之旅

如果没有一个正式的流程来强化标准化,就不可能成功地扩展 API 设计和开发过程,也不可能符合监管和行业标准。API 设计风格指南提供了内外部团队在构建 API 定义和重用资产时开展协作所需的“护栏”。


最初,组织在内部以 PDF 或 Wiki 的形式发布 API 指南,供所有人参考,并制定相应的流程以确保团队遵循设计指南。确保开发一致性的一种方案是在 API 开发期间进行人工评审。


API 以OpenAPI格式指定,并在版本控制系统中维护,API 定义可以遵循与其他代码工件相同的评审过程。开发人员可以为 API 更改创建 pull 请求,并让同事提供反馈。这个过程是手动的,是保障治理以及确保遵循 API 指南的有效方法,但与所有手动过程一样,它容易受人为错误所影响,而且有时候不及时。


等待同事评审 API 更改可能会导致周期变慢,对开发人员的工作效率产生不利的影响,特别是涉及到评审过程中可以自动化的方面时。当组织规模扩大,更多的开发人员开始参与 API 开发时,这个过程也无法扩展。在这种情况下,可以提供 API 自动评审的左移法就很有用了。就像我们对其他工件所做的那样,借助一些自动化工具或分析器尽早获得反馈,这样最好了。

什么是左移法?

术语“左移”指的是软件开发中的一种实践。在这种实践中,团队会比以往更早地开始测试,帮助自己聚焦质量,致力于问题预防而不是检测。左移的目标是提高质量,缩短漫长的测试周期,并降低在开发周期结束时(或者更糟,在生产环境中)出现令人不快的意外情况的可能性。

Open API 验证器

说到 OpenAPI分析器,我见过一些。它们将 API 风格指南转换为一组规则,并根据 Open API 规范进行验证。这些分析器允许你根据组织风格指南自定义规则。一个名为Zally的分析器引起了我的注意,它是一个用 Kotlin 编写的工具,由 Zalando 开源。OpenAPI 风格指南验证器的工作流程如下:


  1. 将 API 标准或风格指南表示成一组规则。这里有 Zalando 提供的一份指南;

  2. 根据OpenAPI编写 API;

  3. 像 Zally、SonarQube、Spectra 这样的检测工具可以验证开发人员编写的 OpenAPI 规范是否符合第 1 步中定义的规范规则。

Zally 是什么?

Zally是一个简单易用的 API 分析器。它的标准配置是根据Zalando RESTful指南中定义的规则检查 API,对任何人来说都是开箱即用的。它具有可扩展性,允许我们添加自己的规则集。它还提供以下特性:


  • 根据需要在服务器端启用/禁用规则;

  • 接受 JSON 和 YAML 格式的 Swagger V2 和 OpenAPI V3 规范;

  • 可以编写并插入自己的规则;

  • 直观的Web UI显示了实现的规则和规范验证的结果;

  • 使用 Web 钩子集成 GitHub,验证每个 pull 请求中的 OpenAPI,并在评论中回显违规情况。

Zally Gradle 插件背后的动机

虽然 Zally 的编写方式更具可扩展性和可定制性,但我觉得,我们仍然可以进一步改进 Zally 当前的验证工作流,缩短开发反馈循环。由于 Zally 缺少像 checkstyle、ktlint、spot bug 这样的插件,所以我在使用 Zally 时遇到了以下几个痛点:


  • 为了使用 CLI 工具,开发人员需要在本地或远程系统上托管 Zally 服务器;

  • 开发人员需要切换运行 CLI 工具的上下文,或是额外做一些工作,将 CLI 配置为 Maven/Gradle 构建过程的一部分,前提是第一条已经满足;

  • 在每个 pull 请求中使用 GitHub 集成组件验证 API 会增加反馈循环时间。所有这些都增加了向开发人员反馈的时间,并且还有托管 Zally 服务器的人工开销。所以我决定编写自己的 Gradle 插件,它既可以集成在本地开发环境中,也可以集成在 CI 工具中,帮助我验证和提取不同格式的验证结果。

定制 Zally 插件

zally-gradle-plugin是一个用 kotlin 编写的 Gradle 插件,可以集成到构建脚本中。该插件根据规则集验证规范,并提供 JSON 和 HTML 格式的报告。


该项目包含一个示例任务配置


// settings.gradle.ktspluginManagement {    repositories {        gradlePluginPortal()        mavenLocal()    }}
// build.gradke.ktsplugins { id("io.github.thiyagu06") version "1.0.2-dev"}
zallyLint { inputSpec = File("${projectDir}/docs/petstore-spec.yml") reports { json { enabled = true destination = File("${rootDir}/zally/violation.json") } rules { must { max = 10 } } }}
//execute task./gradlew clean zallyLint
``````Run ZallyLint task./gradlew zallyLint
复制代码


有了这个 Gradle 插件,我就可以在 API 开发过程中实时获得反馈。这使我能够在进入手动检查步骤之前修复 API 的问题。该插件还可以与 CI 作业集成,用于风格指南的检查验证。因为所有开发团队都使用相同的规则,所以组织就可以为用户提供更加一致的 API。该方法大致有如下好处。该插件提供了一个选项,可以将违规报告导出为 JSON 和 HTML 格式。它还提供了一种简单的规则配置方法,用于定义每个严重性级别下规范中可以存在的最大违规数。


可以将 JSON 格式解析并导出到任何数据库中,用于计算 API 设计兼容性得分,并构建一个仪表板,共享给更广泛的组织,作为 API 标准化方案的决策依据。同样,HTML 报告也可以导出到 S3 桶或谷歌云存储,并以网站的形式提供给更广泛的受众。


原文链接:

https://www.infoq.com/articles/shift-left-api/


2022-10-29 08:0010072

评论

发布
暂无评论
发现更多内容

Shibboleth IdP4 升级指南

冯骐

认证 Shibboleth IdP 上海教育认证 上海教育

详解NLP和时序预测的相似性(附赠AAAI21最佳论文INFORMER的详细解析)

华为云开发者联盟

自然语言处理 深度学习 时序预测 RNN Informer

Pano React Native SDK 来了!快速实现移动端音视频和白板

拍乐云Pano

flutter ios android RTC React Native

笔记整理:技术架构涵盖内容和演变过程总结

小傅哥

Java 程序员 小傅哥 架构设计 架构图

KubeEdge 1.6发布:可靠的K8s原生边云API

华为云原生团队

开源 云原生 边缘技术 kubeedge

百分点大数据技术团队:数据治理“PAI”实施方法论

百分点大数据团队

人民网:亚马逊云科技,以这样姿势扎根中国!

亚马逊云科技 (Amazon Web Services)

SQL Server 删除正在使用数据库

田镇珲

一个简单实用的Linux性能分析工具

运维研习社

Linux 性能分析

工作中,有哪些SQL是我们必须要掌握的?

xiezhr

oracle sql SQL语法 3月日更

大赛报名|首次聚焦口罩场景!第三届 106 点关键点定位大赛开启

京东科技开发者

人工智能 深度学习 计算机视觉

是什么支持“毅力号”在火星上尽情摄影?

亚马逊云科技 (Amazon Web Services)

报名 | 全球首个小资源音色克隆赛结果出炉,高分队伍线上报告会

爱奇艺技术产品团队

中国程序员最容易发错的单词

happlyfox

GitHub 学习 程序人生 3月日更

2021 创新加速周蓄势待发,铆足牛劲再出发!

亚马逊云科技 (Amazon Web Services)

英特尔:i7-10870H 游戏性能超 R7 5800H,更强的 11 代酷睿 H 在后面

E科讯

互联网短平快下,DevCloud如何支撑软件开发的“转型”?

华为云开发者联盟

android 敏捷开发 软件开发 华为云 devcloud

百分点数据科学实验室:产品生命周期管理创新应用落地实践

百分点大数据团队

百亿级流量的百度搜索中台,是怎么做可观测性建设的?

百度Geek说

中台 云原生 #百度#

农田治理效率低下还赔本?智慧农业力保粮食品质,效率事半功倍

一只数据鲸鱼

物联网 数据可视化 智慧城市 智慧农业 农业管理

Kubectl Plugin 推荐(一)| 可观测性篇

郭旭东

kubectl kubectl plugin

云小课丨网络好不好,ping一下就知道

华为云开发者联盟

网络 虚拟私有云 ping ICMP 安全组

华云大咖说 | 高校混合云建设及应用

华云数据

力扣(LeetCode)刷题,简单+中等题(第32期)

不脱发的程序猿

算法 LeetCode 编程能力 28天写作 3月日更

【LeetCode】用栈实现队列Java题解

Albert

算法 LeetCode 28天写作

金三银四如何突击面试美团?面试题(含答案)+学习笔记+电子书籍+学习视频

比伯

Java 编程 架构 面试 程序人生

滚雪球学 Python 第二轮开启,进阶之路,列表与元组那些事儿

梦想橡皮擦

28天写作 3月日更

25个关键技术点,带你熟悉Python

华为云开发者联盟

Python

智汇华云 | ArcherOS Stack—软件定义数据中心“利器”

华云数据

建信金科大咖访谈:金融科技驱动业务创新,智慧运营引领发展转型

金科优源汇

酷睿i7-10870H对比锐龙7 5800H游戏性能, 英特尔仍是游戏本CPU的更优选

E科讯

简化跨微服务重用,API标准化过程中的左移法_架构_InfoQ精选文章