在 .NET Core 中结合 HttpClientFactory 使用 Polly（上篇）

译者序一：前两天写了一篇文章 .NET Core 开源项目 Polly 介绍，在写这篇文章查看 Polly 资料时，看到了“Polly and HttpClientFactory”这篇 Wiki 文档，觉得很有价值，于是抽时间把它翻译了一下，并和大家分享。由于翻译下来篇幅过长，所以我分成了上、中、下三篇，这是上篇。

译者序二：如果你对 ASP.NET Core 2.1 新引入的 HttpClient 工厂还比较陌生，建议先阅读我的另一篇文章 .NET Core 中正确使用 HttpClient 的姿势，这有助于更好地理解本文。

译者序三：特别声明一下，我翻译技术文章不是逐句翻译的，而是根据我自己的理解来表述的（包括标题）。其中可能会去除一些不影响理解但本人实在不知道如何组织的句子。

—— 正文 ——

ASPNET Core 2.1 的 HttpClient 工厂允许预配置 HttpClient 实例，这样我们可以对 HttpClient 实例预配置 Polly 策略，将它应用到每次向外的网络请求中。

什么是 HttpClient 工厂

从 ASPNET Core 2.1 开始, Polly 集成了 IHttpClientFactory。HttpClient 工厂从以下四个方面简化了 HttpClient 的管理和使用：

• 允许你用命名的方式来配置和使用 HttpClint。例如，您可以预先配置和命名一个访问 GitHub API 的客户端。
• 管理 HttpClientMessageHandler 的生命周期，以避免与你自己来管理 HttpClient 的痛苦（可能会遇到一些严重的问题，具体请看 http://t.cn/EhZ8Bxw 和 http://t.cn/EhZRw53）。
• 可以为工厂创建的 Client 的所有请求和响应提供可配置的日志(通过 ILogger)。
• 提供了一个简单的 API，用于向外请求添加中间件，包括日志、授权、服务发现或 Polly 的弹性策略。

Steve Gordon 在他的博客写了四篇系列文章介绍了 HttpClient 工厂的使用并给出了很好的例子。另外官方也有 HttpClient 工厂的文档。

IHttpClientFactory 和 Polly 结合使用

第一步：添加项目引入

从 NuGet 获取 ASPNET Core 2.1 相关的包，通常需要需要 AspNetCore 元包（不需要手动添加，模板默认添加好了）和 Microsoft.Extensions.Http.Polly 扩展包。

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" Version="2.1.0" />
    <PackageReference Include="Microsoft.Extensions.Http.Polly" Version="2.1.0" />
  </ItemGroup>

</Project>

注意：当您阅读本文时，这些包可能已经有了更高的版本。

第二步： 在 Startup 中 配置 Polly 策略

在你的 Startup.ConfigureServices 方法中配置一个命名的 HttpClient，如下：

public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient("GitHub", client =>
    {
        client.BaseAddress = new Uri("https://api.github.com/");
        client.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
    });

    // ...
}

这里我们写死了配置字符串，实际项目中应该从配置文件中获取。

我们将重点讨论如何使用 Polly 策略来配置它，但是配置命名的 HttpClient 还有很多选项，你可以从官方的文档或 Steve Gordon 和 Scott Hanselman 的博客中了解这些选项。根据你的喜好，也可以使用类型化的 HttpClient。

为了使用 Polly 策略，你只需要在上面的示例中扩展一下：

services.AddHttpClient("GitHub", client =>
{
    client.BaseAddress = new Uri("https://api.github.com/");
    client.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
})
.AddTransientHttpErrorPolicy(builder => builder.WaitAndRetryAsync(new[]
{
    TimeSpan.FromSeconds(1),
    TimeSpan.FromSeconds(5),
    TimeSpan.FromSeconds(10)
}));

这个示例创建了一个策略，该策略将处理典型的瞬态故障，如果需要，会最多重试 3 次 Http 请求。这个策略将在第一次重试前延迟 1 秒，第二次重试前 5 秒，在第三次重试前延迟 10 秒。

AddTransientHttpErrorPolicy 的重载方法有许多选项，我们将在介绍完基础知识之后再来查看这些选项。

第三步：消费配置好的 HttpClient

为了完整上面的示例，下面是一个使用配置好的 HttpClient 示例。对于命名 HttpClient(如上例所示)，在 Controller 中通过依赖注入获取一个 IHttpClientFactory，然后用它获得配置好的 HttpClient：

public class MyController : Controller
{
    private readonly IHttpClientFactory _httpClientFactory;

    public MyController(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    public Task<IActionResult> SomeAction()
    {
        var client = _httpClientFactory.CreateClient("GitHub");
        return Ok(await client.GetStringAsync("/someapi"));
    }
}

再提一下, Steve Gordon 和 Scott Hanselman 的博客有更丰富的例子, 包括类型化的方式使用 HttClient。

Polly 策略是如何被应用的

你配置到 HttpClient 上的 Polly 策略会被应用到一个基于 Polly 的 DelegatingHandler 的向外调用上。这意味着策略将应用于通过配置的 HttpClient 的所有向外调用。

如果您过去尝试手动重试 HttpClient.DoSomethingAsync 的向外调用，您可能会发现 HttpRequestMessage 在发送后不能重用（这样做会引发 InvalidOperationException 异常），DelegatingHandler 的方式则避免了这个问题。

DelegatingHandler 只是用于向外 HTTP 调用的中间件，请参阅 Steve Gordon 博客的文章 (链接：http://t.cn/Ehwz16W) 了解 DelegatingHandler 如何工作。

相关文章：

⒈ .NET Core 开源项目 Polly 介绍
⒉ .NET Core 中正确使用 HttpClient 的姿势