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:
fudiwei
parent
8def1f962e
commit
4d1b15f762
36
README.md
36
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)。
|
||||
|
||||
---
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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)
|
||||
|
||||
---
|
||||
|
||||
## 示例项目
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
## 如何生成客户端调起支付时所需的参数及签名？
|
||||
## 如何生成客户端（JS-SDK、小程序、App 等）所需的参数及签名？
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
## 如何生成客户端调起支付时所需的参数及签名？
|
||||
## 如何生成客户端（JSAPI、小程序、App 等）所需的参数及二次签名？
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
---
|
||||
|
||||
## 示例项目
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
## 如何生成 JS-SDK 初始化时所需的参数及签名？
|
||||
## 如何生成 JS-SDK 所需的参数及签名？
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user