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
2e294b0ce7
commit
8609f89c6d
34
README.md
34
README.md
@ -2,7 +2,7 @@
|
||||
|
||||
基于 `Flurl.Http` 的微信 API HTTP 客户端，支持公众平台、开放平台、商户平台、企业微信等模块。
|
||||
|
||||
> [`Flurl.Http`](https://flurl.dev/) 是一个轻量级 HTTP 库，是 .NET 中最受欢迎扩展库之一，在 NuGet 上的累计下载量超过 1200 万、日均下载量超过 5 千、GitHub 2.6k Stars（数据统计截至 2021-05-01）。
|
||||
> [`Flurl.Http`](https://flurl.dev/) 是一个轻量级 HTTP 库，是 .NET 中最受欢迎扩展库之一，在 NuGet 上的累计下载量超过 1700 万、日均下载量超过 6 千、GitHub 2.6k Stars（数据统计截至 2021-06-01）。
|
||||
>
|
||||
> 与另一个流行的 HTTP 库 [`RestSharp`](https://restsharp.dev/) 相比，`Flurl.Http` 底层基于 `System.Net.Http.HttpClient`，而 `RestSharp` 底层则基于 `System.Net.HttpWebRequest`，前者在多核多线程环境下的性能基准测试中表现要远优于后者，同时也是微软官方目前推荐的 HTTP 客户端方案。
|
||||
>
|
||||
@ -27,7 +27,7 @@
|
||||
|
||||
- 强类型接口模型。
|
||||
|
||||
- 完善的微信 API 封装。
|
||||
- 完整、完善、完全的微信 API 封装。
|
||||
|
||||
---
|
||||
|
||||
@ -37,4 +37,32 @@
|
||||
| :---------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------: |
|
||||
| 公众平台（公众号、小程序） & 开放平台模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api) | [文档](./docs/WechatApi/README.md) |
|
||||
| 商户平台（微信支付）模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV3) | [文档](./docs/WechatTenpayV3/README.md) |
|
||||
| 企业微信模块 | _开发中_ | |
|
||||
| 企业微信模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work) | [文档](./docs/WechatWork/README.md) |
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. 为什么要“造轮子”？
|
||||
|
||||
这都 2021 年了，官方本身提供的示例代码还只能运行在 .NET Framework on Windows 上；就连 RSA 签名这么基础的东西都没有人封装（确切的说是因为 RSA 有很多种分块模式和填充模式，网上能找到的往往只封装了其中一种，但却未必符合微信支付的要求）。
|
||||
|
||||
于是萌生了自己封装一个库的想法，打算解决这几个痛点，同时也是推广一下微软官方的 `System.Text.Json`。
|
||||
|
||||
### 2. 本库与[盛派微信 SDK（Senparc.Weixin）](https://github.com/JeffreySu/WeiXinMPSDK)有什么区别？
|
||||
|
||||
- 本库专注于 API 本身的封装；盛派微信 SDK 提供了大而全的功能，可与 MVC 深度集成。
|
||||
|
||||
- 本库的接口模型遵循的是微软官方推荐的 C# 属性命名方式（大驼峰命名法）；盛派微信 SDK 提供的是微信支付接口本身的命名方式（蛇形命名法和小驼峰命名法混杂）。
|
||||
|
||||
- 本库封装了**目前微信官方提供的所有 API**（不支持的已在各模块文档中列出具体原因）；盛派微信 SDK 只提供了常用的 API，只完整支持直连商户模式、部分支持服务商模式。
|
||||
|
||||
- 本库只支持微信支付 v3 版 API；盛派微信 SDK 只支持微信支付 v2 版 API（年前作者开了新坑似乎是想提供 v3 版支持，不过目前只封装了部分接口，进展比较缓慢）。原则上官方已经停止更新 v2 版 API，现在接口只做日常维护，所以有条件的话还是应该尽快升级。
|
||||
|
||||
### 3. 看了源码，发现模型定义里很多同样的代码是复制粘贴的，为什么不继承？
|
||||
|
||||
关于这点得吐槽微信提供的 API 了，很显然微信内部也是很多个 Team 在共同开发，每个 Team、甚至每个人的字段命名风格、约束条件、接口规则都大相径庭。就连微信支付虽然 v3 版 API 号称是 “RESTful” 的，却也没个统一标准。
|
||||
|
||||
举个例子，以分页查询为例，看似字段相同，都由 _offset_、_limit_、_next_cursor_ + _total_count_、_data_ 这几个字段构成，但某些接口的 _offset_、_limit_ 字段是可选参数，某些却是必填项；某些值从 `0` 起始，某些却是从 `1` 起始；某些接口的 _total_count_、_data_ 字段一定会返回，某些却是一定不返回，某些只在特定条件下返回。一共七八个分页查询的接口，却有四五种分页的数据结构，这种情况下很难抽象出一个公共的基类出来。
|
||||
|
||||
同样一个东西在不同接口里竟然拼法不一样；同样是表示数组有的是 JSON、有的却是字符串；诸如此类“奇葩”的情况很多很多。本库已经尽可能在条件允许的范围内抽象出了一些公共基类、并封装了各种奇怪场景下的 JsonConverter，聊胜于无。
|
||||
|
||||
@ -2,16 +2,20 @@
|
||||
|
||||
---
|
||||
|
||||
本库封装了直接解析事件的扩展方法，下面给出一个示例：
|
||||
你可根据官方文档的规则利用本库提供的 `WxBizMsgCryptor` 工具类自行解密回调通知事件的敏感信息。
|
||||
|
||||
对于解密后得到的原始数据，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例：
|
||||
|
||||
```csharp
|
||||
/* 如果是 JSON 格式的通知内容 */
|
||||
string callbackJson = "...";
|
||||
string callbackJson = "{ ... }";
|
||||
var callbackModel = client.DeserializeEventFromJson<Events.WxaMediaCheckEvent>(callbackJson);
|
||||
|
||||
/* 如果是 XML 格式的通知内容 */
|
||||
string callbackXml = "...";
|
||||
string callbackXml = "<xml> ... </xml>";
|
||||
var callbackModel = client.DeserializeEventFromXml<Events.TextMessageEvent>(callbackXml);
|
||||
```
|
||||
|
||||
完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Api/Events_ 目录。
|
||||
|
||||
需要注意的是，如果在微信公众平台后台配置中选择了明文模式，则无需对数据进行解密。
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
>
|
||||
> [《微信官方文档 - 微信网页开发：JS-SDK 说明文档》](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html)
|
||||
|
||||
你可根据官方文档的规则利用本库提供的 `Sha1Util` 工具类自行进行签名生成。
|
||||
你可根据官方文档的规则利用本库提供的 `SHA1Utility` 工具类自行进行签名生成。
|
||||
|
||||
此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例：
|
||||
|
||||
|
||||
@ -12,7 +12,7 @@
|
||||
|
||||
- 基于微信公众平台 & 开放平台 API 封装。
|
||||
|
||||
- 提供了微信公众平台 & 开放平台 API 所需的 SHA-1、HMAC-SHA-256 等算法工具类。
|
||||
- 提供了微信公众平台 & 开放平台 API 所需的 SHA-1、HMAC-SHA-256、AES 等算法工具类。
|
||||
|
||||
- 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。
|
||||
|
||||
@ -144,7 +144,7 @@ var request = new CgibinUserInfoRequest()
|
||||
AccessToken = "微信 AccessToken",
|
||||
OpenId = "微信 OpenId"
|
||||
};
|
||||
var response = await TestClients.Instance.ExecuteCgibinUserInfoAsync(request);
|
||||
var response = await client.ExecuteCgibinUserInfoAsync(request);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -8,12 +8,12 @@
|
||||
|
||||
对于回调通知事件的敏感信息，微信支付平台使用了商户公钥基于 RSA 算法加密。
|
||||
|
||||
开发者利用本库提供的 `RsaUtil` 工具类自行解密相关字段。
|
||||
开发者利用本库提供的 `RSAUtility` 工具类自行解密相关字段。
|
||||
|
||||
此外，本库还封装了直接解密事件的扩展方法，下面给出一个示例：
|
||||
|
||||
```csharp
|
||||
string callbackJson = "..."; // 微信支付平台发来的通知内容
|
||||
string callbackJson = "{ ... }"; // 微信支付平台发来的通知内容
|
||||
|
||||
var callbackModel = client.DeserializeEvent(callbackJson); // 得到通知对象
|
||||
if ("TRANSACTION.SUCCESS".Equals(callbackModel.EventType))
|
||||
|
||||
@ -10,7 +10,7 @@
|
||||
>
|
||||
> [《微信支付开发者文档 - 基础支付：小程序调起支付 API》](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_5_4.shtml)
|
||||
|
||||
你可根据官方文档的规则利用本库提供的 `RsaUtil` 工具类自行进行签名生成。
|
||||
你可根据官方文档的规则利用本库提供的 `RSAUtility` 工具类自行进行签名生成。
|
||||
|
||||
此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例：
|
||||
|
||||
|
||||
@ -12,9 +12,9 @@
|
||||
|
||||
- 使用商户公钥基于 RSA 算法加密。
|
||||
|
||||
- 使用商户 API v3 密钥基于 AES-GCM 算法加密。
|
||||
- 使用商户 API v3 密钥基于 AEAD-AES-GCM 算法加密。
|
||||
|
||||
开发者利用本库提供的 `RsaUtil`、`AesUtil` 工具类自行解密相关字段。
|
||||
开发者利用本库提供的 `RSAUtility`、`AESUtility` 工具类自行解密相关字段。
|
||||
|
||||
此外，本库还封装了直接解密响应的扩展方法，下面给出一个示例：
|
||||
|
||||
|
||||
@ -10,7 +10,7 @@
|
||||
|
||||
本库已经封装了 `QueryCertificatesAsync()` 方法，供开发者获取微信支付平台证书。
|
||||
|
||||
每个响应对象均包含 `WechatpayTimestamp`、`WechatpayNonce`、`WechatpaySignature`、`WechatpaySerial` 等几个公共字段，你可根据官方文档的规则利用本库提供的 `RsaUtil` 工具类自行进行签名验证。
|
||||
每个响应对象均包含 `WechatpayTimestamp`、`WechatpayNonce`、`WechatpaySignature`、`WechatpaySerial` 等几个公共字段，你可根据官方文档的规则利用本库提供的 `RSAUtility` 工具类自行进行签名验证。
|
||||
|
||||
同时，本库也内置了验证签名的的方法，具体用法可以参考项目目录下的 _test/SKIT.FlurlHttpClient.Wechat.TenpayV3.UnitTests/WechatTenpayResponseVerificationTests.cs_ 文件给出的测试用例。
|
||||
|
||||
@ -22,4 +22,4 @@
|
||||
|
||||
- 以 `-----BEGIN CERTIFICATE-----` 开头、 `-----END CERTIFICATE-----` 结尾的是 **CER 证书**文件。
|
||||
|
||||
`QueryCertificatesAsync()` 方法返回的结果是 CER 证书，验证签名时需要先通过 `RsaUtil` 工具类导出 PKCS#8 公钥，再进行签名验证；当然，`RsaUtil` 也封装了直接通过 CER 证书验证签名的方法。
|
||||
`QueryCertificatesAsync()` 方法返回的结果是 CER 证书，验证签名时需要先通过 `RSAUtility` 工具类导出 PKCS#8 公钥，再进行签名验证；当然，`RSAUtility` 也封装了直接通过 CER 证书验证签名的方法。
|
||||
|
||||
@ -16,7 +16,7 @@
|
||||
|
||||
- 请求时自动生成签名，无需开发者手动干预。
|
||||
|
||||
- 提供了微信支付所需的 RSA、AES-GCM、SHA-256 等算法工具类。
|
||||
- 提供了微信支付所需的 RSA、AES、SHA-256 等算法工具类。
|
||||
|
||||
- 提供了调起支付签名、解析响应敏感数据、解析回调通知事件敏感数据等扩展方法。
|
||||
|
||||
@ -110,7 +110,7 @@ var request = new CreatePayTransactionJsapiRequest()
|
||||
OpenId = "微信 OpenId"
|
||||
}
|
||||
};
|
||||
var response = await TestClients.Instance.ExecuteCreatePayTransactionJsapiAsync(request);
|
||||
var response = await client.ExecuteCreatePayTransactionJsapiAsync(request);
|
||||
```
|
||||
|
||||
---
|
||||
@ -132,39 +132,3 @@ var response = await TestClients.Instance.ExecuteCreatePayTransactionJsapiAsync(
|
||||
- [如何解密回调通知事件中的敏感数据？](./Advanced_EventDataDecryption.md)
|
||||
|
||||
- [如何生成客户端调起支付时所需的参数及签名？](./Advanced_Payment.md)
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 1. 为什么要“造轮子”？
|
||||
|
||||
目前网络上还没有基于微信支付 v3 版 API 封装的 .NET 客户端，遑论开源了；这都 2021 年了，官方本身提供的示例代码还只能运行在 .NET Framework on Windows 上；就连 RSA 签名这么基础的东西都没有人封装（确切的说是因为 RSA 有很多种分块模式和填充模式，网上能找到的往往只封装了其中一种，但却未必符合微信支付的要求）。
|
||||
|
||||
于是萌生了自己封装一个库的想法，打算解决这几个痛点，同时也是推广一下微软官方的 `System.Text.Json`。
|
||||
|
||||
### 2. 本库与[盛派微信 SDK（Senparc.Weixin）](https://github.com/JeffreySu/WeiXinMPSDK)有什么区别？
|
||||
|
||||
- 本库只支持微信支付 v3 版 API；盛派微信 SDK 只支持微信支付 v2 版 API（年前作者开了新坑似乎是想提供 v3 版支持，不过目前只封装了部分接口，进展比较缓慢）。原则上官方已经停止更新 v2 版 API，现在接口只做日常维护，所以有条件的话还是应该尽快升级。
|
||||
|
||||
- 本库封装了目前微信支付官方提供的所有 API，包括直连商户和服务商两种模式；盛派微信 SDK 只提供了常用的 API，只完整支持直连商户模式、部分支持服务商模式。
|
||||
|
||||
- 本库的接口模型遵循的是微软官方推荐的 C# 属性命名方式（大驼峰命名法）；盛派微信 SDK 提供的是微信支付接口本身的命名方式（蛇形命名法和小驼峰命名法混杂）。
|
||||
|
||||
- 本库专注于 API 本身的封装；盛派微信 SDK 提供了大而全的功能，与 ASP.NET / ASP.NET Core 深度集成。
|
||||
|
||||
### 3. 为什么不支持企业付款、现金红包等功能？
|
||||
|
||||
请注意前文所描述的微信支付 API 一览表，有部分功能并非封装遗漏，而是官方尚未提供支持。
|
||||
|
||||
如果你确实需要这部分功能，可以考虑使用上面提到过的[盛派微信 SDK（Senparc.Weixin）](https://github.com/JeffreySu/WeiXinMPSDK)，也很不错。
|
||||
|
||||
当官方更新相关的 API 后，本库也会在第一时间保持跟进。
|
||||
|
||||
### 4. 看了源码，发现模型定义里很多同样的代码是复制粘贴的，为什么不继承？
|
||||
|
||||
关于这点得吐槽微信支付提供的 API 了，很显然微信内部也是很多个 Team 在共同开发，每个 Team、甚至每个人的字段命名风格、约束条件、接口规则都大相径庭，虽然号称 v3 版 API 是 “RESTful” 的，却没一个统一标准。
|
||||
|
||||
举个例子，以分页查询为例，看似字段相同，都由 `offset`、`limit` + `total_count`、`data` 这几个字段构成，但某些接口的 `offset`、`limit` 字段是可选参数，某些却是必填项；某些值从 `0` 起始，某些却是从 `1` 起始；某些接口的 `total_count`、`data` 字段一定会返回，某些却是一定不返回，某些只在特定条件下返回。一共七八个分页查询的接口，却有四五种分页的数据结构，这种情况下很难抽象出一个公共的基类出来。
|
||||
|
||||
同样一个东西在不同接口里竟然拼法不一样；同样是表示数组有的是 JSON、有的却是字符串；诸如此类“奇葩”的情况很多很多。本库已经尽可能在条件允许的范围内抽象出了一些公共基类，聊胜于无。
|
||||
|
||||
19
docs/WechatWork/Advanced_EventDataDeserialization.md
Normal file
19
docs/WechatWork/Advanced_EventDataDeserialization.md
Normal file
@ -0,0 +1,19 @@
|
||||
### 如何解析回调通知事件？
|
||||
|
||||
---
|
||||
|
||||
你可根据官方文档的规则利用本库提供的 `WxBizMsgCryptor` 工具类自行解密回调通知事件的敏感信息。
|
||||
|
||||
对于解密后得到的原始数据，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例：
|
||||
|
||||
```csharp
|
||||
/* 如果是 JSON 格式的通知内容 */
|
||||
string callbackJson = "{ ... }";
|
||||
var callbackModel = client.DeserializeEventFromJson<Events.AddScheduleEvent>(callbackJson);
|
||||
|
||||
/* 如果是 XML 格式的通知内容 */
|
||||
string callbackXml = "<xml> ... </xml>";
|
||||
var callbackModel = client.DeserializeEventFromXml<Events.TextMessageEvent>(callbackXml);
|
||||
```
|
||||
|
||||
完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Work/Events_ 目录。
|
||||
68
docs/WechatWork/Advanced_IHttpClientFactory.md
Normal file
68
docs/WechatWork/Advanced_IHttpClientFactory.md
Normal 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.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)。
|
||||
22
docs/WechatWork/Advanced_JSSDK.md
Normal file
22
docs/WechatWork/Advanced_JSSDK.md
Normal file
@ -0,0 +1,22 @@
|
||||
### 如何生成 JS-SDK 初始化时所需的参数及签名？
|
||||
|
||||
---
|
||||
|
||||
> 请先自行阅读：
|
||||
>
|
||||
> [企业微信 API - 客户端 API：JS-SDK 使用权限签名算法》](https://open.work.weixin.qq.com/api/doc/90000/90136/90506)
|
||||
|
||||
你可根据官方文档的规则利用本库提供的 `SHA1Utility` 工具类自行进行签名生成。
|
||||
|
||||
此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例：
|
||||
|
||||
```csharp
|
||||
var request = new Models.CgibinGetJsapiTicketRequest()
|
||||
{
|
||||
AccessToken = "企业微信应用的 AccessToken"
|
||||
};
|
||||
var response = await client.ExecuteCgibinGetJsapiTicketAsync(request);
|
||||
var paramMap = client.GenerateParametersForJssdkConfigRequest(response.Ticket, "https://example.com");
|
||||
```
|
||||
|
||||
需要注意的是，企业微信 JS-SDK 存在两种初始化方式，生成签名时所需要的 Ticket 获取方式并不相同，请开发者根据需要自行选择。
|
||||
46
docs/WechatWork/Advanced_JsonSerializer.md
Normal file
46
docs/WechatWork/Advanced_JsonSerializer.md
Normal 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/WechatWork/Advanced_ModelDefinition.md
Normal file
11
docs/WechatWork/Advanced_ModelDefinition.md
Normal file
@ -0,0 +1,11 @@
|
||||
### 如何快速找到需要调用的 API 模型类名 / 方法名？
|
||||
|
||||
---
|
||||
|
||||
本库提供的请求模型、响应模型和接口方法，三者均保持同名。
|
||||
|
||||
例如，发送应用消息的请求是 `CgibinMessageSendRequest`，响应是 `CgibinMessageSendResponse`，接口是 `ExecuteCgibinMessageSendAsync()`。知道其中一个，其余两个就可以快速地推断出了。
|
||||
|
||||
再有，每个对象的命名与官方文档的接口地址大体保持一致。例如刚刚提到的发送应用消息，它的接口地址是 `[POST] /cgi-bin/message/send`，将其中的反斜杠去掉、并以大驼峰命名法的方式调整它，就可以得到前文提到的几个对象了。
|
||||
|
||||
完整的模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Work/Models_ 目录。
|
||||
144
docs/WechatWork/README.md
Normal file
144
docs/WechatWork/README.md
Normal file
@ -0,0 +1,144 @@
|
||||
# SKIT.FlurlHttpClient.Wechat.Work
|
||||
|
||||
[](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work)
|
||||
[](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work)
|
||||
[](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat/blob/main/LICENSE)
|
||||
|
||||
基于 `Flurl.Http` 的企业微信 API 客户端。
|
||||
|
||||
---
|
||||
|
||||
## 功能
|
||||
|
||||
- 基于企业微信 API 封装。
|
||||
|
||||
- 支持企业内部开发、第三方应用开发（即服务商）两种模式。
|
||||
|
||||
- 提供了企业微信 API 所需的 SHA-1、AES 等算法工具类。
|
||||
|
||||
- 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。
|
||||
|
||||
- 完整企业微信 API 一览：
|
||||
|
||||
| | 微信 API | 开发模式 | 备注 |
|
||||
| :-: | :----------------------------: | :-------------: | :------------------------------: |
|
||||
| √ | 基础功能 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：成员管理 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：部门管理 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：标签管理 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：异步批量接口 | 企业 & 服务商 | |
|
||||
| √ | 通讯录管理：互联企业 | 企业 | |
|
||||
| √ | 通讯录管理：通讯录搜索 | 服务商 | |
|
||||
| √ | 通讯录管理：通讯录 ID 转译 | 服务商 | |
|
||||
| √ | 客户联系：企业服务人员管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户标签管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：在职继承 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：离职继承 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户群管理 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：客户朋友圈 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：消息推送 | 企业 & 服务商 | |
|
||||
| √ | 客户联系：统计管理 | 企业 & 服务商 | |
|
||||
| √ | 身份验证：网页授权登录 | 企业 & 服务商 | |
|
||||
| √ | 身份验证：扫码授权登录 | 企业 & 服务商 | |
|
||||
| √ | 应用管理：获取或设置应用 | 企业 & 服务商 | |
|
||||
| √ | 应用管理：自定义菜单 | 企业 | |
|
||||
| √ | 应用管理：自定义工作台 | 企业 | |
|
||||
| √ | 消息推送：发送应用消息 | 企业 & 服务商 | |
|
||||
| √ | 消息推送：更新任务卡片消息状态 | 企业 & 服务商 | |
|
||||
| √ | 消息推送：发送消息到群聊会话 | 企业 | |
|
||||
| √ | 消息推送：互联企业消息推送 | 企业 | |
|
||||
| √ | 消息推送：家校消息推送 | 企业 | |
|
||||
| √ | 消息推送：查询应用消息发送统计 | 企业 & 服务商 | |
|
||||
| √ | 素材管理 | 企业 & 服务商 | |
|
||||
| √ | OA：打卡 | 企业 & 服务商 | |
|
||||
| √ | OA：审批 | 企业 & 服务商 | |
|
||||
| √ | OA：汇报 | 企业 & 服务商 | |
|
||||
| √ | OA：自建应用 | 企业 & 服务商 | |
|
||||
| √ | OA：会议室 | 企业 | |
|
||||
| √ | OA：紧急通知 | 企业 | |
|
||||
| √ | 效率工具：日程 | 企业 & 服务商 | |
|
||||
| √ | 效率工具：会议 | 企业 & 服务商 | |
|
||||
| √ | 效率工具：直播 | 企业 & 服务商 | |
|
||||
| √ | 效率工具：微盘 | 企业 | |
|
||||
| √ | 效率工具：公费电话 | 企业 | |
|
||||
| × | <del>企业支付：企业红包</del> | <del>企业</del> | 与其他协议不一致，需提供单独模块 |
|
||||
| × | <del>企业支付：员工付款</del> | <del>企业</del> | 与其他协议不一致，需提供单独模块 |
|
||||
| √ | 企业支付：员工收款 | 企业 | |
|
||||
| √ | 企业支付：对外收款 | 企业 & 服务商 | |
|
||||
| √ | 企业互联 | 企业 & 服务商 | |
|
||||
| √ | 会话内容存档 | 企业 | |
|
||||
| √ | 电子发票 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：基础接口 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：网页授权登录 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：学生与家长管理 | 企业 & 服务商 | |
|
||||
| √ | 家校沟通：部门管理 | 企业 & 服务商 | |
|
||||
| √ | 家校应用：健康上报 | 企业 | |
|
||||
| √ | 家校应用：复学码 | 企业 | |
|
||||
| √ | 家校应用：上课直播 | 企业 & 服务商 | |
|
||||
| √ | 政民沟通：配置服务网格 | 企业 | |
|
||||
| √ | 政民沟通：配置事件类别 | 企业 | |
|
||||
| √ | 政民沟通：巡查上报 | 企业 | |
|
||||
| √ | 政民沟通：居民上报 | 企业 | |
|
||||
| √ | 应用授权 | 服务商 | |
|
||||
| √ | 推广二维码 | 服务商 | |
|
||||
|
||||
---
|
||||
|
||||
## 基础用法
|
||||
|
||||
### 安装：
|
||||
|
||||
提示：如果你使用 Visual Studio NuGet 管理器图形化界面，请在搜索结果中勾选“**包括预发行版**”。
|
||||
|
||||
```shell
|
||||
# 通过 NuGet 安装
|
||||
> Install-Package SKIT.FlurlHttpClient.Wechat.Work
|
||||
|
||||
# 通过 dotnet-tools 安装
|
||||
> dotnet add package SKIT.FlurlHttpClient.Wechat.Work
|
||||
```
|
||||
|
||||
### 初始化：
|
||||
|
||||
```csharp
|
||||
using SKIT.FlurlHttpClient.Wechat;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work;
|
||||
|
||||
var options = new WechatWorkClientOptions()
|
||||
{
|
||||
CorpId = "企业微信 CorpId",
|
||||
AgentId = "企业微信应用的 AgentId",
|
||||
AgentSecret = "企业微信应用的 AgentId"
|
||||
};
|
||||
var client = new WechatWorkClient(options);
|
||||
```
|
||||
|
||||
### 请求 & 响应：
|
||||
|
||||
```csharp
|
||||
using SKIT.FlurlHttpClient.Wechat.Work;
|
||||
using SKIT.FlurlHttpClient.Wechat.Work.Models;
|
||||
|
||||
/* 示例：获取用户信息 */
|
||||
var request = new CgibinUserGetRequest()
|
||||
{
|
||||
AccessToken = "企业微信应用的 AccessToken",
|
||||
UserId = "企业成员账号"
|
||||
};
|
||||
var response = await client.ExecuteCgibinUserGetAsync(request);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 高级技巧
|
||||
|
||||
- [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md)
|
||||
|
||||
- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md)
|
||||
|
||||
- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md)
|
||||
|
||||
- [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md)
|
||||
|
||||
- [如何生成 JS-SDK 初始化时所需的参数及签名？](./Advanced_JSSDK.md)
|
||||
Loading…
Reference in New Issue
Block a user