REL03-BP03 根据 API 提供服务合同
服务合同是 API 生产者与使用者之间的书面协议,采用机器可读的 API 定义形式进行定义。合同版本控制策略让使用者能够继续使用现有的 API,并在更新的 API 准备就绪时,将其应用程序迁移到更新的 API。只要遵守合同,生产者部署可随时进行。服务团队可以使用自己选择的技术堆栈来满足 API 合同要求。
期望的结果:
常见反模式: 使用服务导向型架构或微服务架构所构建的应用程序能够独立运行,但具有集成的运行时系统依赖项。当双方都遵循共同的 API 合同时,向 API 使用者或生产者部署更改并不会影响整个系统的稳定性。通过服务 API 进行通信的组件能够独立执行功能发布、升级到运行时系统依赖项或者失效转移到灾难恢复(DR)站点,而彼此之间的影响很小,或者根本没有影响。此外,离散服务能够独立扩展来满足资源需求,无需统一扩展其他服务。
-
创建不使用强类型架构的服务 API。这样, API 不能用来生成无法通过编程方式验证的 API 绑定和有效负载。
-
不采用版本控制策略,会迫使 API 使用者在服务合同变化时进行更新和发布,否则会出现故障。
-
错误消息会泄露基础服务的实施细节,而不是按照域环境和语言描述集成故障。
-
不使用 API 合同开发测试用例和模拟 API 实施,以便对服务组件进行独立测试。
建立此最佳实践的好处: 分布式系统由通过 API 服务合同进行通信的组件组成,可以提高可靠性。开发人员可以在开发过程的早期发现潜在问题,在编译期间进行类型检查,来验证请求和响应是否符合 API 合同以及是否存在必填字段。API 合同为 API 提供了清晰的自描述接口,并在不同的系统和编程语言之间提供了更好的互操作性。
未建立这种最佳实践的情况下暴露的风险等级: 中
实施指导
确定业务领域并确定工作负载划分后,即可开发服务 API。首先,为 API 定义机器可读的服务合同,然后实施 API 版本控制策略。在准备好通过 REST、GraphQL 等常见协议或异步事件来集成服务时,您可以将 AWS 服务整合到架构中,从而将您的组件与强类型的 API 合同集成。
面向服务 API 合同的 AWS 服务
将 AWS 服务(包括 Amazon API Gateway
实施步骤
-
首先,为您的 API 定义一个合同。合同将说明 API 的功能,并为 API 的输入和输出定义强类型的数据对象和字段。
-
在 API Gateway 中配置 API 时,您可以导入和导出端点的 OpenAPI 规范。
-
导入 OpenAPI 定义 可简化 API 的创建过程,并可与 AWS 基础设施即代码工具(例如 AWS Serverless Application Model
和 AWS Cloud Development Kit (AWS CDK) )集成。 -
导出 API 定义 可简化与 API 测试工具的集成,并为服务使用者提供集成规范。
-
-
要使用 AWS AppSync 定义和管理 GraphQL API,您可以 定义 GraphQL 架构 文件来生成合同接口,并简化与复杂的 REST 模型、众多数据库表或传统服务的交互。
-
AWS Amplify
项目与 AWS AppSync 集成后,会生成强类型的 JavaScript 查询文件供应用程序使用,还会生成 AWS AppSync GraphQL 客户端库供 Amazon DynamoDB 表使用。 -
当您使用来自 Amazon EventBridge 的服务事件时,事件遵循架构注册表中已有的架构或您使用 OpenAPI 规范定义的架构。通过在注册表中定义架构,您还可以从架构合同生成客户端绑定,以将代码与事件集成。
-
扩展 API 或者实施 API 版本控制。在添加可以配置为可选字段的字段时,或者为必填字段添加默认值时,扩展 API 是一种相对比较简单的选项。
-
对于 REST 和 GraphQL 等协议,基于 JSON 的合同可能非常适合合同扩展。
-
对于 SOAP 等协议,基于 XML 的合同应与服务使用者一起进行测试,来确定合同扩展的可行性。
-
-
对 API 进行版本控制时,可以考虑实施代理版本控制,其中使用 Facade 模式来支持版本,这样就能够在单个代码库中维护逻辑。
-
通过 API Gateway,您能够使用 请求和响应映射 ,通过建立 Facade 模式为新字段提供默认值,或者从请求或响应中除去已删除的字段,从而简化接受合同变更的过程。通过这种方法,底层服务可以维护单个代码库。
-
资源
相关最佳实践:
相关文档:
相关示例:
相关视频:
相关工具: