译者：王亮
作者：Polly 团队
原文：http://t.cn/EhZ90oq
译者序一：前两天写了一篇文章 .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 如何工作。
相关文章：