diff --git a/docs/en/Distributed-Event-Bus-Kafka-Integration.md b/docs/en/Distributed-Event-Bus-Kafka-Integration.md new file mode 100644 index 0000000000..e4796adf55 --- /dev/null +++ b/docs/en/Distributed-Event-Bus-Kafka-Integration.md @@ -0,0 +1,167 @@ +# Distributed Event Bus Kafka Integration + +> This document explains **how to configure the [Kafka](https://kafka.apache.org/)** as the distributed event bus provider. See the [distributed event bus document](Distributed-Event-Bus.md) to learn how to use the distributed event bus system + +## Installation + +Use the ABP CLI to add [Volo.Abp.EventBus.Kafka](https://www.nuget.org/packages/Volo.Abp.EventBus.Kafka) NuGet package to your project: + +* Install the [ABP CLI](https://docs.abp.io/en/abp/latest/CLI) if you haven't installed before. +* Open a command line (terminal) in the directory of the `.csproj` file you want to add the `Volo.Abp.EventBus.Kafka` package. +* Run `abp add-package Volo.Abp.EventBus.Kafka` command. + +If you want to do it manually, install the [Volo.Abp.EventBus.Kafka](https://www.nuget.org/packages/Volo.Abp.EventBus.Kafka) NuGet package to your project and add `[DependsOn(typeof(AbpEventBusKafkaModule))]` to the [ABP module](Module-Development-Basics.md) class inside your project. + +## Configuration + +You can configure using the standard [configuration system](Configuration.md), like using the `appsettings.json` file, or using the [options](Options.md) classes. + +### `appsettings.json` file configuration + +This is the simplest way to configure the Kafka settings. It is also very strong since you can use any other configuration source (like environment variables) that is [supported by the AspNet Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/). + +**Example: The minimal configuration to connect to a local kafka server with default configurations** + +````json +{ + "Kafka": { + "Connections": { + "Default": { + "BootstrapServers": "localhost:9092" + } + }, + "EventBus": { + "GroupId": "MyGroupId", + "TopicName": "MyTopicName" + } + } +} +```` + +* `MyGroupId` is the name of this application, which is used as the **GroupId** on the Kakfa. +* `MyTopicName` is the **topic name**. + +See [the Kafka document](https://docs.confluent.io/current/clients/confluent-kafka-dotnet/api/Confluent.Kafka.html) to understand these options better. + +#### Connections + +If you need to connect to another server than the localhost, you need to configure the connection properties. + +**Example: Specify the host name (as an IP address)** + +````json +{ + "Kafka": { + "Connections": { + "Default": { + "BootstrapServers": "123.123.123.123:9092" + } + }, + "EventBus": { + "GroupId": "MyGroupId", + "TopicName": "MyTopicName" + } + } +} +```` + +Defining multiple connections is allowed. In this case, you can specify the connection that is used for the event bus. + +**Example: Declare two connections and use one of them for the event bus** + +````json +{ + "Kafka": { + "Connections": { + "Default": { + "BootstrapServers": "123.123.123.123:9092" + }, + "SecondConnection": { + "BootstrapServers": "321.321.321.321:9092" + } + }, + "EventBus": { + "GroupId": "MyGroupId", + "TopicName": "MyTopicName", + "ConnectionName": "SecondConnection" + } + } +} +```` + +This allows you to use multiple RabbitMQ server in your application, but select one of them for the event bus. + +You can use any of the [ClientConfig](https://docs.confluent.io/current/clients/confluent-kafka-dotnet/api/Confluent.Kafka.ClientConfig.html) properties as the connection properties. + +**Example: Specify the socket timeout** + +````json +{ + "Kafka": { + "Connections": { + "Default": { + "BootstrapServers": "123.123.123.123:9092", + "SocketTimeoutMs": 60000 + } + } + } +} +```` + +### The Options Classes + +`AbpRabbitMqOptions` and `AbpRabbitMqEventBusOptions` classes can be used to configure the connection strings and event bus options for the RabbitMQ. + +You can configure this options inside the `ConfigureServices` of your [module](Module-Development-Basics.md). + +**Example: Configure the connection** + +````csharp +Configure(options => +{ + options.Connections.Default.BootstrapServers = "123.123.123.123:9092"; + options.Connections.Default.SaslUsername = "user"; + options.Connections.Default.SaslPassword = "pwd"; +}); +```` + +**Example: Configure the consumer config** + +````csharp +Configure(options => +{ + options.ConfigureConsumer = config => + { + config.GroupId = "MyGroupId"; + config.EnableAutoCommit = false; + }; +}); +```` + +**Example: Configure the producer config** + +````csharp +Configure(options => +{ + options.ConfigureProducer = config => + { + config.MessageTimeoutMs = 6000; + config.Acks = Acks.All; + }; +}); +```` + +**Example: Configure the topic specification** + +````csharp +Configure(options => +{ + options.ConfigureTopic = specification => + { + specification.ReplicationFactor = 3; + specification.NumPartitions = 3; + }; +}); +```` + +Using these options classes can be combined with the `appsettings.json` way. Configuring an option property in the code overrides the value in the configuration file. \ No newline at end of file diff --git a/docs/en/Distributed-Event-Bus.md b/docs/en/Distributed-Event-Bus.md index bd85613011..b1444d8eba 100644 --- a/docs/en/Distributed-Event-Bus.md +++ b/docs/en/Distributed-Event-Bus.md @@ -8,6 +8,7 @@ Distributed event bus system provides an **abstraction** that can be implemented * `LocalDistributedEventBus` is the default implementation that implements the distributed event bus to work as in-process. Yes! The **default implementation works just like the [local event bus](Local-Event-Bus.md)**, if you don't configure a real distributed provider. * `RabbitMqDistributedEventBus` implements the distributed event bus with the [RabbitMQ](https://www.rabbitmq.com/). See the [RabbitMQ integration document](Distributed-Event-Bus-RabbitMQ-Integration.md) to learn how to configure it. +* `KafkaDistributedEventBus` implements the distributed event bus with the [RabbitMQ](https://kafka.apache.org/). See the [Kafka integration document](Distributed-Event-Bus-Kafka-Integration.md) to learn how to configure it. Using a local event bus as default has a few important advantages. The most important one is that: It allows you to write your code compatible to distributed architecture. You can write a monolithic application now that can be split into microservices later. It is a good practice to communicate between bounded contexts (or between application modules) via distributed events instead of local events. diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 411cced68d..4c7703ff70 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -198,6 +198,10 @@ { "text": "RabbitMQ Integration", "path": "Distributed-Event-Bus-RabbitMQ-Integration.md" + }, + { + "text": "Kafka Integration", + "path": "Distributed-Event-Bus-Kafka-Integration.md" } ] } diff --git a/docs/zh-Hans/Distributed-Event-Bus-Kafka-Integration.md b/docs/zh-Hans/Distributed-Event-Bus-Kafka-Integration.md new file mode 100644 index 0000000000..f621a95fae --- /dev/null +++ b/docs/zh-Hans/Distributed-Event-Bus-Kafka-Integration.md @@ -0,0 +1,163 @@ +# 分布式事件总线Kafka集成 + +> 本文解释了**如何配置[Kafka](https://kafka.apache.org/)**做为分布式总线提供程序. 参阅[分布式事件总线文档](Distributed-Event-Bus.md)了解如何使用分布式事件总线系统. + +## 安装 + +使用ABP CLI添加[Volo.Abp.EventBus.Kafka[Volo.Abp.EventBus.Kafka](https://www.nuget.org/packages/Volo.Abp.EventBus.Kafka)NuGet包到你的项目: + +* 安装[ABP CLI](https://docs.abp.io/en/abp/latest/CLI),如果你还没有安装. +* 在你想要安装 `Volo.Abp.EventBus.Kafka` 包的 `.csproj` 文件目录打开命令行(终端). +* 运行 `abp add-package Volo.Abp.EventBus.Kafka` 命令. + +如果你想要手动安装,安装[Volo.Abp.EventBus.Kafka](https://www.nuget.org/packages/Volo.Abp.EventBus.Kafka) NuGet 包到你的项目然后添加 `[DependsOn(typeof(AbpEventBusKafkaModule))]` 到你的项目[模块](Module-Development-Basics.md)类. + +## 配置 + +可以使用配置使用标准的[配置系统](Configuration.md),如 `appsettings.json` 文件,或[选项](Options.md)类. + +### `appsettings.json` 文件配置 + +这是配置Kafka设置最简单的方法. 它也非常强大,因为你可以使用[由AspNet Core支持的](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/)的任何其他配置源(如环境变量). + +**示例:最小化配置与默认配置连接到本地的Kafka服务器** + + +````json +{ + "Kafka": { + "EventBus": { + "GroupId": "MyGroupId", + "TopicName": "MyTopicName" + } + } +} +```` + +* `MyGroupId` 是应用程序的名称,用于Kafka的**GroupId**. +* `MyTopicName` 是**topic名称**. + +参阅[Kafka文档](https://docs.confluent.io/current/clients/confluent-kafka-dotnet/api/Confluent.Kafka.html)更好的了解这些选项. + +#### 连接 + +如果需要连接到本地主机以外的另一台服务器,需要配置连接属性. + +**示例: 指定主机名 (如IP地址)** + +````json +{ + "Kafka": { + "Connections": { + "Default": { + "BootstrapServers": "123.123.123.123:9092" + } + }, + "EventBus": { + "GroupId": "MyGroupId", + "TopicName": "MyTopicName" + } + } +} +```` + +允许定义多个连接. 在这种情况下,你可以指定用于事件总线的连接. + +**示例: 声明两个连接并将其中一个用于事件总线** + +````json +{ + "Kafka": { + "Connections": { + "Default": { + "BootstrapServers": "123.123.123.123:9092" + }, + "SecondConnection": { + "BootstrapServers": "321.321.321.321:9092" + } + }, + "EventBus": { + "GroupId": "MyGroupId", + "TopicName": "MyTopicName", + "ConnectionName": "SecondConnection" + } + } +} +```` + +这允许你可以在你的应用程序使用多个Kafka服务器,但将其中一个做为事件总线. + +你可以使用任何[ClientConfig](https://docs.confluent.io/current/clients/confluent-kafka-dotnet/api/Confluent.Kafka.ClientConfig.html)属性作为连接属性. + +**示例: 指定socket超时时间** + +````json +{ + "Kafka": { + "Connections": { + "Default": { + "BootstrapServers": "123.123.123.123:9092", + "SocketTimeoutMs": 60000 + } + } + } +} +```` + +### 选项类 + +`AbpKafkaOptions` 和 `AbpKafkaEventBusOptions` 类用于配置Kafka的连接字符串和事件总线选项. + +你可以在你的[模块](Module-Development-Basics.md)的 `ConfigureServices` 方法配置选项. + +**示例: 配置连接** + +````csharp +Configure(options => +{ + options.Connections.Default.BootstrapServers = "123.123.123.123:9092"; + options.Connections.Default.SaslUsername = "user"; + options.Connections.Default.SaslPassword = "pwd"; +}); +```` + +**示例: 配置 consumer config** + +````csharp +Configure(options => +{ + options.ConfigureConsumer = config => + { + config.GroupId = "MyGroupId"; + config.EnableAutoCommit = false; + }; +}); +```` + +**示例: 配置 producer config** + +````csharp +Configure(options => +{ + options.ConfigureProducer = config => + { + config.MessageTimeoutMs = 6000; + config.Acks = Acks.All; + }; +}); +```` + +**示例: 配置 topic specification** + +````csharp +Configure(options => +{ + options.ConfigureTopic = specification => + { + specification.ReplicationFactor = 3; + specification.NumPartitions = 3; + }; +}); +```` + +使用这些选项类可以与 `appsettings.json` 组合在一起. 在代码中配置选项属性会覆盖配置文件中的值. \ No newline at end of file diff --git a/docs/zh-Hans/Distributed-Event-Bus.md b/docs/zh-Hans/Distributed-Event-Bus.md index 8416ef953d..68b7466f8a 100644 --- a/docs/zh-Hans/Distributed-Event-Bus.md +++ b/docs/zh-Hans/Distributed-Event-Bus.md @@ -8,6 +8,7 @@ * `LocalDistributedEventBus` 是默认实现,实现作为进程内工作的分布式事件总线. 是的!如果没有配置真正的分布式提供程序,**默认实现的工作方式与[本地事件总线](Local-Event-Bus.md)一样**. * `RabbitMqDistributedEventBus` 通过[RabbitMQ](https://www.rabbitmq.com/)实现分布式事件总线. 请参阅[RabbitMQ集成文档](Distributed-Event-Bus-RabbitMQ-Integration.md)了解如何配置它. +* `KafkaDistributedEventBus` 通过[Kafka](https://kafka.apache.org/)实现分布式事件总线. 请参阅[Kafka集成文档](Distributed-Event-Bus-Kafka-Integration.md)了解如何配置它. 使用本地事件总线作为默认具有一些重要的优点. 最重要的是:它允许你编写与分布式体系结构兼容的代码. 您现在可以编写一个整体应用程序,以后可以拆分成微服务. 最好通过分布式事件而不是本地事件在边界上下文之间(或在应用程序模块之间)进行通信. diff --git a/docs/zh-Hans/docs-nav.json b/docs/zh-Hans/docs-nav.json index 26a526dd10..df72d6e3df 100644 --- a/docs/zh-Hans/docs-nav.json +++ b/docs/zh-Hans/docs-nav.json @@ -180,6 +180,10 @@ { "text": "RabbitMQ 集成", "path": "Distributed-Event-Bus-RabbitMQ-Integration.md" + }, + { + "text": "Kafka 集成", + "path": "Distributed-Event-Bus-Kafka-Integration.md" } ] }