diff --git a/README.md b/README.md index 53711de3..6de4ff8f 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ --- -## 常见问题 +## Q & A ### 1. 为什么要“造轮子”？ @@ -63,30 +63,22 @@ 与另一个流行的 HTTP 库 [`RestSharp`](https://restsharp.dev/) 相比，`Flurl.Http` 底层基于 `System.Net.Http.HttpClient`，而 `RestSharp` 底层则基于 `System.Net.HttpWebRequest`，前者在多核多线程环境下的性能基准测试中表现要远优于后者，同时也是微软官方目前推荐的 HTTP 客户端方案。 -> 微软官方关于 `System.Net.HttpWebRequest` 与 `System.Net.Http.HttpClient` 的说明： +> 注：微软官方关于 `System.Net.HttpWebRequest` 与 `System.Net.Http.HttpClient` 的说明： > > - [《Microsoft Docs - HttpWebRequest 类（Systen.Net）》](https://docs.microsoft.com/zh-cn/dotnet/api/system.net.httpwebrequest#remarks) > - [《Microsoft Docs - HttpClient 类（Systen.Net.Http）》](https://docs.microsoft.com/zh-cn/dotnet/api/system.net.http.httpclient#httpclient-and-net-core) -### 3. 本库与[盛派微信 SDK（Senparc.Weixin）](https://github.com/JeffreySu/WeiXinMPSDK)有什么区别？ +### 3. 本库与盛派微信 SDK（Senparc.Weixin）有什么区别？ + +> 注：[盛派微信 SDK](https://github.com/JeffreySu/WeiXinMPSDK) 是由苏震巍先生发起的国内知名的 .NET 开源项目。 - 本库专注于 API 本身的封装，捎带提供了一些用于加解密、序列化的工具类，使用起来更加灵活，不限任何框架或项目类型；盛派微信 SDK 提供了大而全的功能，与 MVC / WebAPI 深度集成。 - 本库的接口模型遵循的是微软官方推荐的 C# 属性命名方式（帕斯卡命名法）；盛派微信 SDK 提供的是微信接口本身的命名方式（蛇形命名法和驼峰命名法混杂）。 -- 本库封装了**目前微信官方提供的几乎所有 API**（极个别不支持的已在各模块文档中列出具体原因）；盛派微信 SDK 只提供了常用的 API。 +- 本库封装了目前微信官方提供的几乎所有 API（极个别不支持的已在各模块文档中列出具体原因）；盛派微信 SDK 只提供了常用的 API。 -### 4. 看了源码，发现模型定义里很多同样的代码是复制粘贴的，为什么不继承？ - -关于这点得吐槽微信提供的 API 了，很显然微信内部也是很多个 Team 在共同开发，每个 Team、甚至每个人的字段命名风格、约束条件、接口规则都大相径庭。就连微信支付虽然 v3 版 API 号称是 “RESTful” 的，却也没个统一标准。 - -举个例子，以分页查询为例，看似字段相同，都由 _offset_、_cursor_、_page_、_limit_ + _data_、_total_count_、_next_cursor_ 这几个字段构成，但某些接口的 _offset_、_cursor_、_page_、_limit_ 字段是可选参数，某些却是必填项；某些 _page_ 值从 `0` 起始，某些却是从 `1` 起始；某些接口的 _data_、_total_count_、_next_cursor_ 字段一定会返回，某些却是一定不返回，某些只在特定条件下返回。一共十几个分页查询的接口，却有七八种分页的数据结构，这种情况下很难抽象出一个公共的基类出来。 - -除此之外，同样一个东西在不同接口里竟然拼法不一样；同样是表示数组有的是 JSON、有的却是字符串；诸如此类“奇葩”的情况很多很多。 - -本项目已经尽可能在条件允许的范围内抽象出了一些公共基类、并封装了各种奇怪场景下的 JsonConverter，聊胜于无。 - -### 5. 为什么不支持 .NET Framework 4.0 / .NET Framework 4.5？ +### 4. 为什么不支持 .NET Framework 4.0 / .NET Framework 4.5？ 直接原因是本项目的依赖库最低支持到 .NET Framework 4.6.1。 @@ -94,13 +86,23 @@ 根本原因是微软官方已于 2016 年 1 月 12 日终止了对 .NET Framework 4.6.1 以下版本的技术支持（详情请阅读[官方公告](https://docs.microsoft.com/zh-cn/lifecycle/faq/dotnet-framework)）。也就是说，微软已经不再为此提供安全更新，在大部分技术合规要求中这一点都是扣分项，所以建议各位开发者目标框架能升级就升级。 +### 5. 看了源码，发现模型定义里很多同样的代码是复制粘贴的，为什么不使用面向对象中的继承？ + +关于这点得吐槽微信提供的 API 了，很显然微信内部也是很多个 Team 在共同开发，每个 Team、甚至每个人的字段命名风格、约束条件、接口规则都大相径庭。就连微信支付虽然 v3 版 API 号称是 “RESTful” 的，却也没个统一标准。 + +举个例子，以分页查询为例，看似字段相同，都由 _offset_、_cursor_、_page_、_limit_ + _data_、_total_count_、_next_cursor_ 这几个字段构成，但某些接口的 _offset_、_cursor_、_page_、_limit_ 字段是可选参数，某些却是必填项；某些 _page_ 值从 `0` 起始，某些却是从 `1` 起始；某些接口的 _data_、_total_count_、_next_cursor_ 字段一定会返回，某些却是一定不返回，某些只在特定条件下返回。一共十几个分页查询的接口，却有七八种分页的数据结构，这种情况下很难抽象出一个公共的基类出来。 + +除此之外，同样一个东西在不同接口里竟然拼法不一样；同样是表示数组有的是 JSON、有的却是字符串；诸如此类“奇葩”的情况很多很多。 + +本项目已经尽可能在条件允许的范围内抽象出了一些公共基类、并封装了各种奇怪场景下的自定义 JsonConverter。 + ### 6. 所有 API 都经过了测试吗？ 由于微信的产品业务线众多，很多业务也需要前置条件才能继续，截至目前本项目已封装超过 1900 余个 API，虽然同时也编写了若干单元测试用例，但与数量庞大的 API 相比仍远远不够。 本项目严格按照微信官方提供的开发文档进行封装，并利用自动化工具保证封装结果的正确。但微信的文档本身质量很低，所以存在错误在所难免。 -如果你在使用中遇到了因接口或模型定义错误而产生的问题，欢迎提出 Issue。 +因为微信更新 API 很频繁，对于微信支付或企业微信这种有提供官方更新日志的，本项目会定期查阅更新；其他平台经常会悄悄地更新一波、让所有人懵逼。如果你在使用中遇到了因接口或模型定义错误而产生的问题，欢迎提出 Issue。 --- @@ -122,8 +124,6 @@ 以上仓库地址同步更新，均可接受 Issue 或 Pull Request。 -因为微信更新 API 很频繁，对于微信支付或企业微信这种有提供官方更新日志的，本项目会定期查阅更新；其他平台经常会悄悄地更新一波、让所有人懵逼，如果你遇到了这种情况，欢迎提 Issue 说明。 - 如何参与贡献请参阅 [CONTRIBUTING](./CONTRIBUTING.md)。 --- diff --git a/docs/WechatAds/README.md b/docs/WechatAds/README.md index 63ceffcb..a90ab630 100644 --- a/docs/WechatAds/README.md +++ b/docs/WechatAds/README.md @@ -67,10 +67,10 @@ var response = await client.ExecuteCampaignsAddAsync(request); - [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md) +- [如何获取接口调用凭据（即 AccessToken）？](./Advanced_AccessToken.md) + - [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) - [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) - [如何使用拦截器？](./Advanced_Interceptor.md) - -- [如何获取接口调用凭据（即 AccessToken）？](./Advanced_AccessToken.md) diff --git a/docs/WechatApi/README.md b/docs/WechatApi/README.md index b2e384ee..c44b0ca7 100644 --- a/docs/WechatApi/README.md +++ b/docs/WechatApi/README.md @@ -76,12 +76,6 @@ else - [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md) -- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) - -- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) - -- [如何使用拦截器？](./Advanced_Interceptor.md) - - [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md) - [如何验证回调通知事件签名？](./Advanced_EventDataSignatureVerification.md) @@ -92,6 +86,12 @@ else - [如何扩展额外的 API？](./Advanced_Extensions.md) +- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) + +- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) + +- [如何使用拦截器？](./Advanced_Interceptor.md) + --- ## 示例项目 diff --git a/docs/WechatTenpayBusiness/README.md b/docs/WechatTenpayBusiness/README.md index 91568626..8adccd59 100644 --- a/docs/WechatTenpayBusiness/README.md +++ b/docs/WechatTenpayBusiness/README.md @@ -76,12 +76,6 @@ else - [如何快速找到需要调用的 API 模型类名 / 方法名（附完整 API 对照表）？](./Advanced_ModelDefinition.md) -- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) - -- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) - -- [如何使用拦截器？](./Advanced_Interceptor.md) - - [如何加密请求中的敏感数据？](./Advanced_RequestSensitiveDataEncryption.md) - [如何解密响应中的敏感数据？](./Advanced_ResponseSensitiveDataDecryption.md) @@ -89,3 +83,9 @@ else - [如何验证响应签名？](./Advanced_ResponseSignatureVerification.md) - [如何验证回调通知事件签名？](./Advanced_EventSignatureVerification.md) + +- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) + +- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) + +- [如何使用拦截器？](./Advanced_Interceptor.md) diff --git a/docs/WechatTenpayV2/Advanced_Parameters.md b/docs/WechatTenpayV2/Advanced_Parameters.md index 60b41f4c..7ed87e87 100644 --- a/docs/WechatTenpayV2/Advanced_Parameters.md +++ b/docs/WechatTenpayV2/Advanced_Parameters.md @@ -1,4 +1,4 @@ -## 如何生成客户端调起支付时所需的参数及签名？ +## 如何生成客户端（JS-SDK、小程序、App 等）所需的参数及签名？ --- diff --git a/docs/WechatTenpayV2/README.md b/docs/WechatTenpayV2/README.md index 41a56e09..8ab20e54 100644 --- a/docs/WechatTenpayV2/README.md +++ b/docs/WechatTenpayV2/README.md @@ -90,14 +90,14 @@ else - [如何快速找到需要调用的 API 模型类名 / 方法名（附完整 API 对照表）？](./Advanced_ModelDefinition.md) +- [如何解密回调通知事件中的敏感数据？](./Advanced_EventInfoDecryption.md) + +- [如何验证回调通知事件签名？](./Advanced_EventSignatureVerification.md) + +- [如何生成客户端（JSAPI、小程序、App 等）所需的参数及签名？](./Advanced_Parameters.md) + - [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) - [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) - [如何使用拦截器？](./Advanced_Interceptor.md) - -- [如何解密回调通知事件中的敏感数据？](./Advanced_EventInfoDecryption.md) - -- [如何验证回调通知事件签名？](./Advanced_EventSignatureVerification.md) - -- [如何生成客户端调起支付时所需的参数及签名？](./Advanced_Parameters.md) diff --git a/docs/WechatTenpayV3/Advanced_Parameters.md b/docs/WechatTenpayV3/Advanced_Parameters.md index 6d504369..a881dd82 100644 --- a/docs/WechatTenpayV3/Advanced_Parameters.md +++ b/docs/WechatTenpayV3/Advanced_Parameters.md @@ -1,4 +1,4 @@ -## 如何生成客户端调起支付时所需的参数及签名？ +## 如何生成客户端（JSAPI、小程序、App 等）所需的参数及二次签名？ --- diff --git a/docs/WechatTenpayV3/README.md b/docs/WechatTenpayV3/README.md index 8553d47f..1733366f 100644 --- a/docs/WechatTenpayV3/README.md +++ b/docs/WechatTenpayV3/README.md @@ -94,12 +94,6 @@ else - [如何快速找到需要调用的 API 模型类名 / 方法名（附完整 API 对照表）？](./Advanced_ModelDefinition.md) -- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) - -- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) - -- [如何使用拦截器？](./Advanced_Interceptor.md) - - [如何查看商户证书序列号？](./Advanced_CertificateSerialNumber.md) - [如何加密请求中的敏感数据？](./Advanced_RequestSensitiveDataEncryption.md) @@ -112,12 +106,18 @@ else - [如何验证回调通知事件签名？](./Advanced_EventSignatureVerification.md) -- [如何生成客户端调起支付时所需的参数及签名？](./Advanced_Parameters.md) +- [如何生成客户端（JSAPI、小程序、App 等）所需的参数及二次签名？](./Advanced_Parameters.md) - [如何接入国密算法？](./Advanced_SMAlgorithm.md) - [如何扩展额外的 API？](./Advanced_Extensions.md) +- [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) + +- [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) + +- [如何使用拦截器？](./Advanced_Interceptor.md) + --- ## 示例项目 diff --git a/docs/WechatWork/Advanced_Parameters.md b/docs/WechatWork/Advanced_Parameters.md index 0db72d91..b822ae8f 100644 --- a/docs/WechatWork/Advanced_Parameters.md +++ b/docs/WechatWork/Advanced_Parameters.md @@ -1,4 +1,4 @@ -## 如何生成 JS-SDK 初始化时所需的参数及签名？ +## 如何生成 JS-SDK 所需的参数及签名？ --- diff --git a/docs/WechatWork/README.md b/docs/WechatWork/README.md index 029062d8..1d60fae4 100644 --- a/docs/WechatWork/README.md +++ b/docs/WechatWork/README.md @@ -76,14 +76,14 @@ else - [如何快速找到需要调用的 API 模型类名 / 方法名？](./Advanced_ModelDefinition.md) +- [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md) + +- [如何生成 JS-SDK 所需的参数及签名？](./Advanced_Parameters.md) + +- [如何扩展额外的 API？](./Advanced_Extensions.md) + - [如何在 ASP.NET Core 中与 `IHttpClientFactory` 集成？](./Advanced_IHttpClientFactory.md) - [如何指定 JSON 序列化器？](./Advanced_JsonSerializer.md) - [如何使用拦截器？](./Advanced_Interceptor.md) - -- [如何解析回调通知事件？](./Advanced_EventDataDeserialization.md) - -- [如何生成 JS-SDK 初始化时所需的参数及签名？](./Advanced_Parameters.md) - -- [如何扩展额外的 API？](./Advanced_Extensions.md)