API 驱动开发

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

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

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

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

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

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

API 开发测试

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

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

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

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

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

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

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

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

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

::: tip 提示

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

:::

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

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

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