跳至主要内容

插件开发基础

本指南涵盖了 RabbitMQ 插件开发的基础知识。在阅读本指南之前,预计读者已经对 RabbitMQ 插件机制有了基本的了解。

还预计读者对 ErlangOTP 设计原则 有基本的了解。

Learn You Some Erlang 是开始学习 Erlang 和 OTP 的一个好方法。

为什么要开发插件?

编写 RabbitMQ 插件提供了一些有吸引力的可能性

  • 使您的应用程序能够访问 RabbitMQ 内部功能,这些功能未通过支持的协议之一公开。
  • 在与代理相同的 Erlang VM 中运行可能会提高某些工作负载的性能。
  • 插件可以实现否则必须由系统中的每个应用程序(服务)实现的功能,从而创建重复并增加维护负载

为什么要不开发插件

与任何插件机制一样,在开发功能时应考虑将功能嵌入为插件是否是最合适的路径。以下是一些您可能不想将功能开发为插件的原因

  • 依赖 RabbitMQ 内部 API 可能导致您的应用程序在新的 RabbitMQ 发布时(包括补丁版本)需要更改。如果您无需使用 RabbitMQ 内部功能即可完成所需操作,则您的应用程序将具有更好的向前兼容性
  • 编写不当的插件可能导致**整个节点不可用**或行为异常

入门

要开发 RabbitMQ 插件,首先请确保满足以下要求

  • 确保您已安装并可以使用 Git
  • 确保已安装并可以使用 服务器构建 指南中详细说明的依赖项

Erlang.mk 用于构建 RabbitMQ 及其插件。开始开发新插件最简单的方法可能是复制现有的插件,例如rabbitmq-metronome下面将以示例的形式使用

在开发期间激活插件

要在开发过程中测试插件,请使用以下 make 目标启动 RabbitMQ 节点,该节点使用从源代码构建并启用的本地插件。

make run-broker

插件质量提示

编写不当的插件可能会对代理的稳定性构成风险。为了确保您的插件能够安全地运行而不会影响 RabbitMQ 核心,强烈建议您遵循一些安全最佳实践。

  1. 始终为您的应用程序使用顶级 supervisor。
  2. 切勿直接启动插件应用程序,而是选择创建一个(可能非常简单的)supervisor,它将防止 Erlang VM 由于顶级应用程序崩溃而关闭。

代理和依赖项版本约束

可以使用插件应用程序环境中的 broker_version_requirements 键为插件指定代理和依赖项版本要求。这些要求被指定为每个发行版系列中最小版本的列表。请考虑以下示例

{application, my_plugin,[
%% ...
{broker_version_requirements, ["3.11.15", "3.10.22"]}
]}

上述要求 RabbitMQ 3.10.x 从 3.10.22 开始,以及 3.11.x 从 3.11.15 开始。请注意,当新的主要和次要(功能)RabbitMQ 版本发布时,**插件维护人员需要更新列表**。

插件可能具有依赖项。也可以为依赖项指定受支持的版本系列。这与上述情况非常相似,但使用了类似字典的数据结构(proplist)。

例如

{application, my_plugin, [
%% ...
{dependency_version_requirements, [{rabbitmq_management, ["3.11.0", "3.10.22"]}]}
]}

表示插件依赖于 rabbitmq_management 3.10.x 从 3.10.22 开始,以及 3.11.x 系列中的所有版本。

示例插件:Metronome

鉴于没有开发指南会在没有 Hello World 示例的情况下完整,以下内容试图提供构建您自己的 RabbitMQ 插件的基础知识。

以下示例详细说明了如何构建一个充当节拍器(metronome)的简单插件。

每秒钟,它都会发送一条消息,该消息的路由键格式为 yyyy.MM.dd.dow.hh.mm.ss,默认情况下发送到名为“metronome”的主题交换机。应用程序可以将队列附加到此交换机,并使用各种路由键以便按定期间隔调用。例如,要每秒接收一条消息,可以应用“......”的绑定。要每分钟接收一条消息,可以应用“.....*.00”的绑定。

GitHub 上的 rabbitmq-metronome 存储库包含此插件代码的副本。

下表应解释存储库中各个文件的用途。

文件名用途
Makefile

此顶级 Makefile 定义了插件的名称及其依赖项。名称必须与 Erlang 应用程序名称匹配。使用 erlang.mk 的变量声明依赖项。紧随其后,Makefile 包含rabbitmq-components.mkerlang.mk,以及rabbitmq-plugins.mk使用 erlang.mk 插件功能。有关这些文件的说明,请参见下文。

erlang.mk

的本地副本erlang.mk。这不是一个普通的副本,因为 RabbitMQ 依赖于一些修改,这些修改在撰写本文时尚未合并到上游。这就是为什么ERLANG_MK_REPOERLANG_MK_COMMIT目前被覆盖。

rabbitmq-components.mk

的本地副本rabbitmq-components.mk。原始文件位于rabbitmq-common中,您的插件将自动依赖于它。它包含其他 erlang.mk 扩展和帮助程序,必须在erlang.mk包含之前定义。此文件必须与rabbitmq-common保持最新:如果它已过期,您将收到以下错误

error: rabbitmq-components.mk must be updated!

在这种情况下,只需运行以下命令即可更新您的副本

make rabbitmq-components-mk
rabbitmq_metronome.schema

一个 Cuttlefish 配置模式。用于将 配置文件 转换为 RabbitMQ 及其运行时使用的内部格式。

Metronome 模式包含 metronome.exchange 设置的映射,设置插件使用的交换机。

启用插件时将重新生成配置。如果插件尚未启用,则配置中的插件特定值会导致错误。

有关编写模式文件的更多信息,请参阅 Cuttlefish 文档

src/rabbit_metronome.erl

Erlang“应用程序”行为的实现。提供了一种让 Erlang VM 启动和停止插件的方法。

src/rabbit_metronome_sup.erl

Erlang“supervisor”行为的实现。监视工作进程并在其崩溃时重新启动它。

src/rabbit_metronome_worker.erl

插件的核心。工作进程将在内部连接到代理,然后创建一个每秒钟触发一次的任务。

test/metronome_SUITE.erl

插件的自动化测试。

开发流程

运行 make 以构建插件

make

要启动一个节点,并在该节点上构建并启用插件

make run-broker

要确保新插件已启动并正在运行,请运行以下命令

rabbitmq-diagnostics status

如果您的插件已成功加载,您应该在已启用插件列表中看到它

# => Plugins
# =>
# => Enabled plugin file: /var/folders/gp/53t98z011678vk9rkcb_s6ph0000gn/T/rabbitmq-test-instances/rabbit@warp10/enabled_plugins
# => Enabled plugins:
# =>
# => * rabbitmq_metronome
# => * amqp_client

要运行通用测试测试套件,请使用

make tests

最后,您可以生成一个适用于分发的 .ez 文件

DIST_AS_EZS=yes make dist

该文件出现在plugins存储库根目录下的目录中。

© 2024 RabbitMQ. All rights reserved.