AI 年度盘点与2025发展趋势展望,50+案例解析亮相AICon 了解详情
写点什么

简化跨微服务重用,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:009892

评论

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

一文彻底搞懂Raft算法,看这篇就够了!!!

做梦都在改BUG

漫谈 ChatGPT 与问答式 BI

观远数据

数据分析 BI ChatGPT

详解 Flink Catalog 在 ChunJun 中的实践之路

袋鼠云数栈

flink

Flink MongoDB CDC 在 XTransfer 的生产实践|Flink CDC 专题

Apache Flink

大数据 flink 实时计算

四种常见服务限流算法解析

做梦都在改BUG

EasyMR 安全架构揭秘:如何管理 Hadoop 数据安全

袋鼠云数栈

大数据

软件团队文档管理工具哪个好?

爱吃小舅的鱼

团队管理 PingCode 企业文档管理工具

华秋PCB生产工艺分享 | 第十一道之成型

华秋电子

面试官:谈谈分布式一致性机制

Java永远的神

程序员 分布式 微服务 后端 架构师

5 大手段,打造单一可信源代码托管平台|极狐GitLab DevSecOps 助力 SLSA 落地之源代码篇

极狐GitLab

DevOps DevSecOps 源代码 安全审计 SLSA

精选2023年大厂高频Java面试真题集锦(含答案),面试一路开挂

程序知音

java面试 java架构 Java进阶 后端技术 Java面试八股文

MobTech ShareSDK|分享报错怎么办

MobTech袤博科技

关于FTP文件传输协议说明,带你了解更详细的文件传输协议

镭速

GOPS 全球运维大会来了,龙蜥社区邀您一起了解“系统运维”

OpenAnolis小助手

开源 操作系统 内核 龙蜥社区 GOPS全球运维大会

面试还不懂Netty,看这篇文章就够了!

程序员小毕

Java 程序员 后端 Netty 架构师

【福利】ChatGPT免费体验期延长,商用版正式开启预约!

WorkPlus

EMQ&阿里云Lindorm联合方案:解决物联网关键业务场景数据处理难题

EMQ映云科技

阿里云 物联网 IoT 数据处理 企业号 4 月 PK 榜

阿里内部都在疯传!企业级Spring Boot 项目开发实战教程,我先肝了

程序知音

Java 微服务 springboot java架构 Java进阶

携多款产品亮相“深圳先进制造业集群展”,华秋积极探索发展机遇

华秋电子

新旧版本功能对比 | v1.5.0 全新升级

BinTools图尔兹

数据库 社区版 版本更新

PCB拼版对SMT组装的影响,华秋一文告诉你

华秋电子

OpenSea交易平台开发NFT系统部署技术

薇電13242772558

NFT

NFT交易平台商城系统开发技术

薇電13242772558

NFT

现在学C4D还是Blender好?这俩有啥区别?

Finovy Cloud

blender C4D

干货分享|金融机构如何通过标签画像实现精细化客户运营?

索信达控股

Redis崩吗?来一起搞定 Redis 实践中的常见问题!

Steven

redis

苹果电脑软件应用打开出现意外退出、崩溃问题解决办法

互联网搬砖工作者

快手基于 Apache Flink 的实时数仓建设实践

Apache Flink

大数据 flink 实时计算

APP频繁改版惹人烦?火山引擎VeDI来帮忙

字节跳动数据平台

数字化 企业数字化 企业号 4 月 PK 榜 APP改版

行业盛会丨九科信息亮相第十一届中国电子信息博览会(CITE2023),与您共享科技盛宴

九科Ninetech

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