Skip to main content

rocketmq3-py-client

Python3 RocketMQ 3.x 客户端库,基于 JPype 桥接 RocketMQ Java 客户端。仅支持 RocketMQ 3.x 老集群;4.x 及以后请使用官方 rocketmq-client-python。

特性

  • 三种发送模式:同步、异步、单向(策略模式)
  • 两种消费模式:Pull(主动拉取)、Push(被动推送 / 观察者模式)
  • 上下文管理器:所有客户端支持 with 语句,自动释放资源
  • 重试机制:发送失败自动重试,可配置次数和退避策略
  • 线程安全:JVM 单例 + 线程锁
  • 完整异常体系:Java 异常自动翻译为 Python 异常
  • 配置驱动:通过 ClientConfig 统一管理参数
  • 消息建造者:链式 API 构建消息
  • Java 日志可控:通过环境变量配置 RocketMQ Java 客户端的日志级别与日志文件路径, 轻松抑制心跳等 INFO 日志刷屏

环境要求

  • Python 3.8 ~ 3.12(已放弃 3.13 / 3.14 支持,换取 JDK 8 兼容性)
  • JDK 8+(默认依赖 JPype1 1.5.x,官方支持 Java 8;JDK 11+ 亦可向后兼容运行)
  • JPype1 >= 1.5.0, < 1.6.0(最后支持 Java 8 的版本线;自带 macOS universal2 预编译包,含 arm64,Apple Silicon 免源码编译)
  • RocketMQ 3.2.6 JAR 包(获取方式见下方「获取 RocketMQ Java 客户端」)

💡 本库默认兼容 JDK 8:只要本机 JAVA_HOME 指向 JDK 8(或任意 8+),无需特殊处理即可启动。若需强制指定某个 JDK,仍可用 java_home:

config = ClientConfig(namesrv_addr="...", java_home="/Library/Java/JavaVirtualMachines/jdk1.8.0_xxx.jdk/Contents/Home")

⚠️ 注意:JPype1 1.6.0+ 不再支持 Java 8(要求 11+)。如切换到 1.6.0+,须将 JAVA_HOME 指向 JDK 11+,且 Python 上限为 3.12(本库已锁定 1.5.x,因此保持 JDK 8 兼容)。

获取 RocketMQ 3.2.6 Java 客户端

本库通过 JPype 桥接 RocketMQ 3.2.6 的 Java 客户端,但不自带 JAR 包,需自行准备并放到 ROCKETMQ_LIB_PATH(默认 /opt/rocketmq3/lib),运行时会自动加载该目录下所有 JAR。

⚠️ RocketMQ 3.x 使用旧的 com.alibaba.rocketmq 命名空间(不是 4.x+ 的 org.apache.rocketmq),坐标与官方新版完全不同。

Maven 坐标(Maven Central)

<dependency>
    <groupId>com.alibaba.rocketmq</groupId>
    <artifactId>rocketmq-client</artifactId>
    <version>3.2.6</version>
</dependency>

Maven 仓库地址:

  • Maven Central:https://repo1.maven.org/maven2/com/alibaba/rocketmq/rocketmq-client/3.2.6/
  • 检索页:https://mvnrepository.com/artifact/com.alibaba.rocketmq/rocketmq-client/3.2.6

已验证的完整依赖清单

以下为 RocketMQ 3.2.6 运行时所需的最小 JAR 集合(实测通过)。rocketmq-client-3.2.6.jar 本身不内含传递依赖,必须把所有 JAR 放入同一目录,客户端启动时会自动加载。

JAR 版本 说明
rocketmq-client-3.2.6.jar 3.2.6 RocketMQ 客户端核心
rocketmq-common-3.2.6.jar 3.2.6 消息模型(Message / MessageExt 等)
rocketmq-remoting-3.2.6.jar 3.2.6 网络通信层(RemotingException 等)
netty-all-4.0.25.Final.jar 4.0.25.Final 网络传输框架(remoting 依赖)
fastjson-1.2.84.jar 1.2.84 JSON 序列化(remoting 依赖)
slf4j-api-1.7.36.jar 1.7.36 日志接口
slf4j-simple-1.7.36.jar 1.7.36 日志实现(可用其他 SLF4J 实现替换)

⚠️ RocketMQ 3.2.6 发布于 2015 年,整体生态较老,仅建议在内网测试环境使用。fastjson 已升级到最新的 1.2.84 安全修复版。

直接下载

cd /opt/rocketmq3/lib  # 或 $ROCKETMQ_LIB_PATH

wget "https://repo1.maven.org/maven2/com/alibaba/rocketmq/rocketmq-client/3.2.6/rocketmq-client-3.2.6.jar"
wget "https://repo1.maven.org/maven2/com/alibaba/rocketmq/rocketmq-common/3.2.6/rocketmq-common-3.2.6.jar"
wget "https://repo1.maven.org/maven2/com/alibaba/rocketmq/rocketmq-remoting/3.2.6/rocketmq-remoting-3.2.6.jar"
wget "https://repo1.maven.org/maven2/io/netty/netty-all/4.0.25.Final/netty-all-4.0.25.Final.jar"
wget "https://repo1.maven.org/maven2/com/alibaba/fastjson/1.2.84/fastjson-1.2.84.jar"
wget "https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar"
wget "https://repo1.maven.org/maven2/org/slf4j/slf4j-simple/1.7.36/slf4j-simple-1.7.36.jar"

一键拉取全部依赖 JAR(Maven 方式)

也可以建一个临时 pom.xml,用 maven-dependency-plugin 把所有传递依赖一次性收集:

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>tmp</groupId>
  <artifactId>rmq-libs</artifactId>
  <version>1.0</version>
  <dependencies>
    <dependency>
      <groupId>com.alibaba.rocketmq</groupId>
      <artifactId>rocketmq-client</artifactId>
      <version>3.2.6</version>
    </dependency>
  </dependencies>
</project>
mvn dependency:copy-dependencies -DoutputDirectory=.
sudo cp *.jar /opt/rocketmq3/lib/   # 复制到默认加载目录

自定义 JAR 目录

若不放默认路径,用环境变量指定:

export ROCKETMQ_LIB_PATH=/path/to/your/rocketmq3/lib

RocketMQ Java 客户端日志配置

默认情况 RocketMQ Java 客户端以 INFO 级别输出心跳、Rebalance、Broker 地址变更等日志,容易刷屏干扰排查。本库支持用环境变量调整日志级别和日志文件路径。

环境变量

环境变量 说明 默认值
ROCKETMQ_CLIENT_LOG_LEVEL 日志级别:ALL/TRACE/DEBUG/INFO/WARN/ERROR/OFF 不干预(保持 RocketMQ 原生默认 INFO)
ROCKETMQ_CLIENT_LOG_PATH 日志文件绝对路径 ~/logs/rocketmqlogs/rocketmq_client.log
ROCKETMQ_CLIENT_LOG_CONSOLE 是否同时输出到控制台 true/false false(只写文件,不污染应用 stdout)
ROCKETMQ_CLIENT_LOG_CONFIGFILE 自带的 logback/log4j XML,优先级最高 无

用法

只要抑制心跳 INFO 日志:

export ROCKETMQ_CLIENT_LOG_LEVEL=WARN

同时指定日志级别与落盘路径:

export ROCKETMQ_CLIENT_LOG_LEVEL=WARN
export ROCKETMQ_CLIENT_LOG_PATH=/data/logs/myapp/rocketmq_client.log

也可以在代码里显式传入(优先级高于环境变量读取时的默认值):

from rocketmq3_py_client import ClientConfig, Producer

config = ClientConfig(
    namesrv_addr="127.0.0.1:9876",
    log_level="WARN",
    log_path="/data/logs/myapp/rocketmq_client.log",
    log_console=False,
)

with Producer("my_group", "127.0.0.1:9876", config=config) as producer:
    producer.send("topic", b"hello")

完全接管日志(自行编写 logback XML,需 ch.qos.logback 命名空间):

export ROCKETMQ_CLIENT_LOG_CONFIGFILE=/etc/myapp/my_logback.xml

⚠️ 生效前提(重要)

日志配置是 RocketMQ 的 ClientLogger 在类加载时读取 -Drocketmq.client.log.configFile 完成的,因此:

  1. 必须在创建 Producer / Consumer 之前设置。JVM 一旦启动就无法更改,同一进程以首个客户端的配置为准。

  2. classpath 中必须有日志实现 JAR,否则配置不会生效。RocketMQ 3.2.6 只依赖 slf4j-api(接口),不含 logback/log4j 实现 —— 若你的 lib_path 目录里没有这些 JAR,slf4j 走 NOP 绑定(完全静默),此时本库会在日志中给出告警:

    已设置 RocketMQ 日志配置,但 classpath 中未发现任何日志实现 JAR (logback-classic / slf4j-log4j12)
    

    解决办法是把日志实现一并放进 lib_path。在上面的一键拉取 pom.xml 中追加:

    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.0.13</version>
    </dependency>
    

    然后重新 mvn dependency:copy-dependencies。若你偏好 log4j,放入 slf4j-log4j12 + log4j 即可,本库会自动识别应使用哪种 XML 格式。

💡 本库在生成配置时会显式设置 root logger。若不设置,logback 会回退到「DEBUG + ConsoleAppender」默认行为,把日志直接打到控制台 —— 这正是很多场景日志失控的原因。

安装

pip install rocketmq3-py-client
# 或开发模式
pip install -r requirements.txt
pip install -e .

快速开始

生产者

from rocketmq3_py_client import Producer

with Producer("my_group", "127.0.0.1:9876") as producer:
    result = producer.send("topic", b'{"id": 1}', tags="tag_a", keys="key_1")
    print(result)

Push 消费者

from rocketmq3_py_client import PushConsumer

consumer = PushConsumer("cg", "127.0.0.1:9876", "topic")

@consumer.register_handler
def handle(messages):
    for msg in messages:
        print(msg.msg_id, msg.body)
    return True

consumer.start()

Pull 消费者

from rocketmq3_py_client import PullConsumer

with PullConsumer("cg", "127.0.0.1:9876") as consumer:
    queues = consumer.fetch_message_queues("topic")
    for q in queues:
        result = consumer.pull(q, offset=0, max_nums=32)
        for msg in result.messages:
            print(msg.msg_id, msg.body)

Metadata

Release files for rocketmq3-py-client 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rocketmq3-py-client 0.4.0
File Size Uploaded Provenance Actions
rocketmq3_py_client-0.4.0.tar.gz 36.8 kB With provenance Details for rocketmq3_py_client-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rocketmq3-py-client 0.4.0
File Interpreter ABI Platform Actions
rocketmq3_py_client-0.4.0-py3-none-any.whl Python 3 none any Details for rocketmq3_py_client-0.4.0-py3-none-any.whl

Total release size: 71.9 kB

Release files / rocketmq3_py_client-0.4.0.tar.gz

Download URL rocketmq3_py_client-0.4.0.tar.gz
Size 36.8 kB
Tags Source
SHA-256 checksum
How to use checksums
ce1fe2e06dfa388c161fa06026051069c24ae79dc27daee69eb245c8c6066c43
BLAKE2b-256 checksum
How to use checksums
d012c1cbb1a074e27f14280031e41ad70ab1760791aeee102e0adec5260a255a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.

Transparency log

Release files / rocketmq3_py_client-0.4.0-py3-none-any.whl

Download URL rocketmq3_py_client-0.4.0-py3-none-any.whl
Size 35.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6388bd5e8da0516339b489c026c70e3ffa15ec3f3bcf80d61bab921948d8fcb5
BLAKE2b-256 checksum
How to use checksums
3cf9bb5a20348122b973c308000e7fdd8f81d86f91bac9672937617e6fa2bdcf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.

Transparency log

Security for rocketmq3-py-client 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rocketmq3_py_client-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page