From 96ee678bbd64887fc1e314918dc5c7dc8a163adf Mon Sep 17 00:00:00 2001 From: Savorboard Date: Tue, 12 Feb 2019 12:02:32 +0800 Subject: [PATCH] Normalized document --- docs/about/contact-us.md | 14 +++++++++++--- docs/about/contributing.md | 3 +++ docs/about/release-notes.md | 2 -- docs/user-guide/api-interface.md | 4 ++-- docs/user-guide/configuration.md | 16 ++++++++-------- .../{design-principle.md => design.md} | 10 +++++----- docs/user-guide/faq.md | 13 +++++++------ docs/user-guide/getting-started.md | 9 ++------- ...mentation-mechanisms.md => implementation.md} | 11 ++++++----- ...istributed-transactions.md => transaction.md} | 4 +++- mkdocs.yml | 7 ++++--- 11 files changed, 51 insertions(+), 42 deletions(-) rename docs/user-guide/{design-principle.md => design.md} (96%) rename docs/user-guide/{implementation-mechanisms.md => implementation.md} (98%) rename docs/user-guide/{distributed-transactions.md => transaction.md} (95%) diff --git a/docs/about/contact-us.md b/docs/about/contact-us.md index 25088e3..360d2ef 100644 --- a/docs/about/contact-us.md +++ b/docs/about/contact-us.md @@ -1,8 +1,16 @@ -## Contact Us +# Contact Us -* Submit an issue +## Authors + +* Author: [@yang-xiaodong](https://github.com/yang-xiaodong) * Email: yangxiaodong1214@126.com +* Blogs: https://saborboard.cnblogs.com + +## NCC Organization + +* Email: dotnetcn@outlook.com +* Twitter: https://twitter.com/ncc_community +* Weibo: https://weibo.com/dotnetcore -## CAP Team diff --git a/docs/about/contributing.md b/docs/about/contributing.md index e69de29..3a44bc9 100644 --- a/docs/about/contributing.md +++ b/docs/about/contributing.md @@ -0,0 +1,3 @@ +# Contributing + +Pull requests, issues and commentary welcome! No special process just create a request and get in touch either via gitter or create an issue. \ No newline at end of file diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md index 558236b..e793ae1 100644 --- a/docs/about/release-notes.md +++ b/docs/about/release-notes.md @@ -1,7 +1,5 @@ # Release Notes ---- - ## Version 2.4.2 (2019-01-08) **Features:** diff --git a/docs/user-guide/api-interface.md b/docs/user-guide/api-interface.md index 3cdb94c..2fe5a1b 100644 --- a/docs/user-guide/api-interface.md +++ b/docs/user-guide/api-interface.md @@ -6,7 +6,7 @@ CAP only has one interface,It is `ICapPublisher`, You can get its instance from You can use the `Publish` or `PublishAsync` methods defined in the `ICapPublisher` interface to send the event messages. -```c# +```c# hl_lines="19 33" public class PublishController : Controller { private readonly ICapPublisher _capBus; @@ -81,7 +81,7 @@ The following two blocks of code snippet demonstrate how to use transactions in #### EntityFramework ```c# - using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: false) +using (var trans = dbContext.Database.BeginTransaction(_capBus, autoCommit: false) { // Your business logic。 diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index 920e5eb..5c5a9f5 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -1,8 +1,8 @@ -## Configuration +# Configuration CAP uses Microsoft.Extensions.DependencyInjection for configuration injection. -### Cap Options +## CAP Configs You can use the following methods to configure some configuration items in the CAP, for example: @@ -27,7 +27,7 @@ CapOptions provides a callback function for `FailedCallback` to handle failed me The type of FailedCallback is `Action`. The first parameter is the message type (send or receive), the second parameter is the name of the message, and the third parameter is the content of the message. -### RabbitMQ Options +## RabbitMQ Configs The CAP uses the CapOptions extension to implement the RabbitMQ configuration function. Therefore, the configuration of the RabbitMQ is used as follows: @@ -53,7 +53,7 @@ SocketReadTimeout | RabbitMQ message read timeout | int | 30,000 milliseconds SocketWriteTimeout | RabbitMQ message write timeout | int | 30,000 milliseconds QueueMessageExpires | Automatic deletion of messages in queue | int | (10 days) ms -### Kafka Options +### Kafka Configs CAP adopts Kafka's configuration function to expand CapOptions, so the configuration usage for Kafka is as follows: @@ -71,7 +71,7 @@ services.AddCap(capOptions => { [https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md](https://github.com/edenhill/librdkafka/blob/master/CONFIGURATION.md) -### EntityFramework Options +### EntityFramework Configs If you are using Entityframework as a message persistence store, then you can customize some configuration when configuring the CAP EntityFramework configuration item. @@ -94,7 +94,7 @@ Schema | Cap table schema | string | Cap (SQL Server) Schema | Cap table schema | string | cap (PostgreSql) TableNamePrefix | Cap table name prefix | string | cap (MySql) -### SqlServer Options +### SqlServer Configs Note that if you are using EntityFramewrok, you do not use this configuration item. @@ -114,7 +114,7 @@ NAME | DESCRIPTION | TYPE | DEFAULT Schema | Cap Table Schema | string | Cap ConnectionString | Database connection string | string | null -### MySql Options +### MySql Configs Note that if you are using EntityFramewrok, you do not use this configuration item. @@ -134,7 +134,7 @@ NAME | DESCRIPTION | TYPE | DEFAULT TableNamePrefix | Cap table name prefix | string | cap ConnectionString | Database connection string | string | null -### PostgreSql Options +### PostgreSql Configs Note that if you are using EntityFramewrok, you do not use this configuration item. diff --git a/docs/user-guide/design-principle.md b/docs/user-guide/design.md similarity index 96% rename from docs/user-guide/design-principle.md rename to docs/user-guide/design.md index f19a740..08d8abe 100644 --- a/docs/user-guide/design-principle.md +++ b/docs/user-guide/design.md @@ -1,6 +1,6 @@ -## Design Principle +# Design -### Motivation +## Motivation With the popularity of microservices architecture, more and more people are trying to use microservices to architect their systems. In this we encounter problems such as distributed transactions. To solve these problems, I did not find simplicity and Easy to use solution, so I decided to create such a library to solve this problem. @@ -8,7 +8,7 @@ The original CAP was to solve the transaction problems in the distributed system Now in addition to solving distributed transaction problems, CAP's other important function is to use it as an EventBus. It has all of the features of EventBus and provides a more simplified way to handle publish/subscribe in EventBus. -### Persistence +## Persistence The CAP relies on the local database for persistence of messages. The CAP uses this method to deal with situations in which all messages are lost due to environmental or network anomalies. The reliability of messages is the cornerstone of distributed transactions, so messages cannot be lost under any circumstances. @@ -28,7 +28,7 @@ For message persistence in RabbitMQ, CAP uses a consumer queue with message pers Since Kafka is inherently designed to persist messages using files, Kafka ensures that messages are correctly persisted without loss after the message enters Kafka. -### Communication Data Streams +## Communication Data Streams The flow of messages in the CAP is roughly as follows: @@ -42,7 +42,7 @@ The flow of messages in the CAP is roughly as follows: In the 2.2 and later versions, we adjusted the flow of some messages. We removed the Queue table in the database and used the memory queue instead. For details, see: [Improve the implementation mechanism of queue mode](https://github.com/dotnetcore/CAP/issues/96) -### Consistency +## Consistency The CAP uses the ultimate consistency as a consistent solution. This solution follows the CAP theory. The following is the description of the CAP theory. diff --git a/docs/user-guide/faq.md b/docs/user-guide/faq.md index 897b34b..39a9462 100644 --- a/docs/user-guide/faq.md +++ b/docs/user-guide/faq.md @@ -1,16 +1,16 @@ -## FAQ +# FAQ -### Any IM group(e.g Tencent QQ group) to learn and chat about CAP? +## Any IM group(e.g Tencent QQ group) to learn and chat about CAP? None for that. Better than wasting much time in IM group, I hope developers could be capable of independent thinking more, and solve problems yourselves with referenced documents, even create issues or send emails when errors are remaining present. -### Does it require certain different databases, one each for productor and resumer in CAP? +## Does it require certain different databases, one each for productor and resumer in CAP? Not requird differences necessary, a given advice is that using a special database for each program. Otherwise, look at Q&A below. -### How to use the same database for different programs? +## How to use the same database for different programs? defining a prefix name of table in `ConfigureServices` method。 @@ -31,9 +31,10 @@ public void ConfigureServices(IServiceCollection services) } ``` -NOTE：different prefixed names cause SLB to no effect. +!!!NOTE + Different prefixed names cause SLB to no effect. -### If don't care about message missing, can message productor exist without any database, for the reason of sending message only. +## If don't care about message missing, can message productor exist without any database, for the reason of sending message only. Not yet. diff --git a/docs/user-guide/getting-started.md b/docs/user-guide/getting-started.md index 3915296..1775842 100644 --- a/docs/user-guide/getting-started.md +++ b/docs/user-guide/getting-started.md @@ -1,6 +1,4 @@ -# Introduction - -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. +# Getting Stared ## Usage Scenarios @@ -193,7 +191,4 @@ public void ConfigureServices(IServiceCollection services) //... }); } -``` - - - +``` \ No newline at end of file diff --git a/docs/user-guide/implementation-mechanisms.md b/docs/user-guide/implementation.md similarity index 98% rename from docs/user-guide/implementation-mechanisms.md rename to docs/user-guide/implementation.md index 8500ab3..91e4e8c 100644 --- a/docs/user-guide/implementation-mechanisms.md +++ b/docs/user-guide/implementation.md @@ -1,6 +1,7 @@ +# IMPLEMENTATION Users can get a ICapPublisher interface from the ASP.NET Core DI container to publish a message .It is initialized by configurations in the `ConfigureServices` and `configure` method in the Startup.cs file,just like the way to initialize a `MiddleWare` in ASP.NET Core. -### Message Table +## Message Table After initialized, CAP will create two tables in the client side,they are `Cap.Published` and `Cap.Received`. Please noted that different databases may deal letter case differently,if you do not explicitly specify the Schema or the TableName Prefix before project startup,the default names are the ones mentioned above. @@ -22,7 +23,7 @@ Version later than 2.2, CAP will retry after 4 minutes if the status is `Schedu >Before version 2.2,CAP retry 100 times for `Failed` messages by default. -### Message format5 +## Message format CAP use JSON to transfer message,the following is CAP's messaging object model: @@ -52,7 +53,7 @@ CallbackName | the subscriber which is used to call back | string CAP use the same algorithms as MongoDB ObjectId's distributed Id generation algorithms. -### EventBus +## EventBus EventBus adopt the publish-subscribe messaging style to communicate with different components,and there is no need to register it in component explicitly. @@ -67,7 +68,7 @@ We say that CAP implement all the features in Eventbus,EventBus has two features In CAP,send a message can be regarded as an "Event",When CAP is used in an ASP.NET Core applicaiton,the application has the ablity to publish as well as receive messages. -### Retry +## Retry Retry plays a very important role in CAP's infrastructure,CAP will retry for Failed messages.CAP has the following retry strategies: @@ -83,7 +84,7 @@ As metioned above,when the retry count comes to a certain number,CAP will not re When consumer received messages,specified method in the consumer will be executed,if exceptions are thrown during this course,CAP will retry,the retry strategy is the same as above `Retry on sending`. -### Data clean out +## Data clean out table to store messages in database has an `ExpiresAt` field to mark the expiration time of the message. CAP will set `ExpiresAt` value as **1 hour** for `Successed` messages and **15days** for `Failed` messages. diff --git a/docs/user-guide/distributed-transactions.md b/docs/user-guide/transaction.md similarity index 95% rename from docs/user-guide/distributed-transactions.md rename to docs/user-guide/transaction.md index 5750f04..c3429ae 100644 --- a/docs/user-guide/distributed-transactions.md +++ b/docs/user-guide/transaction.md @@ -1,6 +1,8 @@ +# Transaction + For the processing of distributed transactions, this CAP library matches the "Asynchronous recovery events" scenario. -### Asynchronous recovery events +## Asynchronous recovery events As known as the name "native message table", this is a classic solution, originally from EBay, and referenced links about it are at the end of this section. This is also one of the most popular solutions in the business development. diff --git a/mkdocs.yml b/mkdocs.yml index 69bc7e4..3e95bfd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,9 +15,9 @@ nav: - Getting Started: user-guide/getting-started.md - API Interface: user-guide/api-interface.md - Configuration: user-guide/configuration.md - - Design Principle: user-guide/design-principle.md - - Implementation Mechanisms: user-guide/implementation-mechanisms.md - - Distributed Transactions: user-guide/distributed-transactions.md + - Design Principle: user-guide/design.md + - Implementation Mechanisms: user-guide/implementation.md + - Distributed Transactions: user-guide/transaction.md - FAQ: user-guide/faq.md - 使用指南: - 快速开始: user-guide-cn/getting-started.md @@ -55,6 +55,7 @@ markdown_extensions: - markdown.extensions.admonition - markdown.extensions.codehilite: guess_lang: true + linenums: true - markdown.extensions.def_list - markdown.extensions.footnotes - markdown.extensions.meta