使用 Amazon API Gateway 路由规则动态路由请求

作者： Anton Aleksandrov, Giedrius Praspaliauskas |

有效的 API 管理和路由功能对于管理复杂应用程序架构的组织至关重要。无论你是一家向数百万用户推出新 API 版本的科技公司，还是为优化客户体验而进行 A/B 测试的金融服务组织，动态高效地路由 API 流量的能力都至关重要。

今天，Amazon API Gateway 宣布在所有支持的亚马逊云科技区域中支持自定义域名的动态路由规则。这项新功能使您能够根据 HTTP 标头值单独路由 API 请求，也可以与 URL 路径结合使用。在这篇文章中，您将学习如何在不修改 API 终端节点的情况下使用这种新功能来实现 API 版本控制和逐步部署等路由策略。

动态路由规则概述

许多组织需要动态 API 路由功能来支持其不断变化的业务需求。作为业务线角色，您希望能够测试特定客户群的新用户体验，同时保持其现有流程不变。作为工程师，您希望能够在不同的客户端应用程序中维护多个 API 版本，同时确保合规性。在此次发布之前，使用 API Gateway 的开发人员通过使用不同的 URL 路径（例如 "/v1/products" 和 "/v2/products"）实现了动态路由。

在这次新版本中，您可以在自定义域名设置中通过简单的声明性配置来实现动态路由逻辑。新的路由规则机制允许您根据 HTTP 标头、基本路径或两者的组合做出路由决策。开发人员不再需要创建新的路径或更改现有路径来在 API 版本之间顺利过渡，他们只需在请求 HTTP 标头中指定所需的值即可。除其他可能性外，您可以根据主机名、租户 ID、接受的响应媒体类型或 cookie 值实现基于单元的架构路由、A/B 测试或动态后端选择。通过直接在 API Gateway 中实现路由逻辑，您可以消除代理层和复杂的 URL 结构，同时保持对 API 流量的精细控制。这项新功能与现有 API Gateway 功能无缝集成，并支持公共和私有 REST API。下图显示如何使用路由规则进行基于标题和基本路径的路由。此示例使用单级资源 /products 来显示路径匹配，但是根据您的用例，您也可以使用多级路径，例如 /products/items。

图 1。使用路由规则进行基于标头和基本路径的路由

在下一节中，您将学习如何实现基于标头的路由，在 API 版本控制和 A/B 测试等常见场景中使用新的路由规则结构，以及使用不同的路由条件和优先级配置规则以实现所需的行为。

什么是路由规则

路由规则是一种与单个自定义域唯一关联的新资源类型。它代表了一组条件，这些条件匹配后，将导致传入的请求被转发到特定的 API 和阶段。路由规则有三个配置属性：

  • 条件属性定义了必须满足的条件才能采取行动。一条规则最多可以包含两个标头条件和一个基本路径条件，并且必须满足所有指定条件才能触发该操作。如果没有为规则定义任何条件，则它将充当匹配所有请求的包罗万象的规则。
  • Action 属性定义了满足规则条件时将采取的操作。在本次发布时，支持的操作是在同一账户和区域边界内调用任何 REST API 的任何阶段。
  • Priority 属性定义了规则的评估顺序，其中 1 表示最高优先级，1,000,000 表示最低优先级。不能将相同的优先级值重复用于多个规则。亚马逊云科技建议您在顺序规则之间留出足够的空间，以便将来轻松添加新规则，例如使用 100、200、300 而不是 1、2、3。

通过 matchHeaders 属性指定的标头条件用于匹配 HTTP 请求标头值，例如 x-version=v1。根据 RFC 7230，标头名称不区分大小写，而标头值区分大小写。您还可以在前缀、后缀和包含匹配的标头值中使用通配符。参见以下使用 Amazon CloudFormation 模板的示例：

精确匹配：

- MatchHeaders: 
	AnyOf: 
		- Header: "x-version" 
		ValueGlob: "alpha-v2-latest"

只能匹配 x-version=alpha-v2-latest

前缀匹配：

- MatchHeaders: 
	AnyOf: 
	- Header: "x-version" 
	ValueGlob: "*latest"

匹配 x-version=alpha-v2-latest，但不匹配 x-version=alpha-v2

后缀匹配：

- MatchHeaders: 
	AnyOf: 
		- Header: "x-version" 
		ValueGlob: "alpha*"

将匹配 x-version=alpha-v2-latest 和 x-version=alpha-v1，但不匹配 x-version=beta-v1

前缀和后缀匹配：

- MatchHeaders: 
	AnyOf: 
		- Header: "x-version" 
		ValueGlob: "*v2*"

匹配 x-version=alpha-v2-latest 和 x-version=beta-v2-test，但不匹配 x-version=alpha-v1

通过 matchBasePaths 属性指定的基本路径条件用于匹配传入的请求路径。匹配区分大小写。

- MatchBasePaths: 
	AnyOf: 
		- "products"

每个路由规则最多可以有两个匹配标头和一个 matchBasePaths 条件。使用 AND 运算符评估条件，这意味着必须满足所有条件才能采取操作。两种条件类型都支持 anyOf 属性下的单一比较值。以下代码段说明了具有两个 matchHeaders 条件和一个 matchBasePaths 条件的路由规则示例。

ProductsV1RoutingRule: 
	Type: 'AWS::ApiGatewayV2::RoutingRule' 
	Properties: 
		DomainNameArn: !Sub "arn:aws:apigateway:${AWS::Region}::/domainnames/${ApiCustomDomain}" 
		Priority: 100 
		Conditions: 
			- MatchHeaders: 
				AnyOf: 
					- Header: "x-version" 
					ValueGlob: "v2" 
			- MatchHeaders: 
				AnyOf: 
					- Header: "x-user-cohort" 
					ValueGlob: "beta-testers" 
			- MatchBasePaths: 
				AnyOf: 
					- "products" 
		Actions: 
				- InvokeApi:
					ApiId: !Ref ProductsV2Api 
					Stage: !Ref ProductsV2Stage

当两个标头条件（x-version=v2 和 x-user-cohort=beta-testers）都满足时，此规则会匹配向 https://example.com/products 发出的请求。此规则不匹配对任何其他基本路径（例如 https://example.com/orders）的请求，或不匹配至少一个标头条件的请求。

对于 API 版本控制等场景，您可以创建评估标头（例如 "接受" 或 "版本"）的规则，将流量路由到不同的 API 实现。例如，要将包含 "x-version: api-beta" 的请求路由到您的测试版 API，您需要创建一条指定此标头条件的规则，并将操作设置为路由到您的测试版 API 部署。

基于标头的路由还允许您根据自定义标头定义客户端群组，允许使用不同的配置进行对照实验，从而简化了 A/B 测试。您可以创建规则来检查自定义标头（如 "x-test-group"），将特定用户路由到不同的 API 实现。优先级系统确保了可预测的路由行为——当多个规则匹配一个请求时，优先级数值最低（最高优先级）的规则决定路由。将标头和路径条件组合到单个规则中可实现复杂的路由方案，例如针对特定 API 资源而不是整个 API 的版本特定路由，如下图所示。

图 2。API Gateway 控制台中具有两个标头和一个路径条件的路由配置。

查看 API Gateway 文档，了解有关创建路由规则的详细指南。

配置路由模式

在开始创建路由规则之前，必须先创建至少一个 API、阶段和一个自定义域名。您可以使用新的路由模式设置来配置您的自定义域名。

  • 仅限 API 映射。这是默认模式。使用此模式时，您可以继续使用基本路径映射将请求路由到不同的 API，而根本不使用路由规则。此模式保持了当前的行为，即请求仅根据基本路径映射进行路由。
  • 路由规则，然后是 API 映射。在此模式下，您可以使用路由规则，同时继续将基本路径映射保留为备用路径。使用此模式时，路由规则始终优先，不匹配的请求会根据基本路径映射进行评估。此模式对于逐步将 API 过渡到路由规则很有用。
  • 仅限路由规则。此模式使您可以灵活地仅使用路由规则，而不必依赖之前使用 API 映射在域上创建的基本路径。这是推荐的路由模式；当您开始使用新的自定义域或完成从 API 映射到现有自定义域的路由规则的过渡时，它会很有用。

从一种路由模式切换到另一种路由模式时，请务必先在非生产环境中测试您的新配置。例如，当将模式从仅限 API 映射切换到仅限路由规则时，您的流量将仅使用路由规则路由；现有的 API 映射将不再生效。

入门到基于标头的路由

您可以采用零停机时间、风险最小化的方法，对现有的 API Gateway 自定义域采用新的基于标头的路由。第一步是使用 API Gateway 控制台、亚马逊云科技 CLI 或基础设施即代码 (IaC) 工具将您的自定义域配置为使用路由规则，然后使用 API 映射模式。此配置可确保在您逐步创建路由规则的同时，现有的基本路径映射继续用作备用路由。由于路由规则是在基本路径映射之前评估的，并且在没有任何匹配规则的情况下，请求会自动回退到您现有的基本路径映射，因此在此过渡期间，您当前的 API 流量不会受到影响。

配置路由模式后，可以在现有设置的基础上逐步引入路由规则。例如，您可以先创建一个带有特定测试标头的规则，该规则会路由到新的 API 版本，从而允许您在生产流量继续流经现有基本路径映射的同时，使用受控的测试流量来验证路由行为。当您对新的路由配置充满信心时，您可以逐步扩展规则，调整优先级，并有选择地完全放弃基本路径映射。这种渐进式方法与下一节中描述的 API Gateway 的可观察性功能相结合，使您能够验证每项更改，并确保您的 API 使用者在过渡期间不会受到任何干扰。

可观测性

API Gateway 让您可以全面了解您的路由规则如何通过访问日志处理请求。现在，每个请求都包含额外的上下文变量，可帮助您了解路由决策过程。$context.customDomain.routingRuleIdMatched 变量用于标识匹配哪条规则并将其应用于请求，而 $context.domainName、$context.apiId 和 $context.stage 等现有变量则提供完整的路由上下文。通过分析这些访问日志，您可以验证路由行为，对意外路线进行故障排除，并收集有关不同 API 版本或测试变体的流量模式的见解。

端到端示例

以一个真实场景为例，团队需要逐步将用户迁移到新的 API 版本，例如电子商务平台将其结账 API 从 v1 更新到 v2。首先，该团队创建了两个不同的 REST API，每个版本一个。然后，他们设置了优先级为 100 的路由规则，该规则检查标头 x-version=v2 并将匹配的请求路由到 v2 API。他们还创建了另一条优先级为 200 的规则，将所有路径以 /checkout 开头的请求路由到 v1 API 作为备用。

图 3. 逐步将客户端从 v1 过渡到 v2 API。

在应用程序代码中，他们为一小部分用户添加了 x-version 标头。他们通过跟踪访问和执行日志以及发出的指标，使用 API Gateway 的遥测功能来监控性能和错误率。随着信心的增强，他们逐渐增加了发送 v2 标头的用户百分比。这种方法可确保受控迁移，将风险降至最低，并且只需从请求中删除标头或更改路由规则即可快速回滚。

示例

按照此 GitHub 存储库中的说明在您的亚马逊云科技账户中预置示例。该项目说明了在 API Gateway 中使用动态路由。

结论

基于标头的路由为 API Gateway 用户带来了显著的优势。该功能的向后兼容性确保了平稳的过渡路径——您可以在逐步采用路由规则的同时保持现有的基本路径映射，也可以将两种机制与备用选项同时使用。这种灵活性使您可以按照自己的节奏进行迁移，而不会中断现有应用程序。该解决方案具有成本效益，在 REST API 上使用路由规则无需额外付费。它减少了利用额外服务和基础设施进行动态路由的要求。基于优先级的评估系统提供确定性的路由行为，使其更易于理解和排除路由决策故障。

要了解有关基于 API Gateway 标头的路由的更多信息，请参阅服务文档。

要了解有关无服务器架构的更多信息，请参阅 Serverless Land。

*前述特定亚马逊云科技生成式人工智能相关的服务仅在亚马逊云科技海外区域可用，亚马逊云科技中国仅为帮助您发展海外业务和/或了解行业前沿技术选择推荐该服务。