Преглед на файлове

Translate docs to english.

master
Savorboard преди 5 години
родител
ревизия
9f610d43fc
променени са 10 файла, в които са добавени 131 реда и са изтрити 109 реда
  1. +42
    -40
      docs/content/user-guide/en/cap/configuration.md
  2. +23
    -19
      docs/content/user-guide/en/cap/messaging.md
  3. +18
    -10
      docs/content/user-guide/en/cap/serialization.md
  4. +1
    -1
      docs/content/user-guide/en/getting-started/introduction.md
  5. +7
    -7
      docs/content/user-guide/en/persistent/general.md
  6. +7
    -9
      docs/content/user-guide/en/persistent/in-memory-storage.md
  7. +26
    -18
      docs/content/user-guide/en/persistent/mongodb.md
  8. +5
    -3
      docs/content/user-guide/en/persistent/mysql.md
  9. +1
    -1
      docs/content/user-guide/en/persistent/postgresql.md
  10. +1
    -1
      docs/content/user-guide/en/persistent/sqlserver.md

+ 42
- 40
docs/content/user-guide/en/cap/configuration.md Целия файл

@@ -1,95 +1,97 @@
# 配置
# Configuration

默认情况下,你在向IoC容器中注册CAP服务的时候指定配置。
By default, you can specify the configuration when you register the CAP service into the IoC container for ASP.NET Core project.

```c#
services.AddCap(config=> {
services.AddCap(config=>
{
// config.XXX
});
```

其中 `services` 代表的是 `IServiceCollection` 接口对象,它位于 `Microsoft.Extensions.DependencyInjection` 下面。
The `services` is `IServiceCollection` interface,which is under the `Microsoft.Extensions.DependencyInjection`.

如果你不想使用微软的IoC容器,那么你可以查看 [ASP.NET Core 这里的文档](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-2.2#default-service-container-replacement) 来了解如何替换默认的容器实现。
If you don't want to use Microsoft's IoC container, you can view ASP.NET Core documentation [here](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection?view=aspnetcore-2.2#default-service-container-replacement) to learn how to replace the default container implementation.

## 什么是最低配置?
## What is the minimum configuration?

最简单的回答就是,至少你要配置一个消息队列和一个事件存储,如果你想快速开始你可以使用下面的配置:
The simplest answer is that at least you have to configure a transport and a storage. If you want to get started quickly you can use the following configuration:

```C#
services.AddCap(config =>
services.AddCap(capOptions =>
{
config.UseInMemoryQueue();
config.UseInmemoryStorage();
capOptions.UseInMemoryQueue();
capOptions.UseInmemoryStorage();
});
```

有关具体的消息队列的配置和存储的配置,你可以查看 Transports 章节和 Persistent 章节中具体组件提供的配置项。
For specific transport and storage configuration, you can view the configuration items provided by the specific components in the [Transports](../transports/general.md) section and the [Persistent](../persistent/general.md) section.

## CAP 中的自定义配置
## Custom configuration

在 `AddCap` 中 `CapOptions` 对象是用来存储配置相关信息,默认情况下它们都具有一些默认值,有些时候你可能需要自定义。
The `CapOptions` is used to store configuration information. By default they have the default values, and sometimes you may need to customize them.

#### DefaultGroup

默认值:cap.queue.{程序集名称}
> Default: cap.queue.{assembly name}

默认的消费者组的名字,在不同的 Transports 中对应不同的名字,可以通过自定义此值来自定义不同 Transports 中的名字,以便于查看。
The default consumer group name, corresponding to different names in different Transports, you can customize this value to customize the names in Transports for easy viewing.

> 在 RabbitMQ 中映射到 [Queue Names](https://www.rabbitmq.com/queues.html#names)。
> 在 Apache Kafka 中映射到 Topic Name。
> 在 Azure Service Bus 中映射到 Subscription Name。
!!! info "Mapping"
Map to [Queue Names](https://www.rabbitmq.com/queues.html#names) in RabbitMQ.
Map to Topic Name in Apache Kafka.
Map to Subscription Name in Azure Service Bus.

#### Version

默认值:v1
> Default: v1

这是在CAP v2.4 版本中引入的新配置项,用于给消息指定版本来隔离不同版本服务的消息,常用于A/B测试或者多服务版本的场景。以下是其应用场景:
This is a new configuration item introduced in the CAP v2.4 version. It is used to specify a version of a message to isolate messages of different versions of the service. It is often used in A/B testing or multi-service version scenarios. The following is its application scenario:

!!! info "业务快速迭代,需要向前兼容"
由于业务的快速迭代,在各个服务集成的过程中,消息的数据结构并不是固定不变的,有些时候我们为了适应新引入的需求,会添加或者修改一些数据结构。如果你是一套全新的系统这没有什么问题,但是如果你的系统已经部署到生产环境了并且正在服务客户,这就会导致新的功能在上线的时候和旧的数据结构发生不兼容,那么这些改变可能会导致出现严重的问题,要想解决这个问题,只能把消息队列和持久化的消息全部清空,然后才能启动应用程序,这对于生产环境来说显然是致命的。
!!! info "Business Iterative and compatible"
Due to the rapid iteration of services, the data structure of the message is not fixed during each service integration process. Sometimes we add or modify certain data structures to accommodate the newly introduced requirements. If you're a brand new system, there's no problem, but if your system is deployed to a production environment and serves customers, this will cause new features to be incompatible with the old data structure when they go online, and then these changes can cause serious problems. To work around this issue, you can only clean up message queues and persistent messages before starting the application, which is obviously fatal for production environments.

!!! info "多个版本的服务端"
有些时候,App的服务端需要提供多套接口,来支持不同版本的App,这些不同版本的App相同的接口和服务端交互的数据结构可能是不一样的,所以通常情况下服务端提供不用的路由地址来适配不同版本的App调用。
!!! info "Multiple versions of the server"
Sometimes, the server's server needs to provide multiple sets of interfaces to support different versions of the app. The data structures of the same interface and server interaction of these different versions of the app may be different, so usually the server does not provide the same. Routing addresses to adapt to different versions of App calls.

!!! info "不同实例,使用相同的持久化表/集合"
希望多个不同实例的程序可以公用相同的数据库,在 2.4 之前的版本,我们可以通过指定不同的表名来隔离不同实例的数据库表,即在CAP配置的时候通过配置不同的表名前缀来实现。
!!! info "Using the same persistent table/collection in different instance"
If you want multiple different instance services to use the same database, in versions prior to 2.4, we could isolate database tables for different instances by specifying different table names. That is to say, when configuring the CAP, it is implemented by configuring different table name prefixes.

> 查看博客来了解更多关于 Version 的信息: https://www.cnblogs.com/savorboard/p/cap-2-4.html
> Check out the blog to learn more about Version feature: https://www.cnblogs.com/savorboard/p/cap-2-4.html

#### FailedRetryInterval

默认值:60 秒
> Default: 60 sec

在消息发送的时候,如果发送失败,CAP将会对消息进行重试,此配置项用来配置每次重试的间隔时间。
In the process of message message sent to transport failed, the CAP will be retry to sent. This configuration item is used to configure the interval between each retry.

在消息消费的过程中,如果消费失败,CAP将会对消息进行重试消费,此配置项用来配置每次重试的间隔时间。
In the process of message consumption failed, the CAP will retry to execute. This configuration item is used to configure the interval between each retry.

!!! WARNING "重试 & 间隔"
在默认情况下,重试将在发送和消费消息失败的 **4分钟后** 开始,这是为了避免设置消息状态延迟导致可能出现的问题。
发送和消费消息的过程中失败会立即重试 3 次,在 3 次以后将进入重试轮询,此时 FailedRetryInterval 配置才会生效。
!!! WARNING "Retry & Interval"
By default, retry will start after **4 minutes** of failure to send or consume, in order to avoid possible problems caused by setting message state delays.
Failures in the process of sending and consuming messages will be retried 3 times immediately, and will be retried polling after 3 times, at which point the FailedRetryInterval configuration will take effect.

#### FailedRetryCount

默认值:50
> Default: 50

重试的最大次数。当达到此设置值时,将不会再继续重试,通过改变此参数来设置重试的最大次数。
Maximum number of retries. When this value is reached, retry will stop and the maximum number of retries will be modified by setting this parameter.

#### FailedThresholdCallback

默认值:NULL
> Default: NULL

类型:`Action<MessageType, string, string>`
Type: `Action<MessageType, string, string>`

>
T1 : Message Type
T2 : Message Name
T3 : Message Content

重试阈值的失败回调。当重试达到 FailedRetryCount 设置的值的时候,将调用此 Action 回调,你可以通过指定此回调来接收失败达到最大的通知,以做出人工介入。例如发送邮件或者短信。
Failure threshold callback. This action is called when the retry reaches the value set by `FailedRetryCount`, and you can receive the notification by specifying this parameter to make a manual intervention. For example, send an email or notify.

#### SucceedMessageExpiredAfter

默认值:24*3600 秒(1天后)
> Default: 24*3600 sec (1 days)

成功消息的过期时间(秒)。 当消息发送或者消费成功时候,在时间达到 `SucceedMessageExpiredAfter` 秒时候将会从 Persistent 中删除,你可以通过指定此值来设置过期的时间。
The expiration time (in seconds) of the success message. When the message is sent or consumed successfully, it will be removed from persistent when the time reaches `SucceedMessageExpiredAfter` seconds. You can set the expiration time by specifying this value.

+ 23
- 19
docs/content/user-guide/en/cap/messaging.md Целия файл

@@ -1,37 +1,41 @@
# 消息
# Message

使用 `ICapPublisher` 接口发送出去的数据称之为 Message (`消息`)。
The data sent by using the `ICapPublisher` interface is called `Message`.

## 消息调度
## Scheduling

CAP 接收到消息之后会将消息发送到 Transport, 由 Transport 进行运输。
After the CAP receives the message, it sends the message to Transport, which is transported by transport.
When you send using the `ICapPublisher` interface, the CAP will dispatch the message to the corresponding Transport. Currently, bulk messaging is not supported.

当你使用 `ICapPublisher` 接口发送时,CAP将会将消息调度到相应的 Transport中去,目前还不支持批量发送消息。
For more information on transports, see the [Transports](../transports/general.md) section.

有关 Transports 的更多信息,可以查看 [Transports](../transports/general.md) 章节。
## Persistent

## 消息存储
The CAP will storage after receiving the message. For more information on storage, see the [Persistent](../persistent/general.md) section.

CAP 接收到消息之后会将消息进行 Persistent(持久化), 有关 Persistent 的更多信息,可以查看 [Persistent](../persistent/general.md) 章节。
## Retry

## 消息重试
Retrying plays an important role in the overall CAP architecture design, and CAPs retry for messages that fail to send or fail to execute. There are several retry strategies used throughout the CAP design process.

重试在整个CAP架构设计中具有重要作用,CAP 中会针对发送失败或者执行失败的消息进行重试。在整个 CAP 的设计过程中有以下几处采用的重试策略。
### Send retry

1、 发送重试
During the message sending process, when the broker crashes or the connection fails or an abnormality occurs, the CAP will retry the sending. Retry 3 times for the first time, retry every minute after 4 minutes, and +1 retries. When the total number of times reaches 50, the CAP will stop retrying.

在消息发送过程中,当出现 Broker 宕机或者连接失败的情况亦或者出现异常的情况下,这个时候 CAP 会对发送的重试,第一次重试次数为 3,4分钟后以后每分钟重试一次,进行次数 +1,当总次数达到50次后,CAP将不对其进行重试。
You can adjust the total number of default retries by setting `FailedRetryCount` in CapOptions.

你可以在 CapOptions 中设置FailedRetryCount来调整默认重试的总次数。
It will stop when the maximum number of times is reached. You can see the reason for the failure in Dashboard and choose whether to manually retry.

当失败总次数达到默认失败总次数后,就不会进行重试了,你可以在 Dashboard 中查看消息失败的原因,然后进行人工重试处理。
### Consumption retry

2、 消费重试
The consumer method is executed when the Consumer receives the message and will retry when an exception occurs. This retry strategy is the same as the send retry.

当 Consumer 接收到消息时,会执行消费者方法,在执行消费者方法出现异常时,会进行重试。这个重试策略和上面的 发送重试 是相同的。
## Data Cleanup

## 消息数据清理
There is an `ExpiresAt` field in the database message table indicating the expiration time of the message. When the message is sent successfully, the status will be changed to `Successed`, and `ExpiresAt` will be set to **1 hour** later.

数据库消息表中具有一个 ExpiresAt 字段表示消息的过期时间,当消息发送成功或者消费成功后,CAP会将消息状态为 Successed 的 ExpiresAt 设置为 1小时 后过期,会将消息状态为 Failed 的 ExpiresAt 设置为 15天 后过期。
Consuming failure will change the message status to `Failed` and `ExpiresAt` will be set to **15 days** later.

CAP 默认情况下会每隔一个小时将消息表的数据进行清理删除,避免数据量过多导致性能的降低。清理规则为 ExpiresAt 不为空并且小于当前时间的数据。 也就是说状态为Failed的消息(正常情况他们已经被重试了 50 次),如果你15天没有人工介入处理,同样会被清理掉。
By default, the data of the message table is deleted **every hour** to avoid performance degradation caused by too much data. The cleanup strategy is `ExpiresAt` is not empty and is less than the current time.

That is to say, the message with the status Failed (normally they have been retried 50 times), if you do not have manual intervention for 15 days, it will **also be** cleaned up.

+ 18
- 10
docs/content/user-guide/en/cap/serialization.md Целия файл

@@ -1,12 +1,12 @@
# 序列化
# Serialization

CAP 目前还不支持消息本身的序列化,在将消息发送到消息队列之前 CAP 使用 json 对消息对象进行序列化。
CAP does not currently support serialization for transport messages, and CAP uses json to serialize message objects before sending them to the transport.

## 内容序列化
## Content Serialization

CAP 支持对消息的 Content 字段进行序列化,你可以自定义 `IContentSerializer` 接口来做到这一点。
The CAP supports serializing the Message's Content field, which you can do by customizing the `IContentSerializer` interface.

目前由于消息对象需要进行数据库存储,所以只支持 string 的序列化和反序例化。
Currently, since the message object needs to be stored in the database, only the serialization and reverse ordering of `string` are supported.

```csharp

@@ -26,13 +26,21 @@ class MyContentSerializer : IContentSerializer
}
```

## 消息适配器
Configure the custom `MyContentSerializer` to the service.

在异构系统中,有时候需要和其他系统进行通讯,但是其他系统使用的消息对象可能和 CAP 的[**包装器对象**](../persistent/general.md#_7)不一样,这个时候就需要对消息进行自定义适配。
```csharp

services.AddCap(x =>{ }).AddContentSerializer<MyContentSerializer>();

```

## Message Adapter

In heterogeneous systems, sometimes you need to communicate with other systems, but other systems use message objects that may be different from CAP's [**Wrapper Object**](../persistent/general.md#_7). This time maybe you need to customize the message wapper.

CAP 提供了 `IMessagePacker` 接口用于对 [**包装器对象**](../persistent/general.md#_7) 进行自定义,自定义的 MessagePacker 通常是将 `CapMessage` 进行打包和解包操作,在这个过程中可以添加自己的业务对象。
The CAP provides the `IMessagePacker` interface for customizing the [**Wrapper Object**](../persistent/general.md#_7). The custom MessagePacker usually packs and unpacks the `CapMessage` In this process you can add your own business objects.

使用方法:
Usage :

```csharp

@@ -72,7 +80,7 @@ class MyMessagePacker : IMessagePacker
}
```

接下来,配置自定义的 `MyMessagePacker` 到服务中。
Next, configure the custom `MyMessagePacker` to the service.

```csharp



+ 1
- 1
docs/content/user-guide/en/getting-started/introduction.md Целия файл

@@ -2,7 +2,7 @@

CAP is an EventBus and a solution for solving distributed transaction problems in microservices or SOA systems. It helps create a microservices system that is scalable, reliable, and easy to change.

In Microsoft's [eShopOnContainer] (https://github.com/dotnet-architecture/eShopOnContainers) microservices sample project, it is recommended to use CAP as the EventBus available in the production environment.
In Microsoft's [eShopOnContainer](https://github.com/dotnet-architecture/eShopOnContainers) microservices sample project, it is recommended to use CAP as the EventBus available in the production environment.


!!! question "What is EventBus?"


+ 7
- 7
docs/content/user-guide/en/persistent/general.md Целия файл

@@ -1,16 +1,16 @@
# 基本
# General

CAP 需要使用具有持久化功能的存储介质来存储事件消息,例如通过数据库或者其他NoSql设施。CAP 使用这种方式来应对一切环境或者网络异常导致消息丢失的情况,消息的可靠性是分布式事务的基石,所以在任何情况下消息都不能丢失。

## 持久化
## Persistent

### 发送前
### Before sent

在消息进入到消息队列之前,CAP使用本地数据库表对消息进行持久化,这样可以保证当消息队列出现异常或者网络错误时候消息是没有丢失的。

为了保证这种机制的可靠性,CAP使用和业务代码相同的数据库事务来保证业务操作和CAP的消息在持久化的过程中是强一致的。也就是说在进行消息持久化的过程中,任何一方发生异常情况数据库都会进行回滚操作。

### 发送后
### After sent

消息进入到消息队列之后,CAP会启动消息队列的持久化功能,我们需要说明一下在 RabbitMQ 和 Kafka 中CAP的消息是如何持久化的。

@@ -18,11 +18,11 @@ CAP 需要使用具有持久化功能的存储介质来存储事件消息,例

由于 Kafka 天生设计的就是使用文件进行的消息持久化,在所以在消息进入到Kafka之后,Kafka会保证消息能够正确被持久化而不丢失。

## 消息存储
## Storage

在 CAP 启动后,会向持久化介质中生成两个表,默认情况下名称为:`Cap.Published` `Cap.Received`。

### 存储格式
### Storage Data Structure

**Published** 表结构:

@@ -51,7 +51,7 @@ ExpiresAt | Expire time | DateTime
Retries | Retry times | int
StatusName | Status Name | string

### 包装器对象
### Wapper Object

CAP 在进行消息发送到时候,会对原始消息对象进行一个二次包装存储到 `Content` 字段中,以下为包装 Content 的 Message 对象数据结构:



+ 7
- 9
docs/content/user-guide/en/persistent/in-memory-storage.md Целия файл

@@ -1,16 +1,16 @@
# In-Memory Storage

内存消息的持久化存储常用于开发和测试环境,如果使用基于内存的存储则你会失去本地事务消息可靠性保证。
Persistent storage of memory messages is often used in development and test environments, and if you use memory-based storage you lose the reliability of local transaction messages.

## 配置
## Configuration

如果要使用内存存储,你需要从 NuGet 安装以下扩展包:
To use in-memory storage, you need to install the following extensions from NuGet:

```
```ps
Install-Package DotNetCore.CAP.InMemoryStorage
```

然后,你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。
Next, add configuration items to the `ConfigureServices` method of `Startup.cs`.

```csharp

@@ -27,10 +27,8 @@ public void ConfigureServices(IServiceCollection services)

```

内存中的发送成功消息,CAP 将会每 5分钟 进行一次清理。

The successful message in memory, the CAP will be cleaned **every 5 minutes**.

## Publish with transaction

In-Memory 存储 **不支持** 事务方式发送消息。

In-Memory Storage **Not supported** Transaction mode to send messages.

+ 26
- 18
docs/content/user-guide/en/persistent/mongodb.md Целия файл

@@ -1,22 +1,24 @@
# MongoDB

MongoDB 是一个跨平台的面向文档型的数据库程序,它被归为 NOSQL 数据库,CAP 从 2.3 版本开始支持 MongoDB 作为消息存储。
MongoDB is a cross-platform document-oriented database program. Classified as a NoSQL database program, MongoDB uses JSON-like documents with schema.

MongoDB 从 4.0 版本开始支持 ACID 事务,所以 CAP 也只支持 4.0 以上的 MongoDB,并且 MongoDB 需要部署为集群,因为 MongoDB 的 ACID 事务需要集群才可以使用。
CAP has supported MongoDB as persistent since version 2.3 .

有关开发环境如何快速搭建 MongoDB 4.0+ 集群,你可以我的参考 [这篇文章](https://www.cnblogs.com/savorboard/p/mongodb-4-cluster-install.html)。
MongoDB supports ACID transactions since version 4.0, so CAP only supports MongoDB above 4.0, and MongoDB needs to be deployed as a cluster, because MongoDB's ACID transaction requires a cluster to be used.

## 配置
For a quick development of the MongoDB 4.0+ cluster for the development environment, you can refer to [this article](https://www.cnblogs.com/savorboard/p/mongodb-4-cluster-install.html).

要使用 MongoDB 存储,你需要从 NuGet 安装以下扩展包:
## Configuration

```shell
To use MongoDB storage, you need to install the following extensions from NuGet:

```ps

Install-Package DotNetCore.CAP.MongoDB

```

然后,你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。
Next, add configuration items to the `ConfigureServices` method of `Startup.cs`.

```csharp

@@ -35,29 +37,35 @@ public void ConfigureServices(IServiceCollection services)

```

#### MongoDBOptions
#### MongoDB Options

NAME | DESCRIPTION | TYPE | DEFAULT
:---|:---|---|:---
DatabaseName | 数据库名称 | string | cap
DatabaseConnection | 数据库连接字符串 | string | mongodb://localhost:27017
ReceivedCollection | 接收消息集合名称 | string | cap.received
PublishedCollection | 发送消息集合名称 | string | cap.published
DatabaseName | Database name | string | cap
DatabaseConnection | Database connection string | string | mongodb://localhost:27017
ReceivedCollection | Database received message collection name | string | cap.received
PublishedCollection | Database published message collection name | string | cap.published

## Publish with transaction

下面的示例展示了如何利用 CAP 和 MongoDB 进行本地事务集成。
The following example shows how to leverage CAP and MongoDB for local transaction integration.

```csharp

//NOTE: before your test, your need to create database and collection at first
//注意:MongoDB 不能在事务中创建数据库和集合,所以你需要单独创建它们,模拟一条记录插入则会自动创建
//var mycollection = _client.GetDatabase("test").GetCollection<BsonDocument>("test.collection");
//mycollection.InsertOne(new BsonDocument { { "test", "test" } });
//NOTE: Before your test, your need to create database and collection at first.
// Mongo can't create databases and collections in transactions automatic,
// so you need to create them separately, simulating a record insert
// will automatically create.

// var mycollection = _client.GetDatabase("test")
// .GetCollection<BsonDocument>("test.collection");
// mycollection.InsertOne(new BsonDocument { { "test", "test" } });

using (var session = _client.StartTransaction(_capBus, autoCommit: false))
{
var collection = _client.GetDatabase("test").GetCollection<BsonDocument>("test.collection");
var collection = _client.GetDatabase("test")
.GetCollection<BsonDocument>("test.collection");

collection.InsertOne(session, new BsonDocument { { "hello", "world" } });

_capBus.Publish("sample.rabbitmq.mongodb", DateTime.Now);


+ 5
- 3
docs/content/user-guide/en/persistent/mysql.md Целия файл

@@ -2,15 +2,17 @@

MySQL 是一个开源的关系型数据库,你可以使用 MySQL 来作为 CAP 消息的持久化。

## 配置
## Configuration

要使用 MySQL 存储,你需要从 NuGet 安装以下扩展包:

```shell
```ps

Install-Package DotNetCore.CAP.MySql

```

然后,你可以在 `Startup.cs` 的 `ConfigureServices` 方法中添加基于内存的配置项。
Next, add configuration items to the `ConfigureServices` method of `Startup.cs`.

```csharp



+ 1
- 1
docs/content/user-guide/en/persistent/postgresql.md Целия файл

@@ -2,7 +2,7 @@

PostgreSQL 是一个开源的关系型数据库,它已经变得越来越流行,你可以使用 Postgre SQL 来作为 CAP 消息的持久化。

## 配置
## Configuration

要使用 PostgreSQL 存储,你需要从 NuGet 安装以下扩展包:



+ 1
- 1
docs/content/user-guide/en/persistent/sqlserver.md Целия файл

@@ -2,7 +2,7 @@

SQL Server 是由微软开发的一个关系型数据库,你可以使用 SQL Server 来作为 CAP 消息的持久化。

## 配置
## Configuration

要使用 SQL Server 存储,你需要从 NuGet 安装以下扩展包:



Зареждане…
Отказ
Запис