Skip to content

Commit 3f0225e

Browse files
zhenlei520MapleWithoutWords
zhenlei520
and
MapleWithoutWords
authored
chore: update document (#206)
* docs: Update title * document: Modified upgrade guide * docs: Update CQRS document * chore: Adjustment format * chore: Remove useless code * chore: update document * rename: Dcc -> DCC * 添加空格 * 添加空格 * 英文单词添加空格 * Update zh-CN.md * add FAQ menu to caller * Update zh-CN.md --------- Co-authored-by: LiMing <[email protected]>
1 parent cbd8363 commit 3f0225e

File tree

19 files changed

+297
-293
lines changed

19 files changed

+297
-293
lines changed

‎src/Masa.Framework.Docs/wwwroot/data/nav.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,8 @@
5959
"items": [
6060
"overview",
6161
"httpclient",
62-
"daprclient"
62+
"daprclient",
63+
"faq"
6364
]
6465
},
6566
{

‎src/Masa.Framework.Docs/wwwroot/pages/building-blocks/caller/daprclient/zh-CN.md

Lines changed: 3 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
# 服务调用 - DaprClient
2+
13
## 概念
24

35
基于 [DaprClient](https://docs.dapr.io/developing-applications/sdks/dotnet/dotnet-client/dotnet-daprclient-usage/) 实现的服务调用
@@ -642,24 +644,4 @@ MASA Framework 的服务调用提供了中间件功能，在中间件中，你
642644
return masaCallerClient;
643645
}
644646
}
645-
```
646-
647-
## 常见问题
648-
649-
* 继承`DaprCallerBase`的实现类支持从DI获取，如果你需要获取来自DI的服务，可通过构造函数注入所需服务
650-
* 继承`HttpClientCallerBase`的实现类的生命周期为: `Scoped`
651-
* 如果`自定义Caller` (继承DaprCallerBase的类)与`AddAutoRegistrationCaller`方法不在一个程序集，可能会出现自动注册自定义Caller失败的情况，可通过下面提供的任一方案解决:
652-
653-
① 指定Assembly集合 (仅对当前Caller有效)
654-
```csharp
655-
var assemblies = typeof({Replace-With-Your-CustomCaller}).Assembly;
656-
builder.Services.AddAutoRegistrationCaller(assemblies);
657-
```
658-
659-
② 设置全局Assembly集合 (影响全局Assembly默认配置，设置错误的Assembly集合会导致其它使用全局Assembly的服务出现错误)
660-
661-
```csharp
662-
var assemblies = typeof({Replace-With-Your-CustomCaller}).Assembly;
663-
MasaApp.SetAssemblies(assemblies);
664-
builder.Services.AddAutoRegistrationCaller();
665-
```
647+
```

‎src/Masa.Framework.Docs/wwwroot/pages/building-blocks/caller/faq/zh-CN.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# 服务调用 -常见问题
2+
3+
记录了使用 **服务调用** 可能遇到的问题以及问题应该如何解决
4+
5+
## 公共
6+
7+
1. 自动注册自定义 `Caller` 失败的情况？
8+
9+
检查下继承 `HttpClientCallerBase` 的类与 `AddAutoRegistrationCaller`方法是否不在一个程序集，如果是，则可能会出现可通过下面提供的任一方案解决：
10+
11+
* 指定Assembly集合 (仅对当前Caller有效)
12+
13+
```csharp
14+
var assemblies = typeof({Replace-With-Your-CustomCaller}).Assembly;
15+
builder.Services.AddAutoRegistrationCaller(assemblies);
16+
```
17+
18+
* 设置全局 Assembly 集合（影响全局 Assembly 默认配置，设置错误的 Assembly 集合会导致其它使用全局 Assembly 的服务出现错误）
19+
20+
```csharp
21+
var assemblies = typeof({Replace-With-Your-CustomCaller}).Assembly;
22+
MasaApp.SetAssemblies(assemblies);
23+
builder.Services.AddAutoRegistrationCaller();
24+
```
25+
26+
## HttpClient
27+
28+
1. 继承 `HttpClientCallerBase` 的实现类如何获取服务？
29+
30+
可通过构造函数注入所需服务
31+
32+
2. 继承 `HttpClientCallerBase` 的实现类的生命周期是什么？
33+
34+
默认声明周期为: `Scoped`，可在使用 `AddAutoRegistrationCaller` 时指定生命周期为 `Singleton`、`Transient`
35+
36+
## DaprClient
37+
38+
1. 继承 `DaprCallerBase` 的实现类如何获取服务？
39+
40+
可通过构造函数注入所需服务
41+
42+
2. 继承 `DaprCallerBase` 的实现类的生命周期是什么？
43+
44+
默认声明周期为: `Scoped`，可在使用 `AddAutoRegistrationCaller` 时指定生命周期为 `Singleton`、`Transient`

‎src/Masa.Framework.Docs/wwwroot/pages/building-blocks/caller/httpclient/zh-CN.md

Lines changed: 1 addition & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -634,24 +634,4 @@ builder.Services.AddCaller(clientBuilder =>
634634
return masaCallerClient;
635635
}
636636
}
637-
```
638-
639-
## 常见问题
640-
641-
* 继承`HttpClientCallerBase`的实现类支持从DI获取，如果你需要获取来自DI的服务，可通过构造函数注入所需服务
642-
* 继承`HttpClientCallerBase`的实现类的生命周期为: `Scoped`
643-
* 如果`自定义Caller` (继承HttpClientCallerBase的类)与`AddAutoRegistrationCaller`方法不在一个程序集，可能会出现自动注册自定义Caller失败的情况，可通过下面提供的任一方案解决:
644-
645-
① 指定Assembly集合 (仅对当前Caller有效)
646-
```csharp
647-
var assemblies = typeof({Replace-With-Your-CustomCaller}).Assembly;
648-
builder.Services.AddAutoRegistrationCaller(assemblies);
649-
```
650-
651-
② 设置全局Assembly集合 (影响全局Assembly默认配置，设置错误的Assembly集合会导致其它使用全局Assembly的服务出现错误)
652-
653-
```csharp
654-
var assemblies = typeof({Replace-With-Your-CustomCaller}).Assembly;
655-
MasaApp.SetAssemblies(assemblies);
656-
builder.Services.AddAutoRegistrationCaller();
657-
```
637+
```

‎src/Masa.Framework.Docs/wwwroot/pages/building-blocks/caller/overview/zh-CN.md

Lines changed: 22 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -9,52 +9,51 @@
99
MASA Framework 的服务调用组件提供了基于 `HttpClient` 和 `Dapr` 服务调用的能力
1010

1111
* [HttpClient](/framework/building-blocks/caller/httpclient)： 基于 [.NET Core 的 HttpClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient) 实现的服务调用
12-
* [DaprClient](/framework/building-blocks/caller/daprclient): 基于 `DaprClient` 实现的服务调用
12+
* [DaprClient](/framework/building-blocks/caller/daprclient)：基于 `DaprClient` 实现的服务调用
1313

1414
## 源码解读
1515

1616
当返回类型为
17-
* `TResponse`: `自定义返回类型`，框架自行处理异常请求
18-
* `其它类型 (非自定义返回类型)`: 根据传入参数 `autoThrowException` 的值决定是否默认处理框架异常，默认: true
17+
* `TResponse`：`自定义返回类型`，框架自行处理异常请求
18+
* `其它类型 (非自定义返回类型)`：根据传入参数 `autoThrowException` 的值决定是否默认处理框架异常，默认：true
1919

2020
框架处理异常请求机制，当请求响应的 `HttpStatusCode` 为
21-
* `299`: 上抛 `UserFriendlyException` 异常
22-
* `298`: 上抛 `ValidatorException` 异常
21+
* `299`：上抛 `UserFriendlyException` 异常
22+
* `298`：上抛 `ValidatorException` 异常
2323

2424
### ICaller
2525

2626
服务调用抽象，它提供了以下能力
2727

2828
> `autoThrowException` 为 `true` 会检查 `HttpStatus` 状态码并抛出对应的 `Exception`，部分方法的返回类型是指定类型，且没有 `autoThrowException` 参数，那么它们会自动检查 `HttpStatus` 状态码并抛出对应的 `Exception`（gRPC 请求除外）
2929
30-
* SendAsync: 提供原始的 `Send` 方法，需要自行提供`HttpRequestMessage`类型的请求信息
31-
* SendGrpcAsync: 提供基于 `gRPC` 的请求
32-
* GetStringAsync: 提供 `Get` 请求并获取返回类型为 `string` 的结果
33-
* GetByteArrayAsync: 提供 `Get` 请求并获取返回类型为 `byte[]` 的结果
34-
* GetStreamAsync: 提供 `Get` 请求并获取返回类型为 `Stream` 的结果
35-
* GetAsync: 提供 `Get` 请求并获取返回类型为 `指定类型` 的结果
36-
* PostAsync: 提供 `Post` 请求并获取返回类型为 `指定类型` 的结果
37-
* PatchAsync: 提供 `Patch` 请求并获取返回类型为 `指定类型` 的结果
38-
* PutAsync: 提供 `Put` 请求并获取返回类型为 `指定类型` 的结果
39-
* DeleteAsync: 提供 `Delete` 请求并获取返回类型为 `指定类型` 的结果
30+
* SendAsync：提供原始的 `Send` 方法，需要自行提供 `HttpRequestMessage` 类型的请求信息
31+
* SendGrpcAsync：提供基于 `gRPC` 的请求
32+
* GetStringAsync：提供 `Get` 请求并获取返回类型为 `string` 的结果
33+
* GetByteArrayAsync：提供 `Get` 请求并获取返回类型为 `byte[]` 的结果
34+
* GetStreamAsync：提供 `Get` 请求并获取返回类型为 `Stream` 的结果
35+
* GetAsync：提供 `Get` 请求并获取返回类型为 `指定类型` 的结果
36+
* PostAsync：提供 `Post` 请求并获取返回类型为 `指定类型` 的结果
37+
* PatchAsync：提供 `Patch` 请求并获取返回类型为 `指定类型` 的结果
38+
* PutAsync：提供 `Put` 请求并获取返回类型为 `指定类型` 的结果
39+
* DeleteAsync：提供 `Delete` 请求并获取返回类型为 `指定类型` 的结果
4040

4141
### ICallerFactory
4242

4343
服务调用抽象工厂，它提供了以下能力
4444

45-
* Create (): 创建name值为 `string.Empty` 的 Caller 提供者，当不存在 name 为 `string.Empty` 的提供者时，从 Caller 提供者列表中取第一个
46-
* Create (string name): 创建指定`name`的 Caller 提供者
45+
* Create：创建提供者
46+
47+
> 当不存在 `name` 为 `string.Empty` 的提供者时，从 `Caller` 提供者列表中取第一个
4748
4849
### IRequestMessage
4950

50-
请求消息抽象，提供了处理 `HttpRequestMessage` 的请求消息抽象，默认实现: [`JsonRequestMessage`](https://github.com/masastack/MASA.Framework/blob/main/src/BuildingBlocks/Service/Masa.BuildingBlocks.Service.Caller/Infrastructure/Json/JsonRequestMessage.cs)
51+
请求消息抽象，提供了处理 `HttpRequestMessage` 的请求消息抽象，默认实现：[`JsonRequestMessage`](https://github.com/masastack/MASA.Framework/blob/main/src/BuildingBlocks/Service/Masa.BuildingBlocks.Service.Caller/Infrastructure/Json/JsonRequestMessage.cs)
5152

52-
* ProcessHttpRequestMessageAsync(HttpRequestMessage requestMessage): 处理请求消息默认程序 (不支持自定义请求参数)
53-
* ProcessHttpRequestMessageAsync\<TRequest\>(HttpRequestMessage requestMessage, TRequest data): 支持自定义请求参数的处理请求消息默认程序
53+
* ProcessHttpRequestMessageAsync：处理请求消息默认程序
5454

5555
### IResponseMessage
5656

57-
响应消息抽象，提供了处理 `HttpResponseMessage` 的响应消息抽象，默认实现: [`JsonResponseMessage`](https://github.com/masastack/MASA.Framework/blob/main/src/BuildingBlocks/Service/Masa.BuildingBlocks.Service.Caller/Infrastructure/Json/JsonResponseMessage.cs)
57+
响应消息抽象，提供了处理 `HttpResponseMessage` 的响应消息抽象，默认实现：[`JsonResponseMessage`](https://github.com/masastack/MASA.Framework/blob/main/src/BuildingBlocks/Service/Masa.BuildingBlocks.Service.Caller/Infrastructure/Json/JsonResponseMessage.cs)
5858

59-
* ProcessResponseAsync\<TResponse\>(HttpResponseMessage response, CancellationToken cancellationToken = default): 针对指定响应类型的处理程序
60-
* ProcessResponseAsync(HttpResponseMessage response, CancellationToken cancellationToken = default): 针对未指定响应自定义类型的处理程序
59+
* ProcessResponseAsync：针对指定响应类型的处理程序

‎src/Masa.Framework.Docs/wwwroot/pages/building-blocks/configuration/configuration-local/zh-CN.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
## 介绍
1+
# 配置 - 本地配置
22

3-
基于 `Microsoft.Extensions.Configuration` 的基础上进行了优化，不需要手动 `Configure<xxxOptions>`。
3+
基于 `Microsoft.Extensions.Configuration` 的基础上进行了优化，不需要手动 `Configure<XXXOptions>`。
44

55
## 使用
66

@@ -74,9 +74,9 @@
7474

7575
### 选项模式
7676

77-
本地配置也是基于 .NET Core 的 `Microsoft.Extensions.Configuration` 来实现的，所以它也支持 [.NET Core的 Options 模式](https://learn.microsoft.com/zh-cn/dotnet/core/extensions/options)
77+
本地配置也是基于 `.NET Core` 的 `Microsoft.Extensions.Configuration` 来实现的，所以它也支持 [.NET Core的 Options 模式](https://learn.microsoft.com/zh-cn/dotnet/core/extensions/options)
7878

79-
> 支持选项模式后, 我们可以通过`IOptions<TModel>`、`IOptionsMonitor<TModel>`、`IOptionsSnapshot<TModel>` 获取配置信息
79+
> 支持选项模式后，我们可以通过`IOptions<TModel>`、`IOptionsMonitor<TModel>`、`IOptionsSnapshot<TModel>` 获取配置信息
8080
8181
#### 自动映射指定 Section
8282

0 commit comments

Comments
 (0)