《RabbitMQ Tutorial》译文 第 1 章 简介

原文来自 RabbitMQ 英文官网的教程（1.Introduction），其示例代码采用了 .NET C# 语言。

RabbitMQ is a message broker: it accepts and forwards messages. You can think about it as a post office: when you put the mail that you want posting in a post box, you can be sure that Mr. Postman will eventually deliver the mail to your recipient. In this analogy, RabbitMQ is a post box, a post office and a postman.

RabbitMQ 是这样一个消息代理：它接收和转发消息。你能够把它想像成是一个邮局：当你把一份邮件投递到信箱时，你能够确信的是邮递员先生终究会把邮件递送给接收者。在这个比喻中，RabbitMQ 扮演了信箱、邮局以及邮递员这一系列角色。

The major difference between RabbitMQ and the post office is that it doesn't deal with paper, instead it accepts, stores and forwards binary blobs of data ‒ messages.

RabbitMQ与邮局最大的不一样在于它并不处理纸质信件，取而代之的是它接收、储存以及转发二进制消息数据。

RabbitMQ, and messaging in general, uses some jargon.

RabbitMQ 以及消息传递，一般会使用到一些专业术语。

Producing means nothing more than sending. A program that sends messages is a producer :

生产者的含义无非就是发送，一个程序在发送消息时它就是生产者：

A queue is the name for a post box which lives inside RabbitMQ. Although messages flow through RabbitMQ and your applications, they can only be stored inside a queue. A queue is only bound by the host's memory & disk limits, it's essentially a large message buffer. Many producers can send messages that go to one queue, and many consumers can try to receive data from one queue. This is how we represent a queue:

队列实质上就是 RabbitMQ 内部的“信箱”，做为消息，尽管自 RabbitMQ 流经应用程序，但它最终只会存储于队列中。队列只会受限于主机内存和磁盘空间，本质上来说它实际上是一个庞大的消息缓存区。多个生产者能够发送消息到同一个队列，同时多个消费者也能够从同一个队列接收数据。下图是咱们描绘的一个队列的模样：

Consuming has a similar meaning to receiving. A consumer is a program that mostly waits to receive messages:

同理，消费也有着相似接收的含义，消费者就是一个主要用来等待接收消息的程序：

Note that the producer, consumer, and broker do not have to reside on the same host; indeed in most applications they don't.

要注意的是，生产者、消费者，以及代理之间没必要存在于同一台主机，事实上大部分应用程序也不会这么作。

"Hello World"

"起步"

In this part of the tutorial we'll write two programs in C#; a producer that sends a single message, and a consumer that receives messages and prints them out. We'll gloss over some of the detail in the .NET client API, concentrating on this very simple thing just to get started. It's a "Hello World" of messaging.

在教程的当前部分咱们会编写两个 C# 程序。做为生产者会发送一条消息，同时消费者会接收消息并将其打印出来。咱们会忽略 API 当中的一些细节，把精力集中在简单的事情上从而更好的起步。这是一个“Hello World”的消息。

In the diagram below, "P" is our producer and "C" is our consumer. The box in the middle is a queue - a message buffer that RabbitMQ keeps on behalf of the consumer.

在下图中，"P" 就是生产者，"C"就是消费者。中间的方形盒子就是队列，即 RabbitMQ 为消费者保留的消息缓冲区。

The .NET client library

.NET 客户端库

RabbitMQ speaks multiple protocols. This tutorial uses AMQP 0-9-1, which is an open, general-purpose protocol for messaging. There are a number of clients for RabbitMQ in many different languages. We'll use the .NET client provided by RabbitMQ.

RabbitMQ 支持多种协议，本教程使用的是 AMQP 0-9-1，它是公开的较为通用的消息协议。RabbitMQ 支持多种语言的客户端，在这里咱们将使用 RabbitMQ 提供的 .NET 客户端。

The client supports .NET Core as well as .NET Framework 4.5.1+. This tutorial will use RabbitMQ .NET client 5.0 and .NET Core so you will ensure you have it installed and in your PATH.

RabbitMQ 提供的 .NET 客户端已支持 .NET Core 以及 .NET Framework 4.5.1+，本教程将会使用 RabbitMQ .NET client 5.0 和 .NET Core，因此你须要确认已安装成功。

You can also use the .NET Framework to complete this tutorial however the setup steps will be different.

你也能够使用 NET Framework 来完成本教程，然而其安装步骤会有所不一样。

RabbitMQ .NET client 5.0 and later versions are distributed via nuget.

RabbitMQ .NET client 5.0 以及最新的版本是经由 Nuget 来发布的。

This tutorial assumes you are using powershell on Windows. On MacOS and Linux nearly any shell will work.

本教程假定你在 Windows 操做系统中会使用 PowerShell，能够放心的是，在 MacOS 和 Linux 中几乎全部的 Shell 环境都能正常运行。

Setup

安装

First lets verify that you have .NET Core toolchain in PATH:

首先让咱们验证一下本地环境变量 PATH 中的 .NET Core 工具链:

dotnet --help

should produce a help message.

这时应当产生一个帮助消息。

Now let's generate two projects, one for the publisher and one for the consumer:

如今让咱们来建立两个项目，一个是发布者，一个是消费者。

dotnet new console --name Send
mv Send/Program.cs Send/Send.cs
dotnet new console --name Receive
mv Receive/Program.cs Receive/Receive.cs

This will create two new directories named Send and Receive.

这一步将会建立两个文件夹，一个叫 Send，一个叫 Receive。

Then we add the client dependency.

紧接着咱们来添加客户端依赖。

cd Send
dotnet add package RabbitMQ.Client
dotnet restore
cd ../Receive
dotnet add package RabbitMQ.Client
dotnet restore

Now we have the .NET project set up we can write some code.

好了，如今咱们完成了 .NET 项目的安装，这样就能够写一些代码了。

Sending

发送

We'll call our message publisher (sender) Send.cs and our message consumer (receiver) Receive.cs. The publisher will connect to RabbitMQ, send a single message, then exit.

随后咱们会调用消息发布者（发送）Send.cs，以及消息消费者（接收）Receive.cs。发布者会链接 RabbitMQ，并发送一条消息，而后退出。

In Send.cs, we need to use some namespaces:

在 Send.cs 中，咱们须要引入一些命名空间：

using System;
using RabbitMQ.Client;
using System.Text;

Set up the class:

创建类文件：

class Send
{
    public static void Main()
    {
        ...
    }
}

then we can create a connection to the server:

而后咱们就能够建立一个通往服务器的链接。

class Send
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using (var connection = factory.CreateConnection())
        {
            using (var channel = connection.CreateModel())
            {
                ...
            }
        }
    }
}

The connection abstracts the socket connection, and takes care of protocol version negotiation and authentication and so on for us. Here we connect to a broker on the local machine - hence the localhost. If we wanted to connect to a broker on a different machine we'd simply specify its name or IP address here.

该链接是抽象自套接字链接，为咱们处理协议关于版本在协商与认证等方面的事宜。在这里，咱们会链接到本地机器的一个代理，也就是 localhost。若是咱们想链接到一台不一样机器上的代理，只需简单地指定主机名或者 IP 地址。

Next we create a channel, which is where most of the API for getting things done resides.

接下来咱们将建立一个信道，它在众多的 API 中负责着事项的正确处理。

To send, we must declare a queue for us to send to; then we can publish a message to the queue:

为了能顺利的发送，咱们须要先定义一个队列，而后咱们就能够发布消息了。

using System;
using RabbitMQ.Client;
using System.Text;

class Send
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using(var connection = factory.CreateConnection())
        using(var channel = connection.CreateModel())
        {
            channel.QueueDeclare(queue: "hello",
                                 durable: false,
                                 exclusive: false,
                                 autoDelete: false,
                                 arguments: null);

            string message = "Hello World!";
            var body = Encoding.UTF8.GetBytes(message);

            channel.BasicPublish(exchange: "",
                                 routingKey: "hello",
                                 basicProperties: null,
                                 body: body);
            Console.WriteLine(" [x] Sent {0}", message);
        }

        Console.WriteLine(" Press [enter] to exit.");
        Console.ReadLine();
    }
}

Declaring a queue is idempotent - it will only be created if it doesn't exist already. The message content is a byte array, so you can encode whatever you like there.

声明队列的行为是幂等性的 - 即只有当一个队列不存在时才能被建立。

When the code above finishes running, the channel and the connection will be disposed.

当上述代码完成时，信道和链接将会被释放。

Here's the whole Send.cs class.

这里是完整的 Send.cs 类文件。

Sending doesn't work!

发送运行失败

If this is your first time using RabbitMQ and you don't see the "Sent" message then you may be left scratching your head wondering what could be wrong. Maybe the broker was started without enough free disk space (by default it needs at least 50 MB free) and is therefore refusing to accept messages. Check the broker logfile to confirm and reduce the limit if necessary. The configuration file documentation will show you how to set disk_free_limit.

若是这是你第一次使用 RabbitMQ，而且你没有收到“Sent”这一消息，这时你可能会抓耳挠腮，想知道是什么致使了错误。在这种状况下，有很大多是由于代理（broker）在启动时没有足够的可用磁盘空间（默认至少须要 50M ），所以拒绝接收消息。检查代理（broker）日志文件（logfile），并进行确认以减小限制，经过查看配置文件文档，能够知晓如何设置 disk_free_limit。

Receiving

接收

That's it for our publisher. Our consumer is pushed messages from RabbitMQ, so unlike the publisher which publishes a single message, we'll keep it running to listen for messages and print them out.

以上是咱们的发布者。咱们的消费者已开始从 RabbitMQ 上被推送了消息，与发送一条消息的发布者有所不一样的是，咱们会让消费者持续地监听消息并将其打印出来。

The code (in Receive.cs) has almost the same using statements as Send:

在 Receive.cs 类文件中，using 区域的声明代码与 Send.cs 类文件近乎相同：

using RabbitMQ.Client;
using RabbitMQ.Client.Events;
using System;
using System.Text;

Setting up is the same as the publisher; we open a connection and a channel, and declare the queue from which we're going to consume. Note this matches up with the queue that send publishes to.

与发布者的设置同样，咱们打开一个链接和信道，而且声明好队列以做好消费的准备。须要注意的是，该队列与发布者所发送消息的队列是相匹配的（即基于同一个队列）。

class Receive
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using (var connection = factory.CreateConnection())
        {
            using (var channel = connection.CreateModel())
            {
                channel.QueueDeclare(queue: "hello",
                                     durable: false,
                                     exclusive: false,
                                     autoDelete: false,
                                     arguments: null);
                ...
            }
        }
    }
}

Note that we declare the queue here, as well. Because we might start the consumer before the publisher, we want to make sure the queue exists before we try to consume messages from it.

能够看到咱们在消费者这里又声明了一次队列（QueueDeclare），在实践中，咱们极可能是先启动消费者，后启动发布者。因此重复的声明代码，是当咱们尝试从队列中消费消息时，确保队列老是已存在的。

We're about to tell the server to deliver us the messages from the queue. Since it will push us messages asynchronously, we provide a callback. That is what EventingBasicConsumer.Received event handler does.

咱们即将告知服务器从队列中向咱们递送消息，由于该动做是基于异步的，因此咱们须要提供回调，这即是 EventingBasicConsumer.Received 事件处理方法所要作的。

using RabbitMQ.Client;
using RabbitMQ.Client.Events;
using System;
using System.Text;

class Receive
{
    public static void Main()
    {
        var factory = new ConnectionFactory() { HostName = "localhost" };
        using(var connection = factory.CreateConnection())
        using(var channel = connection.CreateModel())
        {
            channel.QueueDeclare(queue: "hello",
                                 durable: false,
                                 exclusive: false,
                                 autoDelete: false,
                                 arguments: null);

            var consumer = new EventingBasicConsumer(channel);
            consumer.Received += (model, ea) =>
            {
                var body = ea.Body;
                var message = Encoding.UTF8.GetString(body);
                Console.WriteLine(" [x] Received {0}", message);
            };
            channel.BasicConsume(queue: "hello",
                                 autoAck: true,
                                 consumer: consumer);

            Console.WriteLine(" Press [enter] to exit.");
            Console.ReadLine();
        }
    }
}

Here's the whole Receive.cs class.

这里是完整的 Receive.cs 类文件

Putting It All Together

融合一块儿

Open two terminals.

打开两个终端。

Run the consumer:

运行消费者：

cd Receive
dotnet run

Then run the producer:

紧接着运行生产者：

cd Send
dotnet run

The consumer will print the message it gets from the publisher via RabbitMQ. The consumer will keep running, waiting for messages (Use Ctrl-C to stop it), so try running the publisher from another terminal.

消费者会经由 RabbitMQ 打印出那些来自发布者的消息。消费者会持续运行，以等待消息（使用 Ctrl-C 来终止运行），如此，咱们能够尝试从其余终端来运行发布者（重复运行多个生产者实例程序）。