mirror of
https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat.git
synced 2025-07-15 14:04:32 +08:00
docs: 完善文档
This commit is contained in:
Fu Diwei
parent
2de86d55c7
commit
8d2fc066d7
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
`IHttpClientFactory` 在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_IHttpClientFactory.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何在 ASP.NET Core 中与 IHttpClientFactory 集成？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_IHttpClientFactory.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,6 +2,18 @@
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
本库内置了一个用于请求时自动生成服务商身份令牌（即 AgencyToken）的拦截器。
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_Interceptor.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
---
|
||||
|
||||
### 内置拦截器
|
||||
|
||||
本库内置了一个用于请求时自动生成服务商身份令牌（即 AgencyToken）的拦截器。
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_JsonSerializer.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,60 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
> 请参阅：
|
||||
>
|
||||
> [《Microsoft Docs - 使用 IHttpClientFactory 实现复原 HTTP 请求》](https://docs.microsoft.com/zh-cn/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests)
|
||||
>
|
||||
> [《Microsoft Docs - 在 ASP.NET Core 中使用 IHttpClientFactory 发出 HTTP 请求》](https://docs.microsoft.com/zh-cn/aspnet/core/fundamentals/http-requests#httpclient-and-lifetime-management)
|
||||
>
|
||||
> [《Microsoft Docs - .NET Core 2.1 的新增功能：套接字改进》](https://docs.microsoft.com/zh-CN/dotnet/core/whats-new/dotnet-core-2-1#sockets-improvements)
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
当你的项目是运行在 ASP.NET Core 2.1 或更高版本的平台时，CLR 已经提供了全新的底层套接字实现，无需你手动干预 `HttpClient` 的生命周期。
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何在 ASP.NET Core 中与 IHttpClientFactory 集成？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_IHttpClientFactory.md)
|
||||
|
||||
如果你想手动管理 `HttpClient`，那么可以参考下面基于 DI/IoC 的代码实现：
|
||||
---
|
||||
|
||||
```csharp
|
||||
using Microsoft.Extensions.Options;
|
||||
using SKIT.FlurlHttpClient.Wechat.Api;
|
||||
using SKIT.FlurlHttpClient.Wechat.Api.Models;
|
||||
### 镜像站点
|
||||
|
||||
public class WechatApiClientFactory
|
||||
{
|
||||
internal class DelegatingFlurlClientFactory : Flurl.Http.Configuration.DefaultHttpClientFactory
|
||||
{
|
||||
private readonly System.Net.Http.IHttpClientFactory _httpClientFactory;
|
||||
|
||||
public DelegatingFlurlClientFactory(System.Net.Http.IHttpClientFactory httpClientFactory)
|
||||
{
|
||||
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
|
||||
}
|
||||
|
||||
public override System.Net.Http.HttpClient CreateHttpClient(System.Net.Http.HttpMessageHandler handler)
|
||||
{
|
||||
return _httpClientFactory.CreateClient();
|
||||
}
|
||||
}
|
||||
|
||||
private readonly System.Net.Http.IHttpClientFactory _httpClientFactory;
|
||||
private readonly IOptions<WechatApiClientOptions> _wechatApiClientOptions;
|
||||
|
||||
public WechatApiClientFactory(
|
||||
System.Net.Http.IHttpClientFactory httpClientFactory,
|
||||
IOptions<WechatApiClientOptions> wechatApiClientOptions)
|
||||
{
|
||||
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
|
||||
_wechatApiClientOptions = wechatApiClientOptions ?? throw new ArgumentNullException(nameof(wechatApiClientOptions));
|
||||
}
|
||||
|
||||
public WechatApiClient CreateClient()
|
||||
{
|
||||
WechatApiClient client = new WechatApiClient(_wechatApiClientOptions.Value);
|
||||
client.Configure((settings) => settings.FlurlHttpClientFactory = new DelegatingFlurlClientFactory(_httpClientFactory));
|
||||
return client;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
需要强调的是，虽然 `WechatApiClient` 实现了 `System.IDisposable` 接口，但你不应该在 DI/IoC 中手动释放它，而是应该交给 IoC 容器自动管理它。
|
||||
|
||||
此外你应注意，`System.Net.Http.IHttpClientFactory` 与 `Flurl.Http.Configuration.IHttpClientFactory` 是两个不同的类型，[使用时请加以区分](https://flurl.dev/docs/configuration/#httpclientfactory)。
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,40 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
拦截器是一种可以监视或重写请求调用的强大机制。下面给出一个用于记录传出请求和传入响应的拦截器简单示例：
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
```csharp
|
||||
public class LoggingInterceptor : FlurlHttpCallInterceptor
|
||||
{
|
||||
private readonly ILogger _logger;
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_Interceptor.md)
|
||||
|
||||
public LoggingInterceptor(ILogger logger)
|
||||
{
|
||||
_logger = logger;
|
||||
}
|
||||
---
|
||||
|
||||
public override Task BeforeCallAsync(FlurlCall flurlCall)
|
||||
{
|
||||
logger.LogInformation($"Sending request to {flurlCall.Request.Url} on {DateTimeOffset.Now}.");
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
### 镜像站点
|
||||
|
||||
public override Task AfterCallAsync(FlurlCall flurlCall)
|
||||
{
|
||||
logger.LogInformation($"Received response in {flurlCall.Duration.Value.TotalMilliseconds}ms.");
|
||||
return Task.CompletedTask;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
示例代码中的 `FlurlCall` 对象，是 `Flurl.Http` 的内置类型，有关该类型的更进一步的说明，请自行阅读相关文档。
|
||||
|
||||
你可以在构造得到 `WechatApiClient` 对象后，将拦截器注入到该客户端中：
|
||||
|
||||
```csharp
|
||||
client.Interceptors.Add(new LoggingInterceptor(loggerFactory.CreateLogger()));
|
||||
```
|
||||
|
||||
拦截器的工作方式类似于洋葱模型。对于请求拦截器而言，将按照添加时的顺序依次执行；对于响应拦截器而言，将按照添加时的顺序逆序依次执行。
|
||||
|
||||
拦截器在某些场景下非常有用。例如，你可以自行实现一个请求拦截器，自动在请求时注入 `AccessToken`。
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,49 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [《Microsoft Docs - .NET 中的 JSON 序列化和反序列化（封送和拆收）》](https://docs.microsoft.com/zh-cn/dotnet/standard/serialization/system-text-json-overview)
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
默认情况下，本库使用 `System.Text.Json` 作为 JSON 序列化器。
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_JsonSerializer.md)
|
||||
|
||||
如果你更习惯于 `Newtonsoft.Json`，那么你可以在构造得到 `WechatApiClient` 对象后：
|
||||
---
|
||||
|
||||
```csharp
|
||||
client.Configure(settings =>
|
||||
{
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer();
|
||||
});
|
||||
```
|
||||
### 镜像站点
|
||||
|
||||
此外，如果你希望调整一些序列化器的配置项，那么可以：
|
||||
|
||||
```csharp
|
||||
using System.Text.Json;
|
||||
using SKIT.FlurlHttpClient;
|
||||
using SKIT.FlurlHttpClient.Wechat;
|
||||
|
||||
client.Configure(settings =>
|
||||
{
|
||||
var jsonOptions = FlurlSystemTextJsonSerializer.GetDefaultSerializerOptions();
|
||||
jsonOptions.WriteIndented = true;
|
||||
settings.JsonSerializer = new FlurlSystemTextJsonSerializer(jsonOptions);
|
||||
});
|
||||
```
|
||||
|
||||
使用 `Newtonsoft.Json` 时也是同样的：
|
||||
|
||||
```csharp
|
||||
using Newtonsoft.Json;
|
||||
using SKIT.FlurlHttpClient;
|
||||
using SKIT.FlurlHttpClient.Wechat;
|
||||
|
||||
client.Configure(settings =>
|
||||
{
|
||||
var jsonSettings = FlurlNewtonsoftJsonSerializer.GetDefaultSerializerSettings();
|
||||
jsonSettings.Formatting = Formatting.Indented;
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer(jsonSettings);
|
||||
});
|
||||
```
|
||||
|
||||
需要注意的是，虽然你也可在代码中指定成其他实现 `ISerializer` 的 JSON 序列化器，但因本库的接口模型定义与实际发送的 JSON 数据并非完全一致，使用其他实现会导致意外的执行结果，所以请务必只使用本库内置的这两种 JSON 序列化器。
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
`IHttpClientFactory` 在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_IHttpClientFactory.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何在 ASP.NET Core 中与 IHttpClientFactory 集成？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_IHttpClientFactory.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_Interceptor.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_JsonSerializer.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_Interceptor.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_JsonSerializer.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
`IHttpClientFactory` 在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_IHttpClientFactory.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何在 ASP.NET Core 中与 IHttpClientFactory 集成？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_IHttpClientFactory.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,8 +2,18 @@
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_Interceptor.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
---
|
||||
|
||||
### 内置拦截器
|
||||
|
||||
本库内置了一个用于请求时自动生成签名的拦截器。
|
||||
|
||||
你也可以自行实现一个响应拦截器，自动在响应时验证签名。
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_JsonSerializer.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
`IHttpClientFactory` 在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_IHttpClientFactory.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何在 ASP.NET Core 中与 IHttpClientFactory 集成？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_IHttpClientFactory.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何使用拦截器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_Interceptor.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
@ -2,4 +2,12 @@
|
||||
|
||||
---
|
||||
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
本功能来自于公共组件，请参阅公共组件下的相关文档：
|
||||
|
||||
> [《SKIT.FlurlHttpClient FAQ：如何指定 JSON 序列化器？》](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient/blob/main/docs/FAQ_JsonSerializer.md)
|
||||
|
||||
---
|
||||
|
||||
### 镜像站点
|
||||
|
||||
国内用户如访问 GitHub 网络状况不佳，可在打开上述链接后，手动将域名部分的 **github.com** 替换为 **gitee.com**、剩余路径部分保持不变，即可访问。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user