作者 | Thiyagarajan Kamaraj
译者 | 平川
策划 | 丁晓昀
什么是 API 标准化？
API 设计就是创建一个有效的接口，使你可以更好地维护和实现 API，同时使消费者能够轻松地使用这个 API。
一致的 API 设计意味着，在组织或团队中对所有 API 及其公开的资源进行标准化设计。它是开发人员、架构师和技术作者共同遵守的蓝图，可以保证在 API 使用过程中品牌和体验的一致性。风格指南旨在确保 API 设计和实现方式的一致性，组织就是用它来标准化设计。下面是比较流行的两份风格指南：
- 微软 REST API 指南
- 谷歌 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 风格指南验证器的工作流程如下：
将 API 标准或风格指南表示成一组规则。这里有 Zalando 提供的一份指南；
根据 OpenAPI 编写 API；
像 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/
声明：本文为InfoQ翻译，未经许可禁止转载。
点击底部阅读原文访问 InfoQ 官网，获取更多精彩内容！
今日好文推荐
对话iPod之父：这不是互联网最坏的年代
“羊了个羊”背后公司清仓式分红10亿元；Meta元宇宙部门今年已亏94亿美元；微软称GitHub年收入10亿美元｜Q资讯
全面审查Twitter代码、当场炒掉CEO等众多高管：马斯克正式入主Twitter
字节跳动开源BitSail：重构数据集成引擎，走向云原生化、实时化
