7. 【.NET 8 实战--孢子记账--从单体到微服务--转向微服务】--微服务基础工具与技术--Ocelot 网关--路由

路由是API网关的核心功能，对系统性能和可靠性至关重要。路由通过定义规则，将客户端请求准确地转发到相应的后端服务，确保请求能够正确处理，简化了微服务架构中的服务调用逻辑。有效的路由配置能够提高系统的灵活性和可维护性。

一、路由配置

1.1 路由基础

在Ocelot中，路由是将上游客户端请求映射到下游服务的一种机制。通过配置路由，Ocelot可以根据特定的规则，将客户端的请求转发到相应的后端服务。路由的定义是Ocelot的核心功能之一，它确保了请求能够被正确处理和响应。

1. 路由的基本组成部分

   一个Ocelot路由通常由以下几个关键部分组成：

   • 上游路径模板（Upstream Path Template） ：这是客户端请求的路径。Ocelot根据这个路径匹配客户端的请求，并决定是否进行路由。例如，/users表示所有请求https://gateway.com/users的客户端请求将被匹配。
     • 下游路径模板（Downstream Path Template） ：这是后端服务的路径。Ocelot将客户端请求转发到这个路径。例如，/api/users表示请求将被转发到http://backend.com/api/users。
     • 下游主机和端口（Downstream Host And Ports） ：这是后端服务的主机名和端口号。Ocelot将请求转发到指定的主机和端口。例如，Host: "localhost", Port: 5001表示请求将被转发到localhost:5001。
     • 上游HTTP方法（Upstream Http Method） ：指定允许的HTTP方法（如GET、POST等）。Ocelot会根据请求的方法匹配路由规则。例如，["GET"]表示只允许GET请求匹配该路由。

2. 路由参数的使用

   Ocelot支持在路径中使用参数，从而实现动态路由。路径参数使用大括号{}包裹，例如，/users/{userId}可以匹配/users/123或/users/abc，其中userId为路径参数。

1.2 上游路径与下游路径

在Ocelot中，上游路径（Upstream Path）和下游路径（Downstream Path）是定义路由规则的两个重要组成部分。它们在API网关的请求转发过程中起着关键作用。了解这两个概念有助于更好地配置和使用Ocelot。

1. 上游路径（Upstream Path）
   上游路径是指客户端发送请求时使用的路径，是Ocelot用于匹配和识别请求的关键字段。上游路径通常与客户端应用程序的URL结构相关联，通过定义上游路径，Ocelot可以确定哪些请求应该被路由到特定的后端服务。
   上游路径使用UpstreamPathTemplate字段进行配置。它支持路径参数和静态路径。路径参数使用大括号{}包裹，表示可以匹配动态值。例如：

   "UpstreamPathTemplate": "/users/{userId}"

   这个配置表示上游路径可以匹配诸如/users/123或/users/abc等请求，其中userId是动态值。这种动态路径匹配使得Ocelot能够处理多种复杂的请求场景。

2. 下游路径（Downstream Path）
   下游路径是指Ocelot将请求转发到后端服务时使用的路径。它定义了实际服务端点的路径结构。Ocelot通过下游路径将上游请求映射到具体的后端服务，实现请求的转发和处理。
   下游路径使用DownstreamPathTemplate字段进行配置。与上游路径类似，它也支持路径参数和静态路径。路径参数可以与上游路径中的参数对应，以便在请求转发时传递动态值。例如：

   "DownstreamPathTemplate": "/api/products/{productId}"

   这个配置表示Ocelot会将请求转发到后端服务的/api/products/{productId}路径，其中productId是从上游路径中提取的动态值。

3. 上游路径与下游路径的关系
   上游路径和下游路径之间的关系是通过路径参数进行映射的。当Ocelot接收到一个上游请求时，它会根据上游路径模板进行匹配，并提取路径参数的值。然后，这些参数值将被用于构建下游路径，从而实现请求的转发。

1.3 路由参数的使用

路由参数是路径模板中的占位符，用于匹配和提取请求路径中的动态部分。路径参数使用大括号{}包裹，如{parameterName}。在Ocelot中，路由参数可以出现在上游路径模板和下游路径模板中，用于实现动态路由和请求转发。

Ocelot也支持在路径模板中使用多个路由参数。例如：

"UpstreamPathTemplate": "/users/{userId}/orders/{orderId}"
"DownstreamPathTemplate": "/api/users/{userId}/orders/{orderId}"

这个配置表示，上游路径可以匹配诸如/users/123/orders/456的请求，并将userId和orderId参数值传递到下游路径中。

1. 可选路由参数

   在某些情况下，路径参数可能是可选的，Ocelot支持使用问号?表示可选参数。例如：

   "UpstreamPathTemplate": "/products/{productId?}"

   这个配置表示，上游路径可以匹配/products和/products/123的请求，其中productId是可选参数。

2. 包含默认值的路由参数

   Ocelot还支持为路由参数指定默认值。例如：

   "UpstreamPathTemplate": "/orders/{orderId=defaultOrderId}"

   这个配置表示，如果请求路径中没有提供orderId参数，将使用默认值defaultOrderId。

3. 正则表达式路由参数

   为了更精确地匹配路径参数，Ocelot支持在路径参数中使用正则表达式。例如：

   "UpstreamPathTemplate": "/products/{productId:regex(^\\d+$)}"

   这个配置表示，productId参数必须是一个或多个数字，否则请求将不匹配该路径模板。

4. 动态API版本控制

   路由参数可以用于实现动态的API版本控制。例如：

   "UpstreamPathTemplate": "/api/v{version}/products/{productId}"
   "DownstreamPathTemplate": "/api/v{version}/products/{productId}"

   这个配置表示，上游路径可以匹配诸如/api/v1/products/123和/api/v2/products/456的请求，并将version和productId参数值传递到下游路径中，实现不同版本API的路由。

5. 多语言支持

   路由参数还可以用于实现多语言支持。例如：

   "UpstreamPathTemplate": "/{lang}/products/{productId}"
   "DownstreamPathTemplate": "/api/{lang}/products/{productId}"

   这个配置表示，上游路径可以匹配诸如/en/products/123和/fr/products/456的请求，并将lang和productId参数值传递到下游路径中，实现不同语言的请求路由。

1.4 示例配置解析

以下是常见的路由配置示例：

{
  "Routes": [
    {
      "DownstreamPathTemplate": "/api/v{version}/products/{productId?}",
      "DownstreamScheme": "http",
      "DownstreamHostAndPorts": [
        {
          "Host": "localhost",
          "Port": 7000
        }
      ],
      "UpstreamPathTemplate": "/{lang}/v{version}/products/{productId:regex(^\\d+$)=defaultProductId}",
      "UpstreamHttpMethod": [ "GET" ]
    }
  ],
  "GlobalConfiguration": {
    "BaseUrl": "https://api.example.com"
  }
}

在这个配置中，Routes节点包含了一个路由配置，定义了从上游请求到下游服务的映射规则。DownstreamPathTemplate字段定义了下游服务的路径模板，其中{version}表示API版本参数，{productId?}表示可选的路径参数，如果未提供productId则下游路径为/api/v{version}/products。DownstreamScheme字段定义了下游服务使用的协议，在这个示例中，下游服务使用HTTP协议。DownstreamHostAndPorts字段定义了下游服务的主机名和端口号，下游请求将会被转发到指定的主机和端口，在这个示例中，下游服务运行在localhost的7000端口。
UpstreamPathTemplate字段定义了上游请求的路径模板，其中{lang}表示语言参数，{version}表示API版本参数，{productId:regex(^\\d+$)=defaultProductId}表示路径参数，必须是数字，如果未提供则使用默认值defaultProductId。例如，请求路径/en/v1/products/123将会匹配这个模板，并将参数值传递到下游路径中。
UpstreamHttpMethod字段定义了允许的上游HTTP方法，在这个示例中，路由只允许GET方法的请求。GlobalConfiguration节点包含了全局配置，适用于所有路由，其中，BaseUrl字段定义了API网关的基础URL，客户端将通过这个URL访问API网关，在这个示例中，API网关运行在https://api.example.com。

假设客户端发送一个GET请求到https://api.example.com/en/v1/products/123，Ocelot将会执行以下操作：首先，根据UpstreamPathTemplate和UpstreamHttpMethod匹配上游请求路径和方法，然后提取路径参数version的值v1，lang的值en，productId的值123。接着根据DownstreamPathTemplate构建下游请求路径/api/v1/products/123，再根据DownstreamScheme、DownstreamHostAndPorts构建下游请求URLhttp://localhost:7000/api/v1/products/123，最后将上游请求转发到下游服务，并返回下游服务的响应给客户端。通过这种方式，Ocelot实现了请求的灵活路由和转发，确保客户端请求能够被正确处理和响应。高级服务路由配置极大地增强了API网关的功能性和灵活性，理解和掌握这些配置方法，是高效使用Ocelot的关键。

二、总结

路由是API网关的核心功能，通过定义规则将客户端请求准确地转发到相应的后端服务，确保请求的正确处理，简化了微服务架构中的服务调用逻辑。Ocelot中的路由配置包括上游路径模板和下游路径模板，并支持路径参数、可选参数、默认值、正则表达式、动态API版本控制和多语言支持等高级功能，提升了系统的灵活性和可维护性。