API 驱动开发

API First 原则

API First 原则即优先设计和完成 API，随后再安排其他事项，其主要优势如下：

进行 API 设计前必须清楚梳理业务逻辑，并明确功能边界和数据交互格式。

微服务架构要求服务单元功能内聚、职责单一，此类要求均可在 API 设计阶段作出清晰界定。高度抽象的 API 有利于刻画功能框架，从而避免过早陷入繁复的设计之中。

相比功能设计文档，规范的 API 文档显得更为清晰、更便于维护。API 定义中的结构化数据格式可直接用于后续的功能实现及场景测试。

参与项目研发的前后端工程师、测试工程师均可基于 API 开展各自的工作。

一致的 API 可解偶依赖，有效协同各方工作，从而实现并行开发。

微服务开发同样提倡 API First 原则，优先完成不同模块的 API 设计，确定功能边界并避免循环依赖，随后开发工程师再完成各自负责模块的功能逻辑实现。

API 提供者的工作流程主要包括：设计 > 发布 > 自测 > 缺陷修复。

平台基于 OpenAPI 3.0 标准协议，并通过可视化界面支持 API 编辑，同时实践 RESTful 规范，从而轻松完成 API 设计。

平台遵循配置即代码的 GitOps 理念，在可视化编辑的同时，API 文档将自动保存至 Git 仓库，便于后续跟踪修改，并支持快速回滚。

完成 API 开发后，您可将 API 直接发布至集市，随后创建访问管理并进行 API 测试。

API 调用方的工作流程主要包括：查阅 > 调用 > 联调 > 缺陷修复。

调用方可进入 DevOps 平台 > API 管理 > API 集市 查看已发布的 API 文档，点击 申请调用 获取客户端的 ClientID 和 ClientSecret，随后完成调用端编码。

若联调测试过程中 API 调用报错，需注意 API 定义是否发生变化，可通过 Git History 进行排查。

测试工程师通过 API 完成接口测试的流程主要包括：查阅 > 设计接口测试场景 > 执行测试 > 提交缺陷。

设计测试用例场景时可直接搜索 API 市场，获取接口定义。

完成开发测试进入生产运行后，建议重新发布一份 API 文档并绑定生产环境的应用实例，随后授权客户端进行访问。

::: tip 提示

后续迭代将持续优化 API 文档与多个运行环境的关联关系。

:::

平台采用语义化版本机制以实现 API 文档的版本管理。版本号格式形如 major.minor.patch。

版本化管理的优势在于将 API 文档的增长与应用程序的增长一视同仁，可从 API 角度审视应用程序的功能。版本号用于解释服务更迭间的兼容性和依赖关系，无论提供者抑或调用方，均可根据版本号语义清晰了解服务的变更情况。

major.minor.patch 版本中 minor 和 patch 版本提升时，所有的 API 必须保持向下兼容。

若 major 版本提升，需确保不兼容的 API 调用方已完成适配。建议通过新增 API 实现新功能，保留旧 API 并通知调用方切换至新接口，直至所有调用方均已完成切换后再行下线。