2021-08-20 15:16:48 +08:00
|
|
|
|
# SKIT.FlurlHttpClient.Wechat
|
2021-05-10 15:30:00 +08:00
|
|
|
|
|
2021-10-06 19:39:59 +08:00
|
|
|
|
[](https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)
|
|
|
|
|
|
[](https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)
|
2021-09-11 18:10:32 +08:00
|
|
|
|
[](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)
|
|
|
|
|
|
[](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)
|
2021-09-11 19:08:14 +08:00
|
|
|
|
[](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat)
|
2021-09-11 18:10:32 +08:00
|
|
|
|
[](https://mit-license.org/)
|
2021-08-16 11:40:43 +08:00
|
|
|
|
|
2023-03-02 19:36:47 +08:00
|
|
|
|
基于 `Flurl.Http` 的微信 HTTP API SDK，目前已包含公众平台、开放平台、商户平台、企业微信、广告平台、对话开放平台等模块。
|
2021-05-10 15:30:00 +08:00
|
|
|
|
|
2021-08-26 18:02:27 +08:00
|
|
|
|
> 更多 SKIT.FlurlHttpClient 系列开发工具包请[点此查看](https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient)。
|
|
|
|
|
|
|
2021-05-10 15:30:00 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 特性
|
|
|
|
|
|
|
|
|
|
|
|
- 基于 `Flurl.Http`，可与 `IHttpClientFactory` 集成。
|
2023-03-02 19:36:47 +08:00
|
|
|
|
- 支持 .NET Framework 4.6.1+、.NET Standard 2.0+、.NET Core 2.0+、.NET 5+。
|
2021-05-10 15:30:00 +08:00
|
|
|
|
- 支持 Windows / Linux / macOS 多平台部署。
|
|
|
|
|
|
- 支持 `System.Text.Json`（默认）和 `Newtonsoft.Json` 两种序列化方式。
|
|
|
|
|
|
- 强类型接口模型。
|
2023-03-02 19:36:47 +08:00
|
|
|
|
- 全异步式编程。
|
|
|
|
|
|
- 提供 SourceLink 调试符号文件。
|
|
|
|
|
|
- 完整、完善、完全的微信 HTTP API 封装。
|
2021-05-10 15:30:00 +08:00
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 模块
|
|
|
|
|
|
|
2022-11-04 14:13:32 +08:00
|
|
|
|
| 名称 | NuGet | 其他 |
|
|
|
|
|
|
| :----------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------: |
|
|
|
|
|
|
| 公众平台（公众号、小程序、视频号） <br> + 开放平台模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api) <br> [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Api) | [开发文档](./docs/WechatApi/README.md)｜[示例项目](./docs/WechatApi/Sample.md) |
|
|
|
|
|
|
| 商户平台（微信支付）模块 <br> （针对 v3 版接口） | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV3) <br> [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV3) | [开发文档](./docs/WechatTenpayV3/README.md)｜[示例项目](./docs/WechatTenpayV3/Sample.md) |
|
|
|
|
|
|
| 商户平台（微信支付）模块 <br> （针对 v2 版接口） | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV2) <br> [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayV2) | [开发文档](./docs/WechatTenpayV2/README.md) |
|
|
|
|
|
|
| 企业微信（企业号）模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work) <br> [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Work) | [开发文档](./docs/WechatWork/README.md) |
|
|
|
|
|
|
| 广告平台（广点通）模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Ads) <br> [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.Ads) | [开发文档](./docs/WechatAds/README.md) |
|
|
|
|
|
|
| 对话开放平台（微信智能对话）模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.OpenAI) <br> [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.OpenAI) | [开发文档](./docs/WechatOpenAI/README.md) |
|
|
|
|
|
|
| 腾讯微企付模块 | [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayBusiness) <br> [](https://www.nuget.org/packages/SKIT.FlurlHttpClient.Wechat.TenpayBusiness) | [开发文档](./docs/WechatTenpayBusiness/README.md) |
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
## Q & A
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
|
|
|
|
|
### 1. 为什么要“造轮子”？
|
|
|
|
|
|
|
2021-11-29 12:14:42 +08:00
|
|
|
|
这都 2021 年了，官方本身提供的示例代码还只能运行在 .NET Framework on Windows 上；就连 RSA 签名这么基础的东西都没有人封装（确切地说是因为 RSA 有很多种分块模式和填充模式，网上能找到的往往只封装了其中一种，但却未必符合微信的要求）；全网很难找到一个封装微信 API 尽可能全的 .NET SDK，开源的项目有不少，但作者能坚持下去的不多。
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
|
|
|
|
|
于是萌生了自己封装一个库的想法，打算解决这几个痛点，同时也是推广一下微软官方的 `System.Text.Json`。
|
|
|
|
|
|
|
2021-08-03 20:29:06 +08:00
|
|
|
|
### 2. `Flurl.Http` 是什么？
|
|
|
|
|
|
|
|
|
|
|
|
[`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 客户端方案。
|
|
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
> 注：微软官方关于 `System.Net.HttpWebRequest` 与 `System.Net.Http.HttpClient` 的说明：
|
2021-11-29 12:14:42 +08:00
|
|
|
|
>
|
|
|
|
|
|
> - [《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)
|
2021-08-03 20:29:06 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
### 3. 本库与盛派微信 SDK（Senparc.Weixin）有什么区别？
|
|
|
|
|
|
|
|
|
|
|
|
> 注：[盛派微信 SDK](https://github.com/JeffreySu/WeiXinMPSDK) 是由苏震巍先生发起的国内知名的 .NET 开源项目。
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
2021-12-19 21:10:10 +08:00
|
|
|
|
- 本库专注于 API 本身的封装，捎带提供了一些用于加解密、序列化的工具类，使用起来更加灵活，不限任何框架或项目类型；盛派微信 SDK 提供了大而全的功能，与 MVC / WebAPI 深度集成。
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
2021-12-19 21:10:10 +08:00
|
|
|
|
- 本库的接口模型遵循的是微软官方推荐的 C# 属性命名方式（帕斯卡命名法）；盛派微信 SDK 提供的是微信接口本身的命名方式（蛇形命名法和驼峰命名法混杂）。
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
- 本库封装了目前微信官方提供的几乎所有 API（极个别不支持的已在各模块文档中列出具体原因）；盛派微信 SDK 只提供了常用的 API。
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
### 4. 为什么不支持 .NET Framework 4.0 / .NET Framework 4.5？
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
直接原因是本项目的依赖库最低支持到 .NET Framework 4.6.1。
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
间接原因是为了支持跨平台的 .NET Standard 2.0，只能兼容到 .NET Framework 4.6.1。
|
2021-06-07 00:32:04 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
根本原因是微软官方已于 2016 年 1 月 12 日终止了对 .NET Framework 4.6.1 以下版本的技术支持（详情请阅读[官方公告](https://docs.microsoft.com/zh-cn/lifecycle/faq/dotnet-framework)）。也就是说，微软已经不再为此提供安全更新，在大部分技术合规要求中这一点都是扣分项，所以建议各位开发者目标框架能升级就升级。
|
2021-08-02 11:45:37 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
### 5. 看了源码，发现模型定义里很多同样的代码是复制粘贴的，为什么不使用面向对象中的继承？
|
2021-06-10 16:29:39 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
关于这点得吐槽微信提供的 API 了，很显然微信内部也是很多个 Team 在共同开发，每个 Team、甚至每个人的字段命名风格、约束条件、接口规则都大相径庭。就连微信支付虽然 v3 版 API 号称是 “RESTful” 的，却也没个统一标准。
|
2021-07-12 13:03:21 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
举个例子，以分页查询为例，看似字段相同，都由 _offset_、_cursor_、_page_、_limit_ + _data_、_total_count_、_next_cursor_ 这几个字段构成，但某些接口的 _offset_、_cursor_、_page_、_limit_ 字段是可选参数，某些却是必填项；某些 _page_ 值从 `0` 起始，某些却是从 `1` 起始；某些接口的 _data_、_total_count_、_next_cursor_ 字段一定会返回，某些却是一定不返回，某些只在特定条件下返回。一共十几个分页查询的接口，却有七八种分页的数据结构，这种情况下很难抽象出一个公共的基类出来。
|
2021-07-12 13:03:21 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
除此之外，同样一个东西在不同接口里竟然拼法不一样；同样是表示数组有的是 JSON、有的却是字符串；诸如此类“奇葩”的情况很多很多。
|
2021-07-12 13:03:21 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
本项目已经尽可能在条件允许的范围内抽象出了一些公共基类、并封装了各种奇怪场景下的自定义 JsonConverter。
|
2021-07-12 13:03:21 +08:00
|
|
|
|
|
2021-08-11 15:37:17 +08:00
|
|
|
|
### 6. 所有 API 都经过了测试吗？
|
|
|
|
|
|
|
2024-01-15 22:13:52 +08:00
|
|
|
|
由于微信的产品业务线众多，很多业务也需要前置条件才能继续，截至目前本项目已封装超过 2300 余个 API，虽然同时也编写了若干单元测试用例，但与数量庞大的 API 相比仍远远不够。
|
2021-08-11 15:37:17 +08:00
|
|
|
|
|
2024-01-15 22:13:52 +08:00
|
|
|
|
本项目严格按照微信官方提供的开发文档进行封装，并利用自动化工具保证封装结果的正确。但微信的文档本身质量比较低，所以存在错误在所难免。
|
2021-08-11 15:37:17 +08:00
|
|
|
|
|
2022-12-15 11:59:29 +08:00
|
|
|
|
因为微信更新 API 很频繁，对于微信支付或企业微信这种有提供官方更新日志的，本项目会定期查阅更新；其他平台经常会悄悄地更新一波、让所有人懵逼。如果你在使用中遇到了因接口或模型定义错误而产生的问题，欢迎提出 Issue。
|
2021-08-11 15:37:17 +08:00
|
|
|
|
|
2021-06-10 16:29:39 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
2021-08-01 20:23:05 +08:00
|
|
|
|
## 使用案例
|
2021-08-01 20:17:15 +08:00
|
|
|
|
|
2023-06-14 16:40:02 +08:00
|
|
|
|
| 项目名称 | 项目简介 | 项目地址 |
|
|
|
|
|
|
| :-------: | :--------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------: |
|
|
|
|
|
|
| CoreShop | 核心商城系统：支持可视化布局的 .NET 商城系统。 | [](https://gitee.com/CoreUnion/CoreShop) |
|
|
|
|
|
|
| Admin.NET | 通用权限开发框架：整合最新技术，模块插件式开发，前后端分离，开箱即用。 | [](https://gitee.com/zuohuaijun/Admin.NET) |
|
2021-08-01 20:17:15 +08:00
|
|
|
|
|
2021-08-25 17:13:49 +08:00
|
|
|
|
注：以上案例均来自第三方，本项目不对其项目做任何保证，仅作列举展示。如果你有项目也使用了本库、希望加到案例列表中，可以在 Issue 中提出。
|
2021-08-03 14:28:12 +08:00
|
|
|
|
|
2021-08-01 20:17:15 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
2021-08-25 17:13:49 +08:00
|
|
|
|
## 参与贡献
|
2021-06-10 16:29:39 +08:00
|
|
|
|
|
2021-11-29 12:14:42 +08:00
|
|
|
|
- GitHub Repo：https://github.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat.git
|
|
|
|
|
|
- Gitee Repo：https://gitee.com/fudiwei/DotNetCore.SKIT.FlurlHttpClient.Wechat.git
|
2021-06-10 16:29:39 +08:00
|
|
|
|
|
|
|
|
|
|
以上仓库地址同步更新，均可接受 Issue 或 Pull Request。
|
2021-07-05 16:26:26 +08:00
|
|
|
|
|
2021-08-25 17:13:49 +08:00
|
|
|
|
如何参与贡献请参阅 [CONTRIBUTING](./CONTRIBUTING.md)。
|
2021-08-05 12:56:40 +08:00
|
|
|
|
|
2021-07-05 16:26:26 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 更新日志
|
|
|
|
|
|
|
2021-08-25 17:13:49 +08:00
|
|
|
|
详细更新说明请参阅 [CHANGELOG](./CHANGELOG.md)。
|
