.NET Core开源API网关 – Ocelot中文文档

Ocelot是一个用.NET Core实现并且开源的API网关，它功能强大，包括了：路由、请求聚合、服务发现、认证、鉴权、限流熔断、并内置了负载均衡器与Service Fabric、Butterfly Tracing集成。这些功能只都只需要简单的配置即可完成，下面我们会对这些功能的配置一一进行说明。

介绍

简单的来说Ocelot是一堆的asp.net core middleware组成的一个管道。当它拿到请求之后会用一个request builder来构造一个HttpRequestMessage发到下游的真实服务器，等下游的服务返回response之后再由一个middleware将它返回的HttpResponseMessage映射到HttpResponse上。

API网关—— 它是系统的暴露在外部的一个访问入口。这个有点像代理访问的家伙，就像一个公司的门卫承担着寻址、限制进入、安全检查、位置引导、等等功能。

Ocelot的基本使用

用一台web service来host Ocelot，在这里有一个json配置文件，里面设置了所有对当前这个网关的配置。它会接收所有的客户端请求，并路由到对应的下游服务器进行处理，再将请求结果返回。而这个上下游请求的对应关系也被称之为路由。

集成Identity Server

当我们涉及到认证和鉴权的时候，我们可以跟Identity Server进行结合。当网关需要请求认证信息的时候会与Identity Server服务器进行交互来完成。

网关集群

只有一个网关是很危险的，也就是我们通常所讲的单点，只要它挂了，所有的服务全挂。这显然无法达到高可用，所以我们也可以部署多台网关。当然这个时候在多台网关前，你还需要一台负载均衡器。

Consul 服务发现

在Ocelot已经支持简单的负载功能，也就是当下游服务存在多个结点的时候，Ocelot能够承担起负载均衡的作用。但是它不提供健康检查，服务的注册也只能通过手动在配置文件里面添加完成。这不够灵活并且在一定程度下会有风险。这个时候我们就可以用Consul来做服务发现，它能与Ocelot完美结合。

集成网关

在asp.net core 2.0里通过nuget即可完成集成，或者命令行dotnet add package Ocelot以及通过vs2017 UI添加Ocelot nuget引用都可以。

Install-Package Ocelot

配置

我们需要添加一个.json的文件用来添加Ocelot的配置，以下是最基本的配置信息。

1.  
   {
2.  
      "ReRoutes": [],
3.  
      "GlobalConfiguration": {
4.  
          "BaseUrl": "https://api.mybusiness.com"
5.  
      }
6.  
   }

要特别注意一下BaseUrl是我们外部暴露的Url，比如我们的Ocelot运行在http://123.111.1.1的一个地址上，但是前面有一个 nginx绑定了域名http://api.jessetalk.cn，那这里我们的BaseUrl就是 http://api.jessetalk.cn。

将配置文件加入ASP.NET Core Configuration

我们需要通过WebHostBuilder将我们添加的json文件添加进asp.net core的配置

1.  
   public static IWebHost BuildWebHost(string[] args) =>
2.  
      WebHost.CreateDefaultBuilder(args)
3.  
          .ConfigureAppConfiguration( (hostingContext,builder) => {
4.  
              builder
5.  
              .SetBasePath(hostingContext.HostingEnvironment.ContentRootPath)
6.  
              .AddJsonFile("Ocelot.json");
7.  
          })
8.  
          .UseStartup<Startup>()
9.  
          .Build();

配置依赖注入与中间件

在startup.cs中我们首先需要引用两个命名空间

using Ocelot.DependencyInjection;using Ocelot.Middleware;

接下来就是添加依赖注入和中间件

1.  
   public void ConfigureServices(IServiceCollection services)
2.  
   {
3.  
      services.AddOcelot();
4.  
   }

1.  
   public void Configure(IApplicationBuilder app, IHostingEnvironment env)
2.  
   {    if (env.IsDevelopment())
3.  
      {
4.  
          app.UseDeveloperExceptionPage();
5.  
      }
6.  
    
7.  
      app.UseOcelot().Wait();
8.  
   }

Ocelot功能介绍

通过配置文件可以完成对Ocelot的功能配置：路由、服务聚合、服务发现、认证、鉴权、限流、熔断、缓存、Header头传递等。在配置文件中包含两个根节点：ReRoutes和GlobalConfiguration。ReRoutes是一个数组，其中的每一个元素代表了一个路由，我们可以针对每一个路由进行以上功能配置。下面是一个完整的路由配置

1.  
   {
2.  
            "DownstreamPathTemplate": "/",
3.  
            "UpstreamPathTemplate": "/",
4.  
            "UpstreamHttpMethod": [              "Get"
5.  
            ],
6.  
            "AddHeadersToRequest": {},
7.  
            "AddClaimsToRequest": {},
8.  
            "RouteClaimsRequirement": {},
9.  
            "AddQueriesToRequest": {},
10.  
             "RequestIdKey": "",
11.  
             "FileCacheOptions": {
12.  
                 "TtlSeconds": 0,
13.  
                 "Region": ""
14.  
             },
15.  
             "ReRouteIsCaseSensitive": false,
16.  
             "ServiceName": "",
17.  
             "DownstreamScheme": "http",
18.  
             "DownstreamHostAndPorts": [
19.  
                 {
20.  
                     "Host": "localhost",
21.  
                     "Port": 51876,
22.  
                 }
23.  
             ],
24.  
             "QoSOptions": {
25.  
                 "ExceptionsAllowedBeforeBreaking": 0,
26.  
                 "DurationOfBreak": 0,
27.  
                 "TimeoutValue": 0
28.  
             },
29.  
             "LoadBalancer": "",
30.  
             "RateLimitOptions": {
31.  
                 "ClientWhitelist": [],
32.  
                 "EnableRateLimiting": false,
33.  
                 "Period": "",
34.  
                 "PeriodTimespan": 0,
35.  
                 "Limit": 0
36.  
             },
37.  
             "AuthenticationOptions": {
38.  
                 "AuthenticationProviderKey": "",
39.  
                 "AllowedScopes": []
40.  
             },
41.  
             "HttpHandlerOptions": {
42.  
                 "AllowAutoRedirect": true,
43.  
                 "UseCookieContainer": true,
44.  
                 "UseTracing": true
45.  
             },
46.  
             "UseServiceDiscovery": false
47.  
         }

• Downstream是下游服务配置

• UpStream是上游服务配置

• Aggregates 服务聚合配置

• ServiceName, LoadBalancer, UseServiceDiscovery 配置服务发现

• AuthenticationOptions 配置服务认证

• RouteClaimsRequirement 配置Claims鉴权

• RateLimitOptions为限流配置

• FileCacheOptions 缓存配置

• QosOptions 服务质量与熔断

• DownstreamHeaderTransform头信息转发

我们接下来将对这些功能一一进行介绍和配置

路由

路由是API网关最基本也是最核心的功能、ReRoutes下就是由多个路由节点组成。

1.  
   {
2.  
      "ReRoutes": [
3.  
      ]
4.  
   }

而每一个路由由以下几个基本信息组成：

下面这个配置信息就是将用户的请求 /post/1 转发到 localhost/api/post/1

1.  
   {
2.  
      "DownstreamPathTemplate": "/api/post/{postId}",
3.  
      "DownstreamScheme": "https",
4.  
      "DownstreamHostAndPorts": [
5.  
              {
6.  
                  "Host": "localhost",
7.  
                  "Port": 80,
8.  
              }
9.  
          ],
10.  
       "UpstreamPathTemplate": "/post/{postId}",
11.  
       "UpstreamHttpMethod": [ "Get"]
12.  
    }

• DownstreamPathTemplate：下游戏

• DownstreamScheme：下游服务http schema

• DownstreamHostAndPorts：下游服务的地址，如果使用LoadBalancer的话这里可以填多项

• UpstreamPathTemplate: 上游也就是用户输入的请求Url模板

• UpstreamHttpMethod: 上游请求http方法，可使用数组

万能模板

万能模板即所有请求全部转发，UpstreamPathTemplate 与DownstreamPathTemplate 设置为 “/{url}”

1.  
   {
2.  
      "DownstreamPathTemplate": "/{url}",
3.  
      "DownstreamScheme": "https",
4.  
      "DownstreamHostAndPorts": [
5.  
              {
6.  
                  "Host": "localhost",
7.  
                  "Port": 80,
8.  
              }
9.  
          ],
10.  
       "UpstreamPathTemplate": "/{url}",
11.  
       "UpstreamHttpMethod": [ "Get" ]
12.  
    }

万能模板的优先级最低，只要有其它的路由模板，其它的路由模板则会优先生效。

上游Host
上游Host也是路由用来判断的条件之一，由客户端访问时的Host来进行区别。比如当a.jesetalk.cn/users/{userid}和b.jessetalk.cn/users/{userid}两个请求的时候可以进行区别对待。

1.  
   {
2.  
      "DownstreamPathTemplate": "/",
3.  
      "DownstreamScheme": "https",
4.  
      "DownstreamHostAndPorts": [
5.  
              {
6.  
                  "Host": "10.0.10.1",
7.  
                  "Port": 80,
8.  
              }
9.  
          ],
10.  
       "UpstreamPathTemplate": "/",
11.  
       "UpstreamHttpMethod": [ "Get" ],
12.  
       "UpstreamHost": "a.jessetalk.cn"
13.  
    }

Prioirty优先级
对多个产生冲突的路由设置优化级

1.  
   {
2.  
      "UpstreamPathTemplate": "/goods/{catchAll}"    "Priority": 0
3.  
   }

1.  
   {
2.  
      "UpstreamPathTemplate": "/goods/delete"    "Priority": 1
3.  
   }

比如你有同样两个路由，当请求/goods/delete的时候，则下面那个会生效。也就是说Prority是大的会被优先选择。

路由负载均衡

当下游服务有多个结点的时候，我们可以在DownstreamHostAndPorts中进行配置。

1.  
   {
2.  
      "DownstreamPathTemplate": "/api/posts/{postId}",
3.  
      "DownstreamScheme": "https",
4.  
      "DownstreamHostAndPorts": [
5.  
              {
6.  
                  "Host": "10.0.1.10",
7.  
                  "Port": 5000,
8.  
              },
9.  
              {
10.  
                   "Host": "10.0.1.11",
11.  
                   "Port": 5000,
12.  
               }
13.  
           ],
14.  
       "UpstreamPathTemplate": "/posts/{postId}",
15.  
       "LoadBalancer": "LeastConnection",
16.  
       "UpstreamHttpMethod": [ "Put", "Delete" ]
17.  
    }

LoadBalancer将决定负载均衡的算法

• LeastConnection – 将请求发往最空闲的那个服务器

• RoundRobin – 轮流发送

• NoLoadBalance – 总是发往第一个请求或者是服务发现

在负载均衡这里，我们还可以和Consul结合来使用服务发现，我们将在后面的小节中进行详述。

请求聚合

即将多个API请求结果合并为一个返回。要实现请求聚合我们需要给其它参与的路由起一个Key。

1.  
   {
2.  
      "ReRoutes": [
3.  
          {
4.  
              "DownstreamPathTemplate": "/",
5.  
              "UpstreamPathTemplate": "/laura",
6.  
              "UpstreamHttpMethod": [                "Get"
7.  
              ],
8.  
              "DownstreamScheme": "http",
9.  
              "DownstreamHostAndPorts": [
10.  
                   {
11.  
                       "Host": "localhost",
12.  
                       "Port": 51881
13.  
                   }
14.  
               ],
15.  
               "Key": "Laura"
16.  
           },
17.  
           {
18.  
               "DownstreamPathTemplate": "/",
19.  
               "UpstreamPathTemplate": "/tom",
20.  
               "UpstreamHttpMethod": [                "Get"
21.  
               ],
22.  
               "DownstreamScheme": "http",
23.  
               "DownstreamHostAndPorts": [
24.  
                   {
25.  
                       "Host": "localhost",
26.  
                       "Port": 51882
27.  
                   }
28.  
               ],
29.  
               "Key": "Tom"
30.  
           }
31.  
       ],
32.  
       "Aggregates": [
33.  
           {
34.  
               "ReRouteKeys": [                "Tom",                "Laura"
35.  
               ],
36.  
               "UpstreamPathTemplate": "/"
37.  
           }
38.  
       ]
39.  
    }

当我们请求/的时候，会将/tom和/laura两个结果合并到一个response返回

{"Tom":{"Age": 19},"Laura":{"Age": 25}}

需要注意的是：

• 聚合服务目前只支持返回json

• 目前只支持Get方式请求下游服务

• 任何下游的response header并会被丢弃

• 如果下游服务返回404，聚合服务只是这个key的value为空，它不会返回404

有一些其它的功能会在将来实现

• 下游服务很慢的处理

• 做一些像 GraphQL的处理对下游服务返回结果进行处理

• 404的处理

限流

对请求进行限流可以防止下游服务器因为访问过载而崩溃，这个功能就是我们的张善友张队进添加进去的。非常优雅的实现，我们只需要在路由下加一些简单的配置即可以完成。

1.  
   "RateLimitOptions": {    "ClientWhitelist": [],    "EnableRateLimiting": true,    "Period": "1s",    "PeriodTimespan": 1,    "Limit": 1
2.  
   }

• ClientWihteList 白名单

• EnableRateLimiting 是否启用限流

• Period 统计时间段：1s, 5m, 1h, 1d

• PeroidTimeSpan 多少秒之后客户端可以重试

• Limit 在统计时间段内允许的最大请求数量

在 GlobalConfiguration下我们还可以进行以下配置

1.  
   "RateLimitOptions": {  "DisableRateLimitHeaders": false,  "QuotaExceededMessage": "Customize Tips!",  "HttpStatusCode": 999,  "ClientIdHeader" : "Test"
2.  
   }

• Http头  X-Rate-Limit 和 Retry-After 是否禁用

• QuotaExceedMessage 当请求过载被截断时返回的消息

• HttpStatusCode 当请求过载被截断时返回的http status

• ClientIdHeader 用来识别客户端的请求头，默认是 ClientId

服务质量与熔断

熔断的意思是停止将请求转发到下游服务。当下游服务已经出现故障的时候再请求也是功而返，并且增加下游服务器和API网关的负担。这个功能是用的Pollly来实现的，我们只需要为路由做一些简单配置即可

1.  
   "QoSOptions": {    "ExceptionsAllowedBeforeBreaking":3,    "DurationOfBreak":5,    "TimeoutValue":5000
2.  
   }

• ExceptionsAllowedBeforeBreaking 允许多少个异常请求

• DurationOfBreak 熔断的时间，单位为秒

• TimeoutValue 如果下游请求的处理时间超过多少则自如将请求设置为超时

缓存

Ocelot可以对下游请求结果进行缓存 ，目前缓存的功能还不是很强大。它主要是依赖于CacheManager 来实现的，我们只需要在路由下添加以下配置即可

"FileCacheOptions": { "TtlSeconds": 15, "Region": "somename" }

Region是对缓存进行的一个分区，我们可以调用Ocelot的 administration API来移除某个区下面的缓存 。

认证

如果我们需要对下游API进行认证以及鉴权服务的，则首先Ocelot 网关这里需要添加认证服务。这和我们给一个单独的API或者ASP.NET Core Mvc添加认证服务没有什么区别。

1.  
   public void ConfigureServices(IServiceCollection services)
2.  
   {    var authenticationProviderKey = "TestKey";
3.  
    
4.  
      services.AddAuthentication()
5.  
          .AddJwtBearer(authenticationProviderKey, x =>
6.  
          {
7.  
          });
8.  
   }

然后在ReRoutes的路由模板中的AuthenticationOptions进行配置，只需要我们的AuthenticationProviderKey一致即可。

1.  
   "ReRoutes": [{        "DownstreamHostAndPorts": [
2.  
              {                "Host": "localhost",                "Port": 51876,
3.  
              }
4.  
          ],        "DownstreamPathTemplate": "/",        "UpstreamPathTemplate": "/",        "UpstreamHttpMethod": ["Post"],        "ReRouteIsCaseSensitive": false,        "DownstreamScheme": "http",        "AuthenticationOptions": {            "AuthenticationProviderKey": "TestKey",            "AllowedScopes": []
5.  
          }
6.  
      }]

JWT Tokens

要让网关支持JWT 的认证其实和让API支持JWT  Token的认证是一样的

1.  
   public void ConfigureServices(IServiceCollection services)
2.  
   {    var authenticationProviderKey = "TestKey";
3.  
    
4.  
      services.AddAuthentication()
5.  
          .AddJwtBearer(authenticationProviderKey, x =>
6.  
          {
7.  
              x.Authority = "test";
8.  
              x.Audience = "test";
9.  
          });
10.  
     
11.  
       services.AddOcelot();
12.  
    }

Identity Server Bearer Tokens

添加Identity Server的认证也是一样

1.  
   public void ConfigureServices(IServiceCollection services)
2.  
   {    var authenticationProviderKey = "TestKey";    var options = o =>
3.  
          {
4.  
              o.Authority = "https://whereyouridentityserverlives.com";
5.  
              o.ApiName = "api";
6.  
              o.SupportedTokens = SupportedTokens.Both;
7.  
              o.ApiSecret = "secret";
8.  
          };
9.  
    
10.  
       services.AddAuthentication()
11.  
           .AddIdentityServerAuthentication(authenticationProviderKey, options);
12.  
     
13.  
       services.AddOcelot();
14.  
    }

Allowed Scopes

这里的Scopes将从当前 token 中的 claims中来获取，我们的鉴权服务将依靠于它来实现 。当前路由的下游API需要某个权限时，我们需要在这里声明 。和oAuth2中的 scope意义一致。

鉴权

我们通过认证中的AllowedScopes 拿到claims之后，如果要进行权限的鉴别需要添加以下配置

1.  
   "RouteClaimsRequirement": {    "UserType": "registered"
2.  
   }

当前请求上下文的token中所带的claims如果没有 name=”UserType” 并且 value=”registered” 的话将无法访问下游服务。

请求头转化

请求头转发分两种：转化之后传给下游和从下游接收转化之后传给客户端。在Ocelot的配置里面叫做Pre  Downstream Request和Post Downstream Request。目前的转化只支持查找和替换。我们用到的配置主要是 UpstreamHeaderTransform 和 DownstreamHeaderTransform

Pre Downstream Request

"Test": "http://www.bbc.co.uk/, http://ocelot.com/"

比如我们将客户端传过来的Header中的 Test 值改为 http://ocelot.com/之后再传给下游

1.  
   "UpstreamHeaderTransform": {    "Test": "http://www.bbc.co.uk/, http://ocelot.com/"
2.  
   },

Post Downstream Request

而我们同样可以将下游Header中的Test再转为 http://www.bbc.co.uk/之后再转给客户端。

1.  
   "DownstreamHeaderTransform": {    "Test": "http://www.bbc.co.uk/, http://ocelot.com/"
2.  
   },

变量

在请求头转化这里Ocelot为我们提供了两个变量：BaseUrl和DownstreamBaseUrl。BaseUrl就是我们在GlobalConfiguration里面配置的BaseUrl，后者是下游服务的Url。这里用301跳转做一个示例如何使用这两个变量。

默认的301跳转，我们会返回一个Location的头，于是我们希望将http://www.bbc.co.uk 替换为 http://ocelot.com，后者者网关对外的域名。

1.  
   "DownstreamHeaderTransform": {    "Location": "http://www.bbc.co.uk/, http://ocelot.com/"
2.  
   }, "HttpHandlerOptions": {    "AllowAutoRedirect": false,
3.  
   },

我们通过DownstreamHeaderTranfrom将下游返回的请求头中的Location替换为了网关的域名，而不是下游服务的域名。所以在这里我们也可以使用BaseUrl来做为变量替换。

1.  
   "DownstreamHeaderTransform": {    "Location": "http://localhost:6773, {BaseUrl}"
2.  
   }, "HttpHandlerOptions": {    "AllowAutoRedirect": false,
3.  
   },

当我们的下游服务有多个的时候，我们就没有办法找到前面的那个http://localhost:6773，因为它可能是多个值。所以这里我们可以使用DownstreamBaseUrl。

1.  
   "DownstreamHeaderTransform": {    "Location": "{DownstreamBaseUrl}, {BaseUrl}"
2.  
   }, "HttpHandlerOptions": {    "AllowAutoRedirect": false,
3.  
   },

Claims转化

Claims转化功能可以将Claims中的值转化到请求头、Query String、或者下游的Claims中，对于Claims的转化，比较特殊的一点是它提供了一种对字符串进行解析的方法。举个例子，比如我们有一个sub的claim。这个claims的 name=”sub” value=”usertypevalue|useridvalue”，实际上我们不会弄这么复杂的value，它是拼接来的，但是我们为了演示这个字符串解析的功能，所以使用了这么一个复杂的value。

Ocelot为我们提供的功能分为三段，第一段是Claims[sub]，很好理解[] 里面是我们的claim的名称。第二段是  > 表示对字符串进行拆分, 后面跟着拆分完之后我们要取的那个数组里面的某一个元素用 value[index]来表示，取第0位元素也可以直接用value。第三段也是以 > 开头后面跟着我们的分隔符，在我们上面的例子分隔符是 |

所以在这里如果我们要取  usertype这个claim就会这样写： Claims[sub] > value[0] > |

Claim取到之后我们如果要放到请求头、QueryString、以及Claim当中对应有以下三个配置。

Claims to Claims 

1.  
   "AddClaimsToRequest": {    "UserType": "Claims[sub] > value[0] > |",    "UserId": "Claims[sub] > value[1] > |"
2.  
   }

Claims to Headers 

1.  
   "AddHeadersToRequest": {    "CustomerId": "Claims[sub] > value[1] > |"
2.  
   }

这里我们还是用的上面那个 sub = usertypevalue|useridvalue 的claim来进行处理和转化。

Claims to Query String

1.  
   "AddQueriesToRequest": {    "LocationId": "Claims[LocationId] > value",
2.  
   }

这里没有进行分隔，所以直接取了value。

Consul服务发现

由于Consul服务发现更多的是Consul的安装、配置、以及使用，所以本小节内容将由另一篇文章来进行详细介绍，欢迎关注。

相关文章：

• Ocelot——初识基于.Net Core的API网关

• Ocelot API网关的实现剖析

• 微服务网关Ocelot

• API网关Ocelot 使用Polly 处理部分失败问题

• 谈谈微服务中的 API 网关（API Gateway）

• Ocelot网关

• Ocelot统一权限验证

• 应用监控怎么做？

• ASP.NET Core之跨平台的实时性能监控

• .Net Core 2.0+ InfluxDB+Grafana+App Metrics 实现跨平台的实时性能监控

• 应用程序的8个关键性能指标以及测量方法

• 使用Metrics监控应用程序的性能

• 下一个计划 : .NET/.NET Core应用性能管理

• Ocelot监控

• Ocelot 集成Butterfly 实现分布式跟踪

• Ocelot中使用Butterfly实践

• Ocelot + Consul实践

原文地址：http://www.jessetalk.cn/2018/03/19/net-core-apigateway-ocelot-docs/