8000 add docs to master by yang-xiaodong · Pull Request #284 · dotnetcore/CAP · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

add docs to master #284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 64 commits into from
Feb 10, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
64 commits
Select commit Hold shift + click to select a range
4d626b9
update version to 2.4.0
yang-xiaodong Oct 29, 2018
c0a6c07
Add version options to config file.
yang-xiaodong Oct 30, 2018
c57625a
update resource
yang-xiaodong Oct 31, 2018
5f5f10a
add message version support for dashboard
yang-xiaodong Oct 31, 2018
da03d36
add message version support for dashboard
yang-xiaodong Oct 31, 2018
7fd361b
Support using version to isolate messages. #220
yang-xiaodong Nov 5, 2018
d3c16b9
update mongo unit tests
yang-xiaodong Nov 6, 2018
3e854a2
update unit tests
yang-xiaodong Nov 6, 2018
40a8aa7
update unit tests
yang-xiaodong Nov 6, 2018
d452206
Set default versions for consumer groups
yang-xiaodong Nov 8, 2018
f98247a
solve the problem of issue#181 (#237)
zjlhope Nov 13, 2018
9e66e62
Issue#235 (#238)
zjlhope Nov 16, 2018
5f3a9fe
refactor
yang-xiaodong Nov 19, 2018
4fccad4
Fix the message persistence bug. #240
yang-xiaodong Nov 19, 2018
545cfd3
using new CamelCaseNamingStrategy
yang-xiaodong Dec 5, 2018
1d982e2
update packages to .net core 2.2
yang-xiaodong Dec 5, 2018
d848c0e
update test framework to netcoreapp2.2
yang-xiaodong Dec 5, 2018
5dd4177
Update .travis.yml
yang-xiaodong Dec 8, 2018
9130fbe
update TargetFramework
yang-xiaodong Dec 8, 2018
a285889
Exclude build samples project
yang-xiaodong Dec 8, 2018
28ba8e1
update version to 2.4.1
yang-xiaodong Dec 8, 2018
7e07cc3
add samples project to sln for build
yang-xiaodong Dec 15, 2018
5d9a44f
Merge branch 'master' of github.com:dotnetcore/CAP into develop
yang-xiaodong Dec 19, 2018
16ba019
update version to 2.4.2
yang-xiaodong Dec 19, 2018
2c3ff53
Fixed PostgreSql version isolation feature bug. (#256)
yang-xiaodong Dec 21, 2018
8a2ab1f
Fixed spelling errors
yang-xiaodong Dec 21, 2018
b19fe5d
modify cap publish Message to rabbitmq slow (#261)
moyuanhui Dec 29, 2018
3e36cd4
Startup the CAP with the BackgroundService. #265
yang-xiaodong Jan 3, 2019
78473ba
update samples
yang-xiaodong Jan 3, 2019
8fb084e
Merge branch 'develop' of github.com:dotnetcore/CAP into develop
yang-xiaodong Jan 3, 2019
cfb9cf5
Fixed SQL query bug. #266
yang-xiaodong Jan 4, 2019
cee0a5d
update travis ci config
yang-xiaodong Jan 4, 2019
51f1151
update travis ci config
yang-xiaodong Jan 4, 2019
10c7f18
adjust dashboard table column width
yang-xiaodong Jan 4, 2019
18a5e16
adjust the consumer execution time to milliseconds
yang-xiaodong Jan 4, 2019
6858dfd
add mkdocs.yml
yang-xiaodong Jan 7, 2019
786492e
Merge branch 'master' into develop
yang-xiaodong Jan 8, 2019
4f9e1eb
update version to 2.4.3
yang-xiaodong Jan 8, 2019
18160b5
add about.md docs
yang-xiaodong Jan 9, 2019
5f60941
add index.md docs
yang-xiaodong Jan 10, 2019
c01484c
add docs
yang-xiaodong Jan 11, 2019
fb8fa07
add docs
yang-xiaodong Jan 12, 2019
ba1f8e0
add docs
yang-xiaodong Jan 13, 2019
af504f7
add docs
yang-xiaodong Jan 15, 2019
93fa301
add docs
yang-xiaodong Jan 16, 2019
25e033e
add docs
yang-xiaodong Jan 17, 2019
cd911b1
add docs
yang-xiaodong Jan 18, 2019
e4ea125
add docs
yang-xiaodong Jan 19, 2019
754719a
add docs
yang-xiaodong Jan 20, 2019
8148acc
add docs
yang-xiaodong Jan 21, 2019
fbfd513
add docs
yang-xiaodong Jan 22, 2019
db594d3
Fix resource files
yang-xiaodong Jan 25, 2019
9434b83
update ignore
yang-xiaodong Jan 6, 2019
816f635
add docs
yang-xiaodong Jan 26, 2019
c644f78
add docs
yang-xiaodong Jan 27, 2019
db68442
add docs
yang-xiaodong Jan 29, 2019
569e344
Create readme.md
yang-xiaodong Feb 1, 2019
c7a0854
add markdown extensions supports
yang-xiaodong Feb 2, 2019
16589eb
update about.md
yang-xiaodong Feb 2, 2019
8000
12570c2
add CNAME fiel
yang-xiaodong Feb 2, 2019
5a60c71
add img
yang-xiaodong Feb 2, 2019
db8db5d
update docs
yang-xiaodong Feb 2, 2019
c000a96
Update README.zh-cn.md
yang-xiaodong Feb 2, 2019
64e233c
Merge branch 'master' into develop
yang-xiaodong Feb 10, 2019
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,4 @@ Properties
/NuGet.config
.vscode/*
samples/Sample.RabbitMQ.MongoDB/appsettings.Development.json
site/
2 changes: 1 addition & 1 deletion README.zh-cn.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

CAP 是一个基于 .NET Standard 的 C# 库,它是一种处理分布式事务的解决方案,同样具有 EventBus 的功能,它具有轻量级、易使用、高性能等特点。

你可以在这里[CAP Wiki](https://github.com/dotnetcore/CAP/wiki)看到更多详细资料。
你可以在这里[CAP docs](http://docs.dotnet-china.org/CAP/)看到更多详细资料。

你可以在这里看到[CAP 视频教程](https://www.cnblogs.com/savorboard/p/cap-video-1.html),学习如何在项目中集成CAP。

Expand Down
2 changes: 1 addition & 1 deletion build/version.props
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<PropertyGroup>
<VersionMajor>2</VersionMajor>
<VersionMinor>4</VersionMinor>
<VersionPatch>2</VersionPatch>
<VersionPatch>3</VersionPatch>
<VersionQuality></VersionQuality>
<VersionPrefix>$(VersionMajor).$(VersionMinor).$(VersionPatch)</VersionPrefix>
</PropertyGroup>
Expand Down
1 change: 1 addition & 0 deletions docs/CNAME
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
cap.dotnet-china.com
5 changes: 5 additions & 0 deletions docs/about.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@

## Contact Us

* Submit an issue
* Email: yangxiaodong1214@126.com
Binary file added docs/img/architecture.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
29 changes: 29 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# CAP

CAP is a library based on .Net standard, which is a solution to deal with distributed transactions, also has the function of EventBus, it is lightweight, easy to use, and efficiently.

## Introduction

In the process of building an SOA or MicroService system, we usually need to use the event to integrate each services. In the process, the simple use of message queue does not guarantee the reliability. CAP is adopted the local message table program integrated with the current database to solve the exception may occur in the process of the distributed system calling each other. It can ensure that the event messages are not lost in any case.

You can also use the CAP as an EventBus. The CAP provides a simpler way to implement event publishing and subscriptions. You do not need to inherit or implement any interface during the process of subscription and sending.

This is a diagram of the CAP working in the ASP.NET Core MicroService architecture:

![cap.png](img/architecture.png)

!!! note
CAP implements the Outbox Pattern described in the [eShop ebook](https://docs.microsoft.com/en-us/dotnet/standard/microservices-architecture/multi-container-microservice-net-applications/subscribe-events#designing-atomicity-and-resiliency-when-publishing-to-the-event-bus).

## Contributing

One of the easiest ways to contribute is to participate in discussions and discuss issues. You can also contribute by submitting pull requests with code changes.

If you have any question or problems, please report them on the CAP repository:

<a href="https://github.com/dotnetcore/cap/issues/new"><button class="btn btn-primary btn-lg" type="submit"><i class="fab fa-github fa-2x"></i> Report Issue</button></a>
<a href="https://github.com/dotnetcore/cap/issues"><button class="btn btn-primary btn-lg" type="submit"> Active Issues <i class="fab fa-github fa-2x"></i></button></a>

## License

CAP is licensed under the [MIT license](https://github.com/dotnetcore/CAP/blob/master/LICENSE.txt).
8 changes: 8 additions & 0 deletions docs/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# CAP documentation

The folder contains the documentation for CAP.

We are using [Github Pages](https://github.com/yang-xiaodong/cap-docs) to host the documentation and the rendered version
can be found [here](http://cap.dotnet-china.com).

Doc pages are authored in Markdown - you can find a primer [here](https://help.gamejolt.com/markdown).
233 changes: 233 additions & 0 deletions docs/user-guide-cn/api-interface.md
10000
Original file line number Diff line number Diff line change
@@ -0,0 +1,233 @@
CAP 的 API 接口只有一个,就是 `ICapPublisher` 接口,你可以从 DI 容器中获取到该接口的实例进行调用。

### 发布/发送

你可以使用 `ICapPublisher` 接口中的 `Publish<T>` 或者 `PublishAsync<T>` 方法来发送消息:

```cs
public class PublishController : Controller
{
private readonly ICapPublisher _capBus;

public PublishController(ICapPublisher capPublisher)
{
_capBus = capPublisher;
}

//不使用事务
[Route("~/without/transaction")]
public IActionResult WithoutTransaction()
{
_capBus.Publish("xxx.services.show.time", DateTime.Now);

return Ok();
}

//Ado.Net 中使用事务,自动提交
[Route("~/adonet/transaction")]
public IActionResult AdonetWithTransaction()
{
using (var connection = new MySqlConnection(ConnectionString))
{
using (var transaction = connection.BeginTransaction(_capBus, autoCommit: true))
{
//业务代码

_capBus.Publish("xxx.services.show.time", DateTime.Now);
}
}
return Ok();
}

//EntityFramework 中使用事务,自动提交
[Route("~/ef/transaction")]
public IActionResult EntityFrameworkWithTransaction([FromServices]AppDbContext dbContext)
{
using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: true))
{
//业务代码

_capBus.Publish("xxx.services.show.time", DateTime.Now);
}
return Ok();
}
}

```

下面是PublishAsync这个接口的签名:

**`PublishAsync<T>(string name,T object)`**

默认情况下,在调用此方法的时候 CAP 将在内部创建事务,然后将消息写入到 `Cap.Published` 这个消息表。

#### 消息补偿

有时候当发送一条消息出去之后,希望有一个回调可以获得消费方法的通知,用来补偿发送方做的业务操作,那么可以使用下面这个重载。

**`PublishAsync<T>(string name,T object, string callBackName)`**

这个重载中 `callbackName` 是一个回调的订阅方法名称,当消费端处理完成消息之后CAP会把消费者的处理结果返回并且调用指定的订阅方法。

> 在一些需要业务补偿的场景中,我们可以利用此特性进行一些还原的补偿操作。例如:电商系统中的付款操作,订单在进行支付调用支付服务的过程中如果发生异常,那么支付服务可以通过返回一个结果来告诉调用方此次业务失败,调用方将支付状态标记为失败。 调用方通过订阅 `callbackName`(订阅参数为消费方方法的返回值) 即可接收到支付服务消费者方法的返回结果,从而进行补偿的业务处理。

下面是使用方法:

```C#

// 发送方
_capBus.Publish("xxx.services.show.time",DaateTime.Now,"callback-show-execute-time");

[CapSubscribe("callback-show-execute-time")] //对应发送的 callbackName
public void ShowPublishTimeAndReturnExecuteTime(DateTime time)
{
Console.WriteLine(time); // 这是订阅方返回的时间
}

//--------------------------------------------------------------------------------

//订阅方
[CapSubscribe("xxx.services.show.time")]
public DateTime ShowPublishTimeAndReturnExecuteTime(DateTime time)
{
Console.WriteLine(time); // 这是发送的时间

return DateTime.Now; // 这是消费者返回的时间,CAP会取该方法的返回值用来传递到发送方的回调订阅里面
}

```

#### 事务

事务在 CAP 具有重要作用,它是保证消息可靠性的一个基石。 在发送一条消息到消息队列的过程中,如果不使用事务,我们是没有办法保证我们的业务代码在执行成功后消息已经成功的发送到了消息队列,或者是消息成功的发送到了消息队列,但是业务代码确执行失败。

这里的失败原因可能是多种多样的,比如连接异常,网络故障等等。

*只有业务代码和CAP的Publish代码必须在同一个事务中,才能够保证业务代码和消息代码同时成功或者失败。*

以下是两种使用事务进行Publish的代码:

* EntityFramework

```cs
using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: false)
{
//业务代码

_capBus.Publish("xxx.services.show.time", DateTime.Now);

trans.Commit();
}
```

在不使用自动提交的时候,你的业务代码可以位于 Publish 之前或者之后,只需要保证在同一个事务。

当使用自动提交时候,需要确保 `_capBus.Publish` 位于代码的最后。

其中,发送的内容会序列化为Json存储到消息表中。

* Dapper

```cs
using (var connection = new MySqlConnection(ConnectionString))
{
using (var transaction = connection.BeginTransaction(_capBus, autoCommit: false))
{
//your business code
connection.Execute("insert into test(name) values('test')", transaction: (IDbTransaction)transaction.DbTransaction);

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

transaction.Commit();
}
}
```

### 订阅/消费

**注意:框架无法做到100%确保消息只执行一次,所以在一些关键场景消息端在方法实现的过程中自己保证幂等性。**

使用 `CapSubscribeAttribute` 来订阅 CAP 发布出去的消息。

```
[CapSubscribe("xxx.services.bar")]
public void BarMessageProcessor()
{

}

```

这里,你也可以使用多个 `CapSubscribe[""]` 来同时订阅多个不同的消息 :

```
[CapSubscribe("xxx.services.bar")]
[CapSubscribe("xxx.services.foo")]
public void BarAndFooMessageProcessor()
{

}

```

其中,`xxx.services.bar` 为订阅的消息名称,内部实现上,这个名称在不同的消息队列具有不同的代表。 在 Kafka 中,这个名称即为 Topic Name。 在RabbitMQ 中,为 RouteKey。

> RabbitMQ 中的 RouteKey 支持绑定键表达式写法,有两种主要的绑定键:
>
> \*(星号)可以代替一个单词.
>
> \# (井号) 可以代替0个或多个单词.
>
> 比如在下面这个图中(P为发送者,X为RabbitMQ中的Exchange,C为消费者,Q为队列)
>
> ![](http://images2017.cnblogs.com/blog/250417/201708/250417-20170807093230268-283915002.png)
>
> 在这个示例中,我们将发送一条关于动物描述的消息,也就是说 Name(routeKey) 字段中的内容包含 3 个单词。第一个单词是描述速度的(celerity),第二个单词是描述颜色的(colour),第三个是描述哪种动物的(species),它们组合起来类似:“<celerity>.<colour>.<species>”。
>
> 然后在使用 `CapSubscribe` 绑定的时候,Q1绑定为 `CapSubscribe["*.orange.*"]`, Q2 绑定为 `CapSubscribe["*.*.rabbit"]` 和 `[CapSubscribe["lazy.#]`。
>
> 那么,当发送一个名为 "quick.orange.rabbit" 消息的时候,这两个队列将会同时收到该消息。同样名为 `lazy.orange.elephant`的消息也会被同时收到。另外,名为 "quick.orange.fox" 的消息将仅会被发送到Q1队列,名为 "lazy.brown.fox" 的消息仅会被发送到Q2。"lazy.pink.rabbit" 仅会被发送到Q2一次,即使它被绑定了2次。"quick.brown.fox" 没有匹配到任何绑定的队列,所以它将会被丢弃。
>
> 另外一种情况,如果你违反约定,比如使用 4个单词进行组合,例如 "quick.orange.male.rabbit",那么它将匹配不到任何的队列,消息将会被丢弃。
>
> 但是,假如你的消息名为 "lazy.orange.male.rabbit",那么他们将会被发送到Q2,因为 #(井号)可以匹配 0 或者多个单词。


在 CAP 中,我们把每一个拥有 `CapSubscribe[]`标记的方法叫做**订阅者**,你可以把订阅者进行分组。

**组(Group)**,是订阅者的一个集合,每一组可以有一个或者多个消费者,但是一个订阅者只能属于某一个组。同一个组内的订阅者订阅的消息只能被消费一次。

如果你在订阅的时候没有指定组,CAP会将订阅者设置到一个默认的组,默认的组名称为 `cap.queue.{程序集名称}`。

以下是使用组进行订阅的示例:

```cs
[CapSubscribe("xxx.services.foo", Group = "moduleA")]
public void FooMessageProcessor()
{

}

```

#### 例外情况

这里有几种情况可能需要知道:

**① 消息发布的时候订阅方还未启动**

Kafka:

当 Kafka 中,发布的消息存储于持久化的日志文件中,所以消息不会丢失,当订阅者所在的程序启动的时候会消费掉这些消息。

RabbitMQ:

在 RabbitMQ 中,应用程序**首次启动**会创建具有持久化的 Exchange 和 Queue,CAP 会针对每一个订阅者Group会新建一个消费者队列,**由于首次启动时候订阅者未启动的所以是没有队列的,消息无法进行持久化,这个时候生产者发的消息会丢失**。

针对RabbitMQ的消息丢失的问题,有两种解决方式:

i. 部署应用程序之前,在RabbitMQ中手动创建具有durable特性的Exchange和Queue,默认情况他们的名字分别是(cap.default.topic, cap.default.group)。

ii. 提前运行一遍所有实例,让Exchange和Queue初始化。

我们建议采用第 ii 种方案,因为很容易做到。
Loading
0