mirror of
https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat.git
synced 2025-04-05 17:37:54 +08:00
docs: 完善文档
This commit is contained in:
Fu Diwei
parent
a19ab7bd46
commit
b317d78fc1
5
docs/WechatAds/Advanced_IHttpClientFactory.md
Normal file
5
docs/WechatAds/Advanced_IHttpClientFactory.md
Normal file
@ -0,0 +1,5 @@
|
||||
### 如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？
|
||||
|
||||
---
|
||||
|
||||
`IHttpClientFactory` 在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_IHttpClientFactory.md)。
|
||||
7
docs/WechatAds/Advanced_Interceptor.md
Normal file
7
docs/WechatAds/Advanced_Interceptor.md
Normal file
@ -0,0 +1,7 @@
|
||||
### 如何使用拦截器？
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
|
||||
本库内置了一个用于请求时自动生成服务商身份令牌（即 AgencyToken）的拦截器。
|
||||
5
docs/WechatAds/Advanced_JsonSerializer.md
Normal file
5
docs/WechatAds/Advanced_JsonSerializer.md
Normal file
@ -0,0 +1,5 @@
|
||||
### 如何指定 JSON 序列化器？
|
||||
|
||||
---
|
||||
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
@ -89,4 +89,10 @@ var response = await client.ExecuteCampaignsAddAsync(request);
|
||||
|
||||
- [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md)
|
||||
|
||||
- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md)
|
||||
|
||||
- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)
|
||||
|
||||
- [如何使用拦截器？](./Advanced_Interceptor.md)
|
||||
|
||||
- [如何获取接口调用凭据（即 AccessToken）？](./Advanced_AccessToken.md)
|
||||
|
||||
39
docs/WechatApi/Advanced_Interceptor.md
Normal file
39
docs/WechatApi/Advanced_Interceptor.md
Normal file
@ -0,0 +1,39 @@
|
||||
### 如何使用拦截器？
|
||||
|
||||
---
|
||||
|
||||
拦截器是一种可以监视或重写请求调用的强大机制。下面给出一个用于记录传出请求和传入响应的拦截器简单示例：
|
||||
|
||||
```csharp
|
||||
public class LoggingInterceptor : WechatHttpCallInterceptor
|
||||
{
|
||||
private readonly ILogger _logger;
|
||||
|
||||
public WechatAdsAgencyTokenInterceptor(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()));
|
||||
```
|
||||
|
||||
拦截器的工作方式类似于洋葱模型。对于请求拦截器而言，将按照添加时的顺序依次执行；对于响应拦截器而言，将按照添加时的顺序逆序依次执行。
|
||||
@ -8,7 +8,7 @@
|
||||
|
||||
默认情况下，本库使用 `System.Text.Json` 作为 JSON 序列化器。
|
||||
|
||||
如果你更习惯于 `Newtonsoft.Json`，那么你可以在构造得到 `WechatTenpayClient` 对象后：
|
||||
如果你更习惯于 `Newtonsoft.Json`，那么你可以在构造得到 `WechatApiClient` 对象后：
|
||||
|
||||
```csharp
|
||||
client.Configure(settings =>
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
[](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api)
|
||||
[](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE)
|
||||
|
||||
基于 `Flurl.Http` 的[微信公众平台]((https://mp.weixin.qq.com/)) & [微信开放平台]((https://open.weixin.qq.com/)) API 客户端。
|
||||
基于 `Flurl.Http` 的[微信公众平台](<(https://mp.weixin.qq.com/)>) & [微信开放平台](<(https://open.weixin.qq.com/)>) API 客户端。
|
||||
|
||||
---
|
||||
|
||||
@ -161,6 +161,8 @@ var response = await client.ExecuteCgibinUserInfoAsync(request);
|
||||
|
||||
- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)
|
||||
|
||||
- [如何使用拦截器？](./Advanced_Interceptor.md)
|
||||
|
||||
- [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md)
|
||||
|
||||
- [如何生成 JS-SDK 初始化时所需的参数及签名？](./Advanced_JSSDK.md)
|
||||
|
||||
@ -2,67 +2,4 @@
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [《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` 的生命周期。
|
||||
|
||||
如果你想手动管理 `HttpClient`，那么可以参考下面基于 DI/IoC 的代码实现：
|
||||
|
||||
```csharp
|
||||
using Flurl.Http;
|
||||
using Flurl.Http.Configuration;
|
||||
using Microsoft.Extensions.Options;
|
||||
using SKIT.FlurlHttpClient.Wechat.TenpayV3;
|
||||
using SKIT.FlurlHttpClient.Wechat.TenpayV3.Models;
|
||||
|
||||
public class WechatTenpayClientFactory
|
||||
{
|
||||
internal class DelegatingFlurlClientFactory : IFlurlClientFactory
|
||||
{
|
||||
private readonly System.Net.Http.IHttpClientFactory _httpClientFactory;
|
||||
|
||||
public DelegatingFlurlClientFactory(System.Net.Http.IHttpClientFactory httpClientFactory)
|
||||
{
|
||||
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
|
||||
}
|
||||
|
||||
public Flurl.Http.IFlurlClient Get(Flurl.Url url)
|
||||
{
|
||||
return new FlurlClient(_httpClientFactory.CreateClient(url.ToUri()));
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
// Do Nothing
|
||||
}
|
||||
}
|
||||
|
||||
private readonly System.Net.Http.IHttpClientFactory _httpClientFactory;
|
||||
private readonly IOptions<WechatTenpayClientOptions> _wechatTenpayClientOptions;
|
||||
|
||||
public WechatTenpayClientFactory(
|
||||
System.Net.Http.IHttpClientFactory httpClientFactory,
|
||||
IOptions<WechatTenpayClientOptions> wechatTenpayClientOptions)
|
||||
{
|
||||
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
|
||||
_wechatTenpayClientOptions = wechatTenpayClientOptions ?? throw new ArgumentNullException(nameof(wechatTenpayClientOptions));
|
||||
|
||||
Flurl.Http.FlurlHttp.GlobalSettings.FlurlClientFactory = new DelegatingFlurlClientFactory(_httpClientFactory);
|
||||
}
|
||||
|
||||
public WechatTenpayClient CreateClient()
|
||||
{
|
||||
return new WechatTenpayClient(_wechatTenpayClientOptions.Value);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
需要强调的是，虽然 `WechatTenpayClient` 实现了 `System.IDisposable` 接口，但你不应该在 DI/IoC 中手动释放它，而是应该交给 IoC 容器自动管理它。
|
||||
|
||||
此外你应注意，`System.Net.Http.IHttpClientFactory` 与 `Flurl.Http.Configuration.IHttpClientFactory` 是两个不同的类型，[使用时请加以区分](https://flurl.dev/docs/configuration/#httpclientfactory)。
|
||||
`IHttpClientFactory` 在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_IHttpClientFactory.md)。
|
||||
|
||||
7
docs/WechatTenpayV3/Advanced_Interceptor.md
Normal file
7
docs/WechatTenpayV3/Advanced_Interceptor.md
Normal file
@ -0,0 +1,7 @@
|
||||
### 如何使用拦截器？
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
|
||||
本库内置了一个用于请求时自动生成签名的拦截器。
|
||||
@ -2,45 +2,4 @@
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [《Microsoft Docs - .NET 中的 JSON 序列化和反序列化（封送和拆收）》](https://docs.microsoft.com/zh-cn/dotnet/standard/serialization/system-text-json-overview)
|
||||
|
||||
默认情况下，本库使用 `System.Text.Json` 作为 JSON 序列化器。
|
||||
|
||||
如果你更习惯于 `Newtonsoft.Json`，那么你可以在构造得到 `WechatTenpayClient` 对象后：
|
||||
|
||||
```csharp
|
||||
client.Configure(settings =>
|
||||
{
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer();
|
||||
});
|
||||
```
|
||||
|
||||
此外，如果你希望调整一些序列化器的配置项，那么可以：
|
||||
|
||||
```csharp
|
||||
using System.Text.Json;
|
||||
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.Wechat;
|
||||
|
||||
client.Configure(settings =>
|
||||
{
|
||||
var jsonSettings = FlurlNewtonsoftJsonSerializer.GetDefaultSerializerSettings();
|
||||
jsonSettings.Formatting = Formatting.Indented;
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer(jsonSettings);
|
||||
});
|
||||
```
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
@ -127,6 +127,8 @@ var response = await client.ExecuteCreatePayTransactionJsapiAsync(request);
|
||||
|
||||
- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)
|
||||
|
||||
- [如何使用拦截器？](./Advanced_Interceptor.md)
|
||||
|
||||
- [如何解密响应中的敏感数据？](./Advanced_ResponseDataDecryption.md)
|
||||
|
||||
- [如何解密回调通知事件中的敏感数据？](./Advanced_EventDataDecryption.md)
|
||||
|
||||
@ -2,67 +2,4 @@
|
||||
|
||||
---
|
||||
|
||||
> 请参阅：
|
||||
>
|
||||
> [《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` 的生命周期。
|
||||
|
||||
如果你想手动管理 `HttpClient`，那么可以参考下面基于 DI/IoC 的代码实现：
|
||||
|
||||
```csharp
|
||||
using Flurl.Http;
|
||||
using Flurl.Http.Configuration;
|
||||
using Microsoft.Extensions.Options;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work.Models;
|
||||
|
||||
public class WechatApiClientFactory
|
||||
{
|
||||
internal class DelegatingFlurlClientFactory : IFlurlClientFactory
|
||||
{
|
||||
private readonly System.Net.Http.IHttpClientFactory _httpClientFactory;
|
||||
|
||||
public DelegatingFlurlClientFactory(System.Net.Http.IHttpClientFactory httpClientFactory)
|
||||
{
|
||||
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
|
||||
}
|
||||
|
||||
public Flurl.Http.IFlurlClient Get(Flurl.Url url)
|
||||
{
|
||||
return new FlurlClient(_httpClientFactory.CreateClient(url.ToUri()));
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
// Do Nothing
|
||||
}
|
||||
}
|
||||
|
||||
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));
|
||||
|
||||
Flurl.Http.FlurlHttp.GlobalSettings.FlurlClientFactory = new DelegatingFlurlClientFactory(_httpClientFactory);
|
||||
}
|
||||
|
||||
public WechatApiClient CreateClient()
|
||||
{
|
||||
return new WechatApiClient(_wechatApiClientOptions.Value);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
需要强调的是，虽然 `WechatApiClient` 实现了 `System.IDisposable` 接口，但你不应该在 DI/IoC 中手动释放它，而是应该交给 IoC 容器自动管理它。
|
||||
|
||||
此外你应注意，`System.Net.Http.IHttpClientFactory` 与 `Flurl.Http.Configuration.IHttpClientFactory` 是两个不同的类型，[使用时请加以区分](https://flurl.dev/docs/configuration/#httpclientfactory)。
|
||||
`IHttpClientFactory` 在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_IHttpClientFactory.md)。
|
||||
|
||||
5
docs/WechatWork/Advanced_Interceptor.md
Normal file
5
docs/WechatWork/Advanced_Interceptor.md
Normal file
@ -0,0 +1,5 @@
|
||||
### 如何使用拦截器？
|
||||
|
||||
---
|
||||
|
||||
拦截器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_Interceptor.md)。
|
||||
@ -2,45 +2,4 @@
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [《Microsoft Docs - .NET 中的 JSON 序列化和反序列化（封送和拆收）》](https://docs.microsoft.com/zh-cn/dotnet/standard/serialization/system-text-json-overview)
|
||||
|
||||
默认情况下，本库使用 `System.Text.Json` 作为 JSON 序列化器。
|
||||
|
||||
如果你更习惯于 `Newtonsoft.Json`，那么你可以在构造得到 `WechatTenpayClient` 对象后：
|
||||
|
||||
```csharp
|
||||
client.Configure(settings =>
|
||||
{
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer();
|
||||
});
|
||||
```
|
||||
|
||||
此外，如果你希望调整一些序列化器的配置项，那么可以：
|
||||
|
||||
```csharp
|
||||
using System.Text.Json;
|
||||
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.Wechat;
|
||||
|
||||
client.Configure(settings =>
|
||||
{
|
||||
var jsonSettings = FlurlNewtonsoftJsonSerializer.GetDefaultSerializerSettings();
|
||||
jsonSettings.Formatting = Formatting.Indented;
|
||||
settings.JsonSerializer = new FlurlNewtonsoftJsonSerializer(jsonSettings);
|
||||
});
|
||||
```
|
||||
JSON 序列化器在本库下的用法与在 [SKIT.FlurlHttpClient.Wechat.Api](../WechatApi/README.md) 模块下的用法类似，请参阅[相关文档](../WechatApi/Advanced_JsonSerializer.md)。
|
||||
|
||||
@ -140,6 +140,8 @@ var response = await client.ExecuteCgibinUserGetAsync(request);
|
||||
|
||||
- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)
|
||||
|
||||
- [如何使用拦截器？](./Advanced_Interceptor.md)
|
||||
|
||||
- [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md)
|
||||
|
||||
- [如何生成 JS-SDK 初始化时所需的参数及签名？](./Advanced_JSSDK.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user