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