插件开发基础
本指南涵盖了 RabbitMQ 插件开发的基础知识。在阅读本指南之前,预计读者已经对 RabbitMQ 插件机制有了基本的了解。
还预计读者对 Erlang 和 OTP 设计原则 有基本的了解。
Learn You Some Erlang 是开始学习 Erlang 和 OTP 的一个好方法。
为什么要开发插件?
编写 RabbitMQ 插件提供了一些有吸引力的可能性
- 使您的应用程序能够访问 RabbitMQ 内部功能,这些功能未通过支持的协议之一公开。
- 在与代理相同的 Erlang VM 中运行可能会提高某些工作负载的性能。
- 插件可以实现否则必须由系统中的每个应用程序(服务)实现的功能,从而创建重复并增加维护负载
为什么要不开发插件
与任何插件机制一样,在开发功能时应考虑将功能嵌入为插件是否是最合适的路径。以下是一些您可能不想将功能开发为插件的原因
- 依赖 RabbitMQ 内部 API 可能导致您的应用程序在新的 RabbitMQ 发布时(包括补丁版本)需要更改。如果您无需使用 RabbitMQ 内部功能即可完成所需操作,则您的应用程序将具有更好的向前兼容性
- 编写不当的插件可能导致**整个节点不可用**或行为异常
入门
要开发 RabbitMQ 插件,首先请确保满足以下要求
Erlang.mk 用于构建 RabbitMQ 及其插件。开始开发新插件最简单的方法可能是复制现有的插件,例如rabbitmq-metronome,下面将以示例的形式使用。
在开发期间激活插件
要在开发过程中测试插件,请使用以下 make 目标启动 RabbitMQ 节点,该节点使用从源代码构建并启用的本地插件。
make run-broker
插件质量提示
编写不当的插件可能会对代理的稳定性构成风险。为了确保您的插件能够安全地运行而不会影响 RabbitMQ 核心,强烈建议您遵循一些安全最佳实践。
- 始终为您的应用程序使用顶级 supervisor。
- 切勿直接启动插件应用程序,而是选择创建一个(可能非常简单的)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.mk和erlang.mk,以及rabbitmq-plugins.mk使用 erlang.mk 插件功能。有关这些文件的说明,请参见下文。 |
erlang.mk | 的本地副本erlang.mk。这不是一个普通的副本,因为 RabbitMQ 依赖于一些修改,这些修改在撰写本文时尚未合并到上游。这就是为什么ERLANG_MK_REPO和ERLANG_MK_COMMIT目前被覆盖。 |
rabbitmq-components.mk | 的本地副本rabbitmq-components.mk。原始文件位于rabbitmq-common中,您的插件将自动依赖于它。它包含其他 erlang.mk 扩展和帮助程序,必须在erlang.mk包含之前定义。此文件必须与rabbitmq-common保持最新:如果它已过期,您将收到以下错误
在这种情况下,只需运行以下命令即可更新您的副本
|
rabbitmq_metronome.schema | 一个 Cuttlefish 配置模式。用于将 配置文件 转换为 RabbitMQ 及其运行时使用的内部格式。 Metronome 模式包含 启用插件时将重新生成配置。如果插件尚未启用,则配置中的插件特定值会导致错误。 有关编写模式文件的更多信息,请参阅 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存储库根目录下的目录中。