From 8609f89c6d9bf569703887c19b3ed08c68ccd452 Mon Sep 17 00:00:00 2001 From: Fu Diwei Date: Mon, 7 Jun 2021 00:32:04 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 34 ++++- .../Advanced_EventDataDeserialization.md | 10 +- docs/WechatApi/Advanced_JSSDK.md | 2 +- docs/WechatApi/README.md | 4 +- .../Advanced_EventDataDecryption.md | 4 +- docs/WechatTenpayV3/Advanced_Payment.md | 2 +- .../Advanced_ResponseDataDecryption.md | 4 +- .../Advanced_ResponseSignatureVerification.md | 4 +- docs/WechatTenpayV3/README.md | 40 +---- .../Advanced_EventDataDeserialization.md | 19 +++ .../WechatWork/Advanced_IHttpClientFactory.md | 68 +++++++++ docs/WechatWork/Advanced_JSSDK.md | 22 +++ docs/WechatWork/Advanced_JsonSerializer.md | 46 ++++++ docs/WechatWork/Advanced_ModelDefinition.md | 11 ++ docs/WechatWork/README.md | 144 ++++++++++++++++++ 15 files changed, 360 insertions(+), 54 deletions(-) create mode 100644 docs/WechatWork/Advanced_EventDataDeserialization.md create mode 100644 docs/WechatWork/Advanced_IHttpClientFactory.md create mode 100644 docs/WechatWork/Advanced_JSSDK.md create mode 100644 docs/WechatWork/Advanced_JsonSerializer.md create mode 100644 docs/WechatWork/Advanced_ModelDefinition.md create mode 100644 docs/WechatWork/README.md diff --git a/README.md b/README.md index 5eddee80..ef7c4069 100644 --- a/README.md +++ b/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 @@ | :---------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------: | | 公众平台（公众号、小程序） & 开放平台模块 | [![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) | -| 企业微信模块 | _开发中_ | | +| 企业微信模块 | [![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Work.svg?sanitize=true)](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，聊胜于无。 diff --git a/docs/WechatApi/Advanced_EventDataDeserialization.md b/docs/WechatApi/Advanced_EventDataDeserialization.md index 518d9c97..a6247991 100644 --- a/docs/WechatApi/Advanced_EventDataDeserialization.md +++ b/docs/WechatApi/Advanced_EventDataDeserialization.md @@ -2,16 +2,20 @@ --- -本库封装了直接解析事件的扩展方法，下面给出一个示例： +你可根据官方文档的规则利用本库提供的 `WxBizMsgCryptor` 工具类自行解密回调通知事件的敏感信息。 + +对于解密后得到的原始数据，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例： ```csharp /* 如果是 JSON 格式的通知内容 */ -string callbackJson = "..."; +string callbackJson = "{ ... }"; var callbackModel = client.DeserializeEventFromJson(callbackJson); /* 如果是 XML 格式的通知内容 */ -string callbackXml = "..."; +string callbackXml = " ... "; var callbackModel = client.DeserializeEventFromXml(callbackXml); ``` 完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Api/Events_ 目录。 + +需要注意的是，如果在微信公众平台后台配置中选择了明文模式，则无需对数据进行解密。 diff --git a/docs/WechatApi/Advanced_JSSDK.md b/docs/WechatApi/Advanced_JSSDK.md index 4cee6e82..f0a670ad 100644 --- a/docs/WechatApi/Advanced_JSSDK.md +++ b/docs/WechatApi/Advanced_JSSDK.md @@ -6,7 +6,7 @@ > > [《微信官方文档 - 微信网页开发：JS-SDK 说明文档》](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/JS-SDK.html) -你可根据官方文档的规则利用本库提供的 `Sha1Util` 工具类自行进行签名生成。 +你可根据官方文档的规则利用本库提供的 `SHA1Utility` 工具类自行进行签名生成。 此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例： diff --git a/docs/WechatApi/README.md b/docs/WechatApi/README.md index fcb392e7..6cbc5e27 100644 --- a/docs/WechatApi/README.md +++ b/docs/WechatApi/README.md @@ -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); ``` --- diff --git a/docs/WechatTenpayV3/Advanced_EventDataDecryption.md b/docs/WechatTenpayV3/Advanced_EventDataDecryption.md index 5699b9e2..0c10673d 100644 --- a/docs/WechatTenpayV3/Advanced_EventDataDecryption.md +++ b/docs/WechatTenpayV3/Advanced_EventDataDecryption.md @@ -8,12 +8,12 @@ 对于回调通知事件的敏感信息，微信支付平台使用了商户公钥基于 RSA 算法加密。 -开发者利用本库提供的 `RsaUtil` 工具类自行解密相关字段。 +开发者利用本库提供的 `RSAUtility` 工具类自行解密相关字段。 此外，本库还封装了直接解密事件的扩展方法，下面给出一个示例： ```csharp -string callbackJson = "..."; // 微信支付平台发来的通知内容 +string callbackJson = "{ ... }"; // 微信支付平台发来的通知内容 var callbackModel = client.DeserializeEvent(callbackJson); // 得到通知对象 if ("TRANSACTION.SUCCESS".Equals(callbackModel.EventType)) diff --git a/docs/WechatTenpayV3/Advanced_Payment.md b/docs/WechatTenpayV3/Advanced_Payment.md index e25a8198..e0b70873 100644 --- a/docs/WechatTenpayV3/Advanced_Payment.md +++ b/docs/WechatTenpayV3/Advanced_Payment.md @@ -10,7 +10,7 @@ > > [《微信支付开发者文档 - 基础支付：小程序调起支付 API》](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_5_4.shtml) -你可根据官方文档的规则利用本库提供的 `RsaUtil` 工具类自行进行签名生成。 +你可根据官方文档的规则利用本库提供的 `RSAUtility` 工具类自行进行签名生成。 此外，本库还封装了直接生成参数及签名的扩展方法，下面给出一个示例： diff --git a/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md b/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md index 454dcd64..c3d97376 100644 --- a/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md +++ b/docs/WechatTenpayV3/Advanced_ResponseDataDecryption.md @@ -12,9 +12,9 @@ - 使用商户公钥基于 RSA 算法加密。 -- 使用商户 API v3 密钥基于 AES-GCM 算法加密。 +- 使用商户 API v3 密钥基于 AEAD-AES-GCM 算法加密。 -开发者利用本库提供的 `RsaUtil`、`AesUtil` 工具类自行解密相关字段。 +开发者利用本库提供的 `RSAUtility`、`AESUtility` 工具类自行解密相关字段。 此外，本库还封装了直接解密响应的扩展方法，下面给出一个示例： diff --git a/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md b/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md index 6eef293e..eea0bc18 100644 --- a/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md +++ b/docs/WechatTenpayV3/Advanced_ResponseSignatureVerification.md @@ -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 证书验证签名的方法。 diff --git a/docs/WechatTenpayV3/README.md b/docs/WechatTenpayV3/README.md index 23182ba2..97a28eb5 100644 --- a/docs/WechatTenpayV3/README.md +++ b/docs/WechatTenpayV3/README.md @@ -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、有的却是字符串；诸如此类“奇葩”的情况很多很多。本库已经尽可能在条件允许的范围内抽象出了一些公共基类，聊胜于无。 diff --git a/docs/WechatWork/Advanced_EventDataDeserialization.md b/docs/WechatWork/Advanced_EventDataDeserialization.md new file mode 100644 index 00000000..205798a3 --- /dev/null +++ b/docs/WechatWork/Advanced_EventDataDeserialization.md @@ -0,0 +1,19 @@ +### 如何解析回调通知事件？ + +--- + +你可根据官方文档的规则利用本库提供的 `WxBizMsgCryptor` 工具类自行解密回调通知事件的敏感信息。 + +对于解密后得到的原始数据，本库封装了直接解析成事件模型的扩展方法，下面给出一个示例： + +```csharp +/* 如果是 JSON 格式的通知内容 */ +string callbackJson = "{ ... }"; +var callbackModel = client.DeserializeEventFromJson(callbackJson); + +/* 如果是 XML 格式的通知内容 */ +string callbackXml = " ... "; +var callbackModel = client.DeserializeEventFromXml(callbackXml); +``` + +完整的回调通知模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Work/Events_ 目录。 diff --git a/docs/WechatWork/Advanced_IHttpClientFactory.md b/docs/WechatWork/Advanced_IHttpClientFactory.md new file mode 100644 index 00000000..6c8f5987 --- /dev/null +++ b/docs/WechatWork/Advanced_IHttpClientFactory.md @@ -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; + + public WechatApiClientFactory( + System.Net.Http.IHttpClientFactory httpClientFactory, + IOptions 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)。 diff --git a/docs/WechatWork/Advanced_JSSDK.md b/docs/WechatWork/Advanced_JSSDK.md new file mode 100644 index 00000000..0dab4266 --- /dev/null +++ b/docs/WechatWork/Advanced_JSSDK.md @@ -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 获取方式并不相同，请开发者根据需要自行选择。 diff --git a/docs/WechatWork/Advanced_JsonSerializer.md b/docs/WechatWork/Advanced_JsonSerializer.md new file mode 100644 index 00000000..705ca8f3 --- /dev/null +++ b/docs/WechatWork/Advanced_JsonSerializer.md @@ -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); +}); +``` diff --git a/docs/WechatWork/Advanced_ModelDefinition.md b/docs/WechatWork/Advanced_ModelDefinition.md new file mode 100644 index 00000000..577c1caa --- /dev/null +++ b/docs/WechatWork/Advanced_ModelDefinition.md @@ -0,0 +1,11 @@ +### 如何快速找到需要调用的 API 模型类名 / 方法名？ + +--- + +本库提供的请求模型、响应模型和接口方法，三者均保持同名。 + +例如，发送应用消息的请求是 `CgibinMessageSendRequest`，响应是 `CgibinMessageSendResponse`，接口是 `ExecuteCgibinMessageSendAsync()`。知道其中一个，其余两个就可以快速地推断出了。 + +再有，每个对象的命名与官方文档的接口地址大体保持一致。例如刚刚提到的发送应用消息，它的接口地址是 `[POST] /cgi-bin/message/send`，将其中的反斜杠去掉、并以大驼峰命名法的方式调整它，就可以得到前文提到的几个对象了。 + +完整的模型定义可以参考项目目录下的 _src/SKIT.FlurlHttpClient.Wechat.Work/Models_ 目录。 \ No newline at end of file diff --git a/docs/WechatWork/README.md b/docs/WechatWork/README.md new file mode 100644 index 00000000..cc76378b --- /dev/null +++ b/docs/WechatWork/README.md @@ -0,0 +1,144 @@ +# SKIT.FlurlHttpClient.Wechat.Work + +[![NuGet Version](https://img.shields.io/nuget/v/SKIT.FlurlHttpClient.Wechat.Work.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work) +[![NuGet Download](https://img.shields.io/nuget/dt/SKIT.FlurlHttpClient.Wechat.Work.svg?sanitize=true)](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work) +[![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、AES 等算法工具类。 + +- 提供了 JS-SDK 签名、解析回调通知事件等扩展方法。 + +- 完整企业微信 API 一览： + + | | 微信 API | 开发模式 | 备注 | + | :-: | :----------------------------: | :-------------: | :------------------------------: | + | √ | 基础功能 | 企业 & 服务商 | | + | √ | 通讯录管理：成员管理 | 企业 & 服务商 | | + | √ | 通讯录管理：部门管理 | 企业 & 服务商 | | + | √ | 通讯录管理：标签管理 | 企业 & 服务商 | | + | √ | 通讯录管理：异步批量接口 | 企业 & 服务商 | | + | √ | 通讯录管理：互联企业 | 企业 | | + | √ | 通讯录管理：通讯录搜索 | 服务商 | | + | √ | 通讯录管理：通讯录 ID 转译 | 服务商 | | + | √ | 客户联系：企业服务人员管理 | 企业 & 服务商 | | + | √ | 客户联系：客户管理 | 企业 & 服务商 | | + | √ | 客户联系：客户标签管理 | 企业 & 服务商 | | + | √ | 客户联系：在职继承 | 企业 & 服务商 | | + | √ | 客户联系：离职继承 | 企业 & 服务商 | | + | √ | 客户联系：客户群管理 | 企业 & 服务商 | | + | √ | 客户联系：客户朋友圈 | 企业 & 服务商 | | + | √ | 客户联系：消息推送 | 企业 & 服务商 | | + | √ | 客户联系：统计管理 | 企业 & 服务商 | | + | √ | 身份验证：网页授权登录 | 企业 & 服务商 | | + | √ | 身份验证：扫码授权登录 | 企业 & 服务商 | | + | √ | 应用管理：获取或设置应用 | 企业 & 服务商 | | + | √ | 应用管理：自定义菜单 | 企业 | | + | √ | 应用管理：自定义工作台 | 企业 | | + | √ | 消息推送：发送应用消息 | 企业 & 服务商 | | + | √ | 消息推送：更新任务卡片消息状态 | 企业 & 服务商 | | + | √ | 消息推送：发送消息到群聊会话 | 企业 | | + | √ | 消息推送：互联企业消息推送 | 企业 | | + | √ | 消息推送：家校消息推送 | 企业 | | + | √ | 消息推送：查询应用消息发送统计 | 企业 & 服务商 | | + | √ | 素材管理 | 企业 & 服务商 | | + | √ | OA：打卡 | 企业 & 服务商 | | + | √ | OA：审批 | 企业 & 服务商 | | + | √ | OA：汇报 | 企业 & 服务商 | | + | √ | OA：自建应用 | 企业 & 服务商 | | + | √ | OA：会议室 | 企业 | | + | √ | OA：紧急通知 | 企业 | | + | √ | 效率工具：日程 | 企业 & 服务商 | | + | √ | 效率工具：会议 | 企业 & 服务商 | | + | √ | 效率工具：直播 | 企业 & 服务商 | | + | √ | 效率工具：微盘 | 企业 | | + | √ | 效率工具：公费电话 | 企业 | | + | × | 企业支付：企业红包 | 企业 | 与其他协议不一致，需提供单独模块 | + | × | 企业支付：员工付款 | 企业 | 与其他协议不一致，需提供单独模块 | + | √ | 企业支付：员工收款 | 企业 | | + | √ | 企业支付：对外收款 | 企业 & 服务商 | | + | √ | 企业互联 | 企业 & 服务商 | | + | √ | 会话内容存档 | 企业 | | + | √ | 电子发票 | 企业 & 服务商 | | + | √ | 家校沟通：基础接口 | 企业 & 服务商 | | + | √ | 家校沟通：网页授权登录 | 企业 & 服务商 | | + | √ | 家校沟通：学生与家长管理 | 企业 & 服务商 | | + | √ | 家校沟通：部门管理 | 企业 & 服务商 | | + | √ | 家校应用：健康上报 | 企业 | | + | √ | 家校应用：复学码 | 企业 | | + | √ | 家校应用：上课直播 | 企业 & 服务商 | | + | √ | 政民沟通：配置服务网格 | 企业 | | + | √ | 政民沟通：配置事件类别 | 企业 | | + | √ | 政民沟通：巡查上报 | 企业 | | + | √ | 政民沟通：居民上报 | 企业 | | + | √ | 应用授权 | 服务商 | | + | √ | 推广二维码 | 服务商 | | + +--- + +## 基础用法 + +### 安装： + +提示：如果你使用 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)