lsm/DotNetCore.SKIT.FlurlHttpClient.Wechat
1
0
Fork 0
mirror of https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat.git synced 2025-04-05 17:37:54 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: 完善文档

Browse Source
This commit is contained in:
Fu Diwei 2021-05-28 19:27:50 +08:00
parent 27cd4178e7
commit 03c30ddd2e
11 changed files with 339 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
README.md
View File

@ -3,12 +3,11 @@
基于 `Flurl.Http` 的微信 API HTTP 客户端，支持公众平台、开放平台、商户平台等模块。
> [`Flurl.Http`](https://flurl.dev/) 是一个轻量级 HTTP 库，是 .NET 中最受欢迎扩展库之一，在 NuGet 上的累计下载量超过 1200 万、日均下载量超过 5 千、GitHub 2.6k Stars（数据统计截至 2021-05-01）。
>
>
> 与另一个流行的 HTTP 库 [`RestSharp`](https://restsharp.dev/) 相比，`Flurl.Http` 底层基于 `System.Net.Http.HttpClient`，而 `RestSharp` 底层则基于 `System.Net.HttpWebRequest`，前者在多核多线程环境下的性能基准测试中表现要远优于后者，同时也是微软官方目前推荐的 HTTP 客户端方案。
>
>
>
> 【附】微软官方关于 `System.Net.HttpWebRequest` 与 `System.Net.Http.HttpClient` 的说明：
>
>
> - https://docs.microsoft.com/zh-cn/dotnet/api/system.net.httpwebrequest#remarks
> - https://docs.microsoft.com/zh-cn/dotnet/api/system.net.http.httpclient#httpclient-and-net-core）。
@ -34,6 +33,8 @@
## 模块
- [《微信公众平台（公众号、小程序） & 开放平台 API 模块》文档](./docs/WechatApi/README.md)
- [《微信商户平台（微信支付） API 模块》文档](./docs/WechatTenpayV3/README.md)
| 名称 | NuGet | 其他 |
| :---------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------: |
| 公众平台（公众号、小程序） & 开放平台模块 | [![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Api.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api) | [文档](./docs/WechatApi/README.md) |
| 商户平台（微信支付）模块 | [![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.TenpayV3.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV3) | [文档](./docs/WechatTenpayV3/README.md) |
| 企业微信模块 | _开发中_ | |

17
docs/WechatApi/Advanced_EventDataDeserialization.md Normal file
View File

@ -0,0 +1,17 @@
### 如何解析回调通知事件？
---
本库封装了直接解析事件的扩展方法，下面给出一个示例：
```csharp
/* 如果是 JSON 格式的通知内容 */
string callbackJson = "...";
var callbackModel = client.DeserializeEventFromJson<Events.WxaMediaCheckEvent>(callbackJson);
/* 如果是 XML 格式的通知内容 */
string callbackXml = "...";
var callbackModel = client.DeserializeEventFromXml<Events.TextMessageEvent>(callbackXml);
```
完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Api/Events_ 目录。

68
docs/WechatApi/Advanced_IHttpClientFactory.md Normal file
View File

@ -0,0 +1,68 @@
### 如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？
---
> 请参阅：
>
> [《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.Api;
using SKIT.FlurlHttpClient.Wechat.Api.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)。

20
docs/WechatApi/Advanced_JSSDK.md Normal file
View File

@ -0,0 +1,20 @@
### 如何生成 JS-SDK 初始化时所需的参数及签名？
---
> 请先自行阅读：
>
> [《微信官方文档 - 微信网页开发：JS-SDK 说明文档》](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html)
你可根据官方文档的规则利用本库提供的 `Sha1Util` 工具类自行进行签名生成。
此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例：
```csharp
var request = new Models.CgibinTicketGetTicketRequest()
{
AccessToken = "微信 AccessToken"
};
var response = await client.ExecuteCgibinTicketGetTicketAsync(request);
var paramMap = client.GenerateParametersForJssdkConfigRequest(response.Ticket, "https://example.com");
```

46
docs/WechatApi/Advanced_JsonSerializer.md Normal file
View File

@ -0,0 +1,46 @@
### 如何指定 JSON 序列化器？
---
> 请先自行阅读：
>
> [《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);
});
```

11
docs/WechatApi/Advanced_ModelDefinition.md Normal file
View File

@ -0,0 +1,11 @@
### 如何快速找到需要调用的 API 模型类名 / 方法名？
---
本库提供的请求模型、响应模型和接口方法，三者均保持同名。
例如，发送模板消息的请求是 `CgibinMessageTemplateSendRequest`，响应是 `CgibinMessageTemplateSendResponse`，接口是 `ExecuteCgibinMessageTemplateSendAsync()`。知道其中一个，其余两个就可以快速地推断出了。
再有，每个对象的命名与官方文档的接口地址大体保持一致。例如刚刚提到的发送模板消息，它的接口地址是 `[POST] /cgi-bin/message/template/send`，将其中的反斜杠去掉、并以大驼峰命名法的方式调整它，就可以得到前文提到的几个对象了。
完整的模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Api/Models_ 目录。

161
docs/WechatApi/README.md
View File

@ -1,3 +1,162 @@
# SKIT.FlurlHttpClient.Wechat.Api
*开发中，未完待续 ...*
[![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Api.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api)
[![NuGet Download](https://img.shields.io/nuget/dt/SKIT.FlurlHttpClient.Wechat.Api.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api)
[![GitHub License](https://img.shields.io/github/license/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE)
基于 `Flurl.Http` 的微信公众平台 & 开放平台 API 客户端。
---
## 功能
- 基于微信公众平台 & 开放平台 API 封装。
- 提供了微信公众平台 & 开放平台 API 所需的 SHA-1 等算法工具类。
- 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。
- 完整微信公众平台 & 开放平台 API 一览：
| | 微信 API | 所属平台 | 备注 |
| :-: | :---------------------------: | :----------------------: | :------------------------------: |
| √ | 基础功能 | 公众号 & 小程序 & 小游戏 | |
| √ | 自定义菜单 | 公众号 | |
| √ | 基础消息能力 | 公众号 | |
| √ | 客服消息 | 公众号 | |
| √ | 微信网页开发 | 公众号 | |
| √ | 素材管理 | 公众号 | |
| √ | 图文消息留言管理 | 公众号 | |
| √ | 用户管理 | 公众号 | |
| √ | 账号管理 | 公众号 | |
| √ | 数据统计 | 公众号 | |
| √ | 微信卡券 | 公众号 | |
| √ | 微信门店 | 公众号 | |
| √ | 微信小店 | 公众号 | |
| √ | 智能接口 | 公众号 | |
| × | <del>微信设备功能</del> | <del>公众号</del> | 与其他协议不一致，需提供单独模块 |
| √ | 微信一物一码 | 公众号 | |
| √ | 微信发票 | 公众号 | |
| √ | 微信非税缴费 | 公众号 | |
| √ | 订阅通知 | 公众号 & 小程序 & 小游戏 | |
| √ | 登录 | 小程序 & 小游戏 | |
| √ | 用户信息 | 小程序 & 小游戏 | |
| √ | 数据分析 | 小程序 & 小游戏 | |
| √ | 动态消息 | 小程序 & 小游戏 | |
| √ | 客服消息 | 小程序 & 小游戏 & 小商店 | |
| √ | 插件管理 | 小程序 | |
| √ | 附近的小程序 | 小程序 | |
| √ | URL Scheme | 小程序 | |
| √ | URL Link | 小程序 | |
| × | <del>广告</del> | <del>小程序</del> | 与其他协议不一致，需提供单独模块 |
| √ | 图像处理 | 小程序 | |
| √ | 即时配送 | 小程序 | |
| √ | 物流助手 | 小程序 | |
| √ | OCR | 小程序 | |
| √ | 运维中心 | 小程序 | |
| √ | 小程序搜索 | 小程序 | |
| √ | 服务市场 | 小程序 | |
| √ | 生物认证 | 小程序 | |
| √ | 虚拟支付 | 小游戏 | |
| √ | 开放数据 | 小游戏 | |
| √ | 对局匹配 | 小游戏 | |
| √ | 帧同步 | 小游戏 | |
| √ | 小程序码 | 小程序 & 小游戏 | |
| √ | 内容安全 | 小程序 & 小游戏 | |
| √ | 云开发 | 小程序 & 小游戏 | |
| √ | 安全风控 | 小程序 & 小游戏 | |
| √ | 直播 | 小程序 & 小商店 | |
| × | <del>开店接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>服务市场接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>SPU 接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>SKU 接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>订单接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>物流接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>配送方式接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>运费模板管理接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>线下配送管理接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>优惠券接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>店铺接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>商家地址管理接口</del> | <del>小商店</del> | _开发中_ |
| × | <del>交易组件</del> | <del>小商店</del> | _开发中_ |
| √ | 微信登录功能 | 开放平台 | |
| √ | 一次性订阅消息 | 开放平台 | |
| √ | 小程序硬件框架 | 开放平台 | |
| √ | 开放平台接口 | 开放平台 | |
| × | <del>代商家注册小程序</del> | 开放平台 | _开发中_ |
| × | <del>试用小程序</del> | 开放平台 | _开发中_ |
| √ | 授权相关 | 开放平台 | _开发中_ |
| √ | 授权方账号管理 | 开放平台 | |
| × | <del>小程序模板管理</del> | 开放平台 | _开发中_ |
| × | <del>小程序基础信息管理</del> | 开放平台 | _开发中_ |
| × | <del>小程序类目管理</del> | 开放平台 | _开发中_ |
| × | <del>小程序成员管理</del> | 开放平台 | _开发中_ |
| × | <del>小程序代码管理</del> | 开放平台 | _开发中_ |
| × | <del>违规和申诉管理</del> | 开放平台 | _开发中_ |
| × | <del>扫码关注组件</del> | 开放平台 | _开发中_ |
| √ | 普通链接二维码与小程序码 | 开放平台 | |
| √ | 其他小程序业务 | 开放平台 | |
| × | <del>公众号业务</del> | 开放平台 | _开发中_ |
| × | <del>云开发</del> | 开放平台 | _开发中_ |
---
## 基础用法
### 安装：
提示：如果你使用 Visual Studio NuGet 管理器图形化界面，请在搜索结果中勾选“**包括预发行版**”。
```shell
# 通过 NuGet 安装
> Install-Package SKIT.FlurlHttpClient.Wechat.Api
# 通过 dotnet-tools 安装
> dotnet add package SKIT.FlurlHttpClient.Wechat.Api
```
### 初始化：
```csharp
using SKIT.FlurlHttpClient.Wechat;
using SKIT.FlurlHttpClient.Wechat.Api;
var options = new WechatApiClientOptions()
{
AppId = "微信 AppId",
AppSecret = "微信 AppSecret",
MidasAppKey = "米大师相关服务 AppKey",
ImmeDeliveryAppKey = "即时配送相关服务 AppKey",
ImmeDeliveryAppSecret = "即时配送相关服务 AppSecret"
};
var client = new WechatApiClient(options);
```
### 请求 & 响应：
```csharp
using SKIT.FlurlHttpClient.Wechat.Api;
using SKIT.FlurlHttpClient.Wechat.Api.Models;
/* 示例：获取用户信息 */
var request = new CgibinUserInfoRequest()
{
AccessToken = "微信 AccessToken",
OpenId = "微信 OpenId"
};
var response = await TestClients.Instance.ExecuteCgibinUserInfoAsync(request);
```
---
## 高级技巧
- [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md)
- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md)
- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)
- [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md)
- [如何生成 JS-SDK 初始化时所需的参数及签名？](./Advanced_JSSDK.md)

6
docs/WechatTenpayV3/Advanced_CallbackDataDecryption.md → docs/WechatTenpayV3/Advanced_EventDataDecryption.md
View File

@ -15,13 +15,13 @@
```csharp
string callbackJson = "..."; // 微信支付平台发来的通知内容
var callbackModel = client.DeserializeCallback(callbackJson); // 得到通知对象
var callbackModel = client.DeserializeEvent(callbackJson); // 得到通知对象
if ("TRANSACTION.SUCCESS".Equals(callbackModel.EventType))
{
var callbackResource = client.DecryptCallbackResource<Resources.TransactionResource>(callbackModel); // 得到支付通知敏感数据
var callbackResource = client.DecryptEventResource<Events.TransactionResource>(callbackModel); // 得到支付通知敏感数据
string outTradeNumber = callbackResource.OutTradeNumber;
string transactionId = callbackResource.TransactionId;
}
```
完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.TenpayV3/Resources_ 目录。
完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.TenpayV3/Events_ 目录。

4
docs/WechatTenpayV3/Advanced_IHttpClientFactory.md
View File

@ -34,7 +34,7 @@ public class WechatTenpayClientFactory
public Flurl.Http.IFlurlClient Get(Flurl.Url url)
{
return new FlurlClient(_httpClientFactory.CreateClient(url));
return new FlurlClient(_httpClientFactory.CreateClient(url.ToUri()));
}
public void Dispose()
@ -53,7 +53,7 @@ public class WechatTenpayClientFactory
_httpClientFactory = httpClientFactory ?? throw new ArgumentNullException(nameof(httpClientFactory));
_wechatTenpayClientOptions = wechatTenpayClientOptions ?? throw new ArgumentNullException(nameof(wechatTenpayClientOptions));
FlurlHttp.Configure(settings => settings.FlurlClientFactory = new DelegatingFlurlClientFactory(_httpClientFactory));
Flurl.Http.FlurlHttp.GlobalSettings.FlurlClientFactory = new DelegatingFlurlClientFactory(_httpClientFactory);
}
public WechatTenpayClient CreateClient()

2
docs/WechatTenpayV3/Advanced_ModelDefinition.md
View File

@ -4,7 +4,7 @@
本库提供的请求模型、响应模型和接口方法，三者均保持同名。
例如，发起退款的请求是 `CreateRefundDomesticRefundRequest`，响应是 `CreateRefundDomesticRefundResponse`，接口是 `CreateRefundDomesticRefundAsync()`。知道其中一个，其余两个就可以快速地推断出了。
例如，发起退款的请求是 `CreateRefundDomesticRefundRequest`，响应是 `CreateRefundDomesticRefundResponse`，接口是 `ExecuteCreateRefundDomesticRefundAsync()`。知道其中一个，其余两个就可以快速地推断出了。
再有，每个对象的命名与官方文档的接口地址大体保持一致。例如刚刚提到的发起退款，它的接口地址是 `[POST] /refund/domestic/refunds`，将其中的反斜杠去掉、并以大驼峰命名法的方式调整它，就可以得到前文提到的几个对象了。

6
docs/WechatTenpayV3/README.md
View File

@ -107,7 +107,7 @@ var request = new CreatePayTransactionJsapiRequest()
},
Payer = new Models.CreatePayTransactionJsapiRequest.Types.Payer()
{
OpenId = TestConfigs.WechatOpenId
OpenId = "微信 OpenId"
}
};
var response = await TestClients.Instance.ExecuteCreatePayTransactionJsapiAsync(request);
@ -121,7 +121,7 @@ var response = await TestClients.Instance.ExecuteCreatePayTransactionJsapiAsync(
- [如何验证微信响应签名？](./Advanced_ResponseSignatureVerification.md)
- [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md)
- [如何快速找到需要调用的 API 模型类名 / 方法名（附完整 API 对照表）？](./Advanced_ModelDefinition.md)
- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md)
@ -129,7 +129,7 @@ var response = await TestClients.Instance.ExecuteCreatePayTransactionJsapiAsync(
- [如何解密响应中的敏感数据？](./Advanced_ResponseDataDecryption.md)
- [如何解密回调通知事件中的敏感数据？](./Advanced_CallbackDataDecryption.md)
- [如何解密回调通知事件中的敏感数据？](./Advanced_EventDataDecryption.md)
- [如何生成客户端调起支付时所需的参数及签名？](./Advanced_Payment.md)