docs: 完善文档

This commit is contained in:
Fu Diwei
2024-02-07 18:02:46 +08:00
committed by RHQYZ
parent 33928a5318
commit 2e1f3eba89
17 changed files with 374 additions and 35 deletions

View File

@@ -0,0 +1,79 @@
## v3.x 迁移指南
v3.x 版本是一个主要版本,其中包括了一些破坏性的变化。从 v2.x 升级到 v3.x 之前,请仔细阅读本文档。
---
### 目标框架和框架的变更
微软官方已与 2022 年 4 月 26 日宣布中止对 .NET Framework 4.6.1 的支持。因此,本项目的最低运行时要求调整为 .NET Framework 4.6.2。
与此同时,相关的 .NET 基础库(即通常在 `System.*``Microsoft.*` 命名空间下的内置类型)版本对齐至 .NET 8.0。
### `Flurl.Http` 的变更
本库所依赖的 `Flurl.Http` 版本已升级至 v4.0.0,并由此带来一些底层的破坏性变化。
通常情况下,开发者不需要关注这些变化,除非你正在自定义额外的 API 接口。
### 新的构造器模式
随着 `Flurl.Http` 的升级,原有的与 `IHttpClientFactory` 集成的方式发生了根本性的改变。
为了应对这种变化(请参阅本文档[《如何与 `IHttpClientFactory` 集成?》](./Advanced_IHttpClientFactory.md)),也为了日后能更加灵活地配置客户端,我们在新版本中提供了构造器模式来构造客户端:
```csharp
var options = new WechatApiClientOptions() { /* 具体配置项略 */ };
var client = WechatApiClientBuilder.Create(options).Build();
```
当然,原有的实例化方式仍然可用:
```csharp
var options = new WechatApiClientOptions() { /* 具体配置项略 */ };
var client = new WechatApiClient(options);
```
### 基础类型:`SKIT.FlurlHttpClient.Primitives.EncodedeString`
在进行加解密或哈希等操作时,参与运算的数据和最终得到的结果通常是字节数组(即 `byte[]`)形式。而在实际应用中,我们常常需要将这些字节序列转换成文本格式。我们发现即便是同一种加解密或哈希算法,在不同平台上所需要的编码方式也可能不同。比如同为 SHA256在某些接口中需要转换为十六进制HEX编码传参而在另一些接口中却需要转换为 Base64 编码传参。
在过往的版本中,我们在不同的模块中针对不同平台的要求提供了单独的封装方法,这使得代码更加分散且不易维护。
为了统一处理并简化这些差异,我们在公共组件中引入了 `EncodedString` 这一类型。`EncodedString` 类型是一个封装结构,它提供了统一的接口来处理不同编码方式的字符串。通过该类型,开发者可以不必关心底层使用的是哪种编码方式,从而使代码更加简洁和清晰。
幸运的是,为了简化升级的难度,`EncodedString` 仍可以与 `String` 类型互相转换:
```csharp
// string → EncodedString
string str = "U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=";
EncodedString estr = (EncodedString)str;
// EncodedString → string
EncodedString estr = new EncodedString("U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=", EncodingKinds.Base64);
string str = (string)estr;
```
涉及到变化的包括 `AESUtility``SHA1Utility``HMACUtility` 等工具类。
### 基础类型:`SKIT.FlurlHttpClient.Primitives.ErroredResult`
在进行数据验签等操作时,由于传入了错误的参数导致抛出异常,通常需要被视为验签失败。
在过往的版本中,我们在相应的方法内部 `try-catch` 捕获所有异常,并直接返回 `false`。然而,这种做法虽然简化了返回值的处理,但却严重限制了开发者错误调试的能力,因为它无法提供关于异常的详细信息。虽然有部分方法提供了带有 `(..., out Exception error)` 引用参数的重载,但却不能在异步方法中所使用。
为了解决这一问题,我们在公共组件中引入了 `ErroredResult` 这一类型。`ErroredResult` 类型是一个封装结构,它不仅可以在逻辑上表示操作的成功与否,而且能够携带发生的异常信息,极大地便利了异常处理和调试过程。
幸运的是,为了简化升级的难度,`ErroredResult` 仍可以与 `Boolean` 类型互相转换:
```csharp
// Boolean → ErroredResult
bool ret = true;
ErroredResult eret = (ErroredResult)ret;
// ErroredResult → Boolean
ErroredResult eret = new ErroredResult(true);
bool ret = (bool)eret;
```
涉及到变化的包括 `VerifyEventSignatureFromJson()``VerifyEventSignatureFromXml()` 等扩展方法。

View File

@@ -108,3 +108,10 @@ else
为方便开发者快速掌握本库的使用方法,这里提供一个示例项目以供参考。
请阅读[《示例项目说明》](./Sample.md)。
---
## 迁移指南
- [v3.x 迁移指南](./Migration_V3.md)

View File

@@ -19,7 +19,7 @@ bool ret = client.VerifyEventSignature(
### 调试验签错误:
由于 `VerifyEventSignature()` 方法内部会 `try-catch` 所有异常情况,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证回调通知事件签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
由于 `VerifyEventSignature()` 方法内部会 `try-catch` 捕获所有异常,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证回调通知事件签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
```csharp
ErroredResult res = client.VerifyEventSignature(authorization, signature);

View File

@@ -25,7 +25,7 @@ bool ret = client.VerifyResponseSignature(response);
### 调试验签错误:
由于 `VerifyResponseSignature()` 方法内部会 `try-catch` 所有异常情况,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证响应签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
由于 `VerifyResponseSignature()` 方法内部会 `try-catch` 捕获所有异常,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证响应签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
```csharp
ErroredResult res = client.VerifyResponseSignature(response);

View File

@@ -0,0 +1,79 @@
## v3.x 迁移指南
v3.x 版本是一个主要版本,其中包括了一些破坏性的变化。从 v2.x 升级到 v3.x 之前,请仔细阅读本文档。
---
### 目标框架和框架的变更
微软官方已与 2022 年 4 月 26 日宣布中止对 .NET Framework 4.6.1 的支持。因此,本项目的最低运行时要求调整为 .NET Framework 4.6.2。
与此同时,相关的 .NET 基础库(即通常在 `System.*``Microsoft.*` 命名空间下的内置类型)版本对齐至 .NET 8.0。
### `Flurl.Http` 的变更
本库所依赖的 `Flurl.Http` 版本已升级至 v4.0.0,并由此带来一些底层的破坏性变化。
通常情况下,开发者不需要关注这些变化,除非你正在自定义额外的 API 接口。
### 新的构造器模式
随着 `Flurl.Http` 的升级,原有的与 `IHttpClientFactory` 集成的方式发生了根本性的改变。
为了应对这种变化(请参阅本文档[《如何与 `IHttpClientFactory` 集成?》](./Advanced_IHttpClientFactory.md)),也为了日后能更加灵活地配置客户端,我们在新版本中提供了构造器模式来构造客户端:
```csharp
var options = new WechatTenpayClientOptions() { /* 具体配置项略 */ };
var client = WechatTenpayClientBuilder.Create(options).Build();
```
当然,原有的实例化方式仍然可用:
```csharp
var options = new WechatTenpayClientOptions() { /* 具体配置项略 */ };
var client = new WechatTenpayClient(options);
```
### 基础类型:`SKIT.FlurlHttpClient.Primitives.EncodedeString`
在进行加解密或哈希等操作时,参与运算的数据和最终得到的结果通常是字节数组(即 `byte[]`)形式。而在实际应用中,我们常常需要将这些字节序列转换成文本格式。我们发现即便是同一种加解密或哈希算法,在不同平台上所需要的编码方式也可能不同。比如同为 SHA256在某些接口中需要转换为十六进制HEX编码传参而在另一些接口中却需要转换为 Base64 编码传参。
在过往的版本中,我们在不同的模块中针对不同平台的要求提供了单独的封装方法,这使得代码更加分散且不易维护。
为了统一处理并简化这些差异,我们在公共组件中引入了 `EncodedString` 这一类型。`EncodedString` 类型是一个封装结构,它提供了统一的接口来处理不同编码方式的字符串。通过该类型,开发者可以不必关心底层使用的是哪种编码方式,从而使代码更加简洁和清晰。
幸运的是,为了简化升级的难度,`EncodedString` 仍可以与 `String` 类型互相转换:
```csharp
// string → EncodedString
string str = "U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=";
EncodedString estr = (EncodedString)str;
// EncodedString → string
EncodedString estr = new EncodedString("U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=", EncodingKinds.Base64);
string str = (string)estr;
```
涉及到变化的包括 `AESUtility``MD5Utility``HMACUtility` 等工具类。
### 基础类型:`SKIT.FlurlHttpClient.Primitives.ErroredResult`
在进行数据验签等操作时,由于传入了错误的参数导致抛出异常,通常需要被视为验签失败。
在过往的版本中,我们在相应的方法内部 `try-catch` 捕获所有异常,并直接返回 `false`。然而,这种做法虽然简化了返回值的处理,但却严重限制了开发者错误调试的能力,因为它无法提供关于异常的详细信息。虽然有部分方法提供了带有 `(..., out Exception error)` 引用参数的重载,但却不能在异步方法中所使用。
为了解决这一问题,我们在公共组件中引入了 `ErroredResult` 这一类型。`ErroredResult` 类型是一个封装结构,它不仅可以在逻辑上表示操作的成功与否,而且能够携带发生的异常信息,极大地便利了异常处理和调试过程。
幸运的是,为了简化升级的难度,`ErroredResult` 仍可以与 `Boolean` 类型互相转换:
```csharp
// Boolean → ErroredResult
bool ret = true;
ErroredResult eret = (ErroredResult)ret;
// ErroredResult → Boolean
ErroredResult eret = new ErroredResult(true);
bool ret = (bool)eret;
```
涉及到变化的包括 `VerifyResponseSignature()``VerifyEventSignature()` 等扩展方法。

View File

@@ -101,3 +101,9 @@ else
- [如何指定 JSON 序列化器?](./Advanced_JsonSerializer.md)
- [如何使用拦截器?](./Advanced_Interceptor.md)
---
## 迁移指南
- [v3.x 迁移指南](./Migration_V3.md)

View File

@@ -51,7 +51,7 @@ bool ret = client.VerifyEventSignature(
### 调试验签错误:
由于 `VerifyEventSignature()` 方法内部会 `try-catch` 所有异常情况,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证回调通知事件签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
由于 `VerifyEventSignature()` 方法内部会 `try-catch` 捕获所有异常,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证回调通知事件签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
```csharp
ErroredResult res = client.VerifyEventSignature(timestamp, nonce, body, signature, serialNumber);

View File

@@ -60,7 +60,7 @@ bool ret = client.VerifyResponseSignature(response);
### 调试验签错误:
由于 `VerifyResponseSignature()` 方法内部会 `try-catch` 所有异常情况,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证响应签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
由于 `VerifyResponseSignature()` 方法内部会 `try-catch` 捕获所有异常,并直接返回 `false`。为方便开发者在调试阶段排查验签的错误信息,你可以在验证响应签名时指定返回值类型为 `ErroredResult` 而非 `Boolean`,该返回值中包含了一些异常的原因和相关堆栈信息。
```csharp
ErroredResult res = client.VerifyResponseSignature(response);

View File

@@ -0,0 +1,87 @@
## v3.x 迁移指南
v3.x 版本是一个主要版本,其中包括了一些破坏性的变化。从 v2.x 升级到 v3.x 之前,请仔细阅读本文档。
---
### 目标框架和框架的变更
微软官方已与 2022 年 4 月 26 日宣布中止对 .NET Framework 4.6.1 的支持。因此,本项目的最低运行时要求调整为 .NET Framework 4.6.2。
与此同时,相关的 .NET 基础库(即通常在 `System.*``Microsoft.*` 命名空间下的内置类型)版本对齐至 .NET 8.0。
### `Flurl.Http` 的变更
本库所依赖的 `Flurl.Http` 版本已升级至 v4.0.0,并由此带来一些底层的破坏性变化。
通常情况下,开发者不需要关注这些变化,除非你正在自定义额外的 API 接口。
### 新的构造器模式
随着 `Flurl.Http` 的升级,原有的与 `IHttpClientFactory` 集成的方式发生了根本性的改变。
为了应对这种变化(请参阅本文档[《如何与 `IHttpClientFactory` 集成?》](./Advanced_IHttpClientFactory.md)),也为了日后能更加灵活地配置客户端,我们在新版本中提供了构造器模式来构造客户端:
```csharp
var options = new WechatTenpayClientOptions() { /* 具体配置项略 */ };
var client = WechatTenpayClientBuilder.Create(options).Build();
```
当然,原有的实例化方式仍然可用:
```csharp
var options = new WechatTenpayClientOptions() { /* 具体配置项略 */ };
var client = new WechatTenpayClient(options);
```
### 基础类型:`SKIT.FlurlHttpClient.Primitives.EncodedeString`
在进行加解密或哈希等操作时,参与运算的数据和最终得到的结果通常是字节数组(即 `byte[]`)形式。而在实际应用中,我们常常需要将这些字节序列转换成文本格式。我们发现即便是同一种加解密或哈希算法,在不同平台上所需要的编码方式也可能不同。比如同为 SHA256在某些接口中需要转换为十六进制HEX编码传参而在另一些接口中却需要转换为 Base64 编码传参。
在过往的版本中,我们在不同的模块中针对不同平台的要求提供了单独的封装方法,这使得代码更加分散且不易维护。
为了统一处理并简化这些差异,我们在公共组件中引入了 `EncodedString` 这一类型。`EncodedString` 类型是一个封装结构,它提供了统一的接口来处理不同编码方式的字符串。通过该类型,开发者可以不必关心底层使用的是哪种编码方式,从而使代码更加简洁和清晰。
幸运的是,为了简化升级的难度,`EncodedString` 仍可以与 `String` 类型互相转换:
```csharp
// string → EncodedString
string str = "U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=";
EncodedString estr = (EncodedString)str;
// EncodedString → string
EncodedString estr = new EncodedString("U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=", EncodingKinds.Base64);
string str = (string)estr;
```
涉及到变化的包括 `AESUtility``RSAUtility``SHA256Utility``SM2Utility``SM3Utility``SM4Utility` 等工具类。
### 基础类型:`SKIT.FlurlHttpClient.Primitives.ErroredResult`
在进行数据验签等操作时,由于传入了错误的参数导致抛出异常,通常需要被视为验签失败。
在过往的版本中,我们在相应的方法内部 `try-catch` 捕获所有异常,并直接返回 `false`。然而,这种做法虽然简化了返回值的处理,但却严重限制了开发者错误调试的能力,因为它无法提供关于异常的详细信息。虽然有部分方法提供了带有 `(..., out Exception error)` 引用参数的重载,但却不能在异步方法中所使用。
为了解决这一问题,我们在公共组件中引入了 `ErroredResult` 这一类型。`ErroredResult` 类型是一个封装结构,它不仅可以在逻辑上表示操作的成功与否,而且能够携带发生的异常信息,极大地便利了异常处理和调试过程。
幸运的是,为了简化升级的难度,`ErroredResult` 仍可以与 `Boolean` 类型互相转换:
```csharp
// Boolean → ErroredResult
bool ret = true;
ErroredResult eret = (ErroredResult)ret;
// ErroredResult → Boolean
ErroredResult eret = new ErroredResult(true);
bool ret = (bool)eret;
```
涉及到变化的包括 `VerifyResponseSignature()``VerifyEventSignature()` 等扩展方法。
### 新的平台证书管理器
原有的平台证书管理器由抽象类型 `CertificateManager` 调整为接口 `ICertificateManager`
同时,我们提供了新的 `ICertificateManagerAsync` 接口,开发者可以基于此自定义异步的密钥管理器实现。然后,你就可以调用 `VerifyResponseSignatureAsync()``VerifyEventSignatureAsync()``EncryptRequestSensitivePropertyAsync()` 等新的扩展方法,来异步地执行原本的业务流程了。
此外,我们废弃了原本的 `CertificateEntry` 的一个构造函数 `CertificateEntry(QueryCertificatesResponse.Types.Certificate model)` 重载。取而代之的是新的静态方法 `CertificateEntry.Parse(QueryCertificatesResponse.Types.Certificate model)`

View File

@@ -127,3 +127,9 @@ else
为方便开发者快速掌握本库的使用方法,这里提供一个示例项目以供参考。
请阅读[《示例项目说明》](./Sample.md)。
---
## 迁移指南
- [v3.x 迁移指南](./Migration_V3.md)

View File

@@ -0,0 +1,85 @@
## v3.x 迁移指南
v3.x 版本是一个主要版本,其中包括了一些破坏性的变化。从 v2.x 升级到 v3.x 之前,请仔细阅读本文档。
---
### 目标框架和框架的变更
微软官方已与 2022 年 4 月 26 日宣布中止对 .NET Framework 4.6.1 的支持。因此,本项目的最低运行时要求调整为 .NET Framework 4.6.2。
与此同时,相关的 .NET 基础库(即通常在 `System.*``Microsoft.*` 命名空间下的内置类型)版本对齐至 .NET 8.0。
### `Flurl.Http` 的变更
本库所依赖的 `Flurl.Http` 版本已升级至 v4.0.0,并由此带来一些底层的破坏性变化。
通常情况下,开发者不需要关注这些变化,除非你正在自定义额外的 API 接口。
### 新的构造器模式
随着 `Flurl.Http` 的升级,原有的与 `IHttpClientFactory` 集成的方式发生了根本性的改变。
为了应对这种变化(请参阅本文档[《如何与 `IHttpClientFactory` 集成?》](./Advanced_IHttpClientFactory.md)),也为了日后能更加灵活地配置客户端,我们在新版本中提供了构造器模式来构造客户端:
```csharp
var options = new WechatWorkClientOptions() { /* 具体配置项略 */ };
var client = WechatWorkClientBuilder.Create(options).Build();
```
当然,原有的实例化方式仍然可用:
```csharp
var options = new WechatWorkClientOptions() { /* 具体配置项略 */ };
var client = new WechatWorkClient(options);
```
### 基础类型:`SKIT.FlurlHttpClient.Primitives.EncodedeString`
在进行加解密或哈希等操作时,参与运算的数据和最终得到的结果通常是字节数组(即 `byte[]`)形式。而在实际应用中,我们常常需要将这些字节序列转换成文本格式。我们发现即便是同一种加解密或哈希算法,在不同平台上所需要的编码方式也可能不同。比如同为 SHA256在某些接口中需要转换为十六进制HEX编码传参而在另一些接口中却需要转换为 Base64 编码传参。
在过往的版本中,我们在不同的模块中针对不同平台的要求提供了单独的封装方法,这使得代码更加分散且不易维护。
为了统一处理并简化这些差异,我们在公共组件中引入了 `EncodedString` 这一类型。`EncodedString` 类型是一个封装结构,它提供了统一的接口来处理不同编码方式的字符串。通过该类型,开发者可以不必关心底层使用的是哪种编码方式,从而使代码更加简洁和清晰。
幸运的是,为了简化升级的难度,`EncodedString` 仍可以与 `String` 类型互相转换:
```csharp
// string → EncodedString
string str = "U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=";
EncodedString estr = (EncodedString)str;
// EncodedString → string
EncodedString estr = new EncodedString("U0tJVC5GbHVybEh0dHBDbGllbnQgaXMgQVdFU09NRSE=", EncodingKinds.Base64);
string str = (string)estr;
```
涉及到变化的包括 `AESUtility``RSAUtility``SHA1Utility` 等工具类。
### 基础类型:`SKIT.FlurlHttpClient.Primitives.ErroredResult`
在进行数据验签等操作时,由于传入了错误的参数导致抛出异常,通常需要被视为验签失败。
在过往的版本中,我们在相应的方法内部 `try-catch` 捕获所有异常,并直接返回 `false`。然而,这种做法虽然简化了返回值的处理,但却严重限制了开发者错误调试的能力,因为它无法提供关于异常的详细信息。虽然有部分方法提供了带有 `(..., out Exception error)` 引用参数的重载,但却不能在异步方法中所使用。
为了解决这一问题,我们在公共组件中引入了 `ErroredResult` 这一类型。`ErroredResult` 类型是一个封装结构,它不仅可以在逻辑上表示操作的成功与否,而且能够携带发生的异常信息,极大地便利了异常处理和调试过程。
幸运的是,为了简化升级的难度,`ErroredResult` 仍可以与 `Boolean` 类型互相转换:
```csharp
// Boolean → ErroredResult
bool ret = true;
ErroredResult eret = (ErroredResult)ret;
// ErroredResult → Boolean
ErroredResult eret = new ErroredResult(true);
bool ret = (bool)eret;
```
涉及到变化的包括 `VerifyEventSignatureForEcho()``VerifyEventSignatureFromJson()``VerifyEventSignatureFromXml()` 等扩展方法。
### 企业会话存档 SDK
原企业会话存档 SDK 客户端的命名空间发生了变化,由 `SKIT.FlurlHttpClient.Wechat.Work.SDK.Finance` 移动至 `SKIT.FlurlHttpClient.Wechat.Work.ExtendedSDK.Finance`
同时,我们提供了新的 `IEncryptionKeyManagerAsync` 接口,开发者可以基于此自定义异步的密钥管理器实现。

View File

@@ -93,3 +93,9 @@ else
- [如何指定 JSON 序列化器?](./Advanced_JsonSerializer.md)
- [如何使用拦截器?](./Advanced_Interceptor.md)
---
## 迁移指南
- [v3.x 迁移指南](./Migration_V3.md)