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 构建消息

环境要求

  • 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

安装

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.3.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.3.0
File Size Uploaded Provenance Actions
rocketmq3_py_client-0.3.0.tar.gz 27.9 kB With provenance Details for rocketmq3_py_client-0.3.0.tar.gz

Built distribution (wheel)

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

Total release size: 55.7 kB

Release files / rocketmq3_py_client-0.3.0.tar.gz

Download URL rocketmq3_py_client-0.3.0.tar.gz
Size 27.9 kB
Tags Source
SHA-256 checksum
How to use checksums
d5f57a0208b0e828454d9b66c9183b022938a7896fab991fff99acac3c9a7266
BLAKE2b-256 checksum
How to use checksums
d4b4e99dd9d31c1b7918f4e84e466ff57c0c8d6e11406e364db31f244fedaec4
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 Aug 8, 2026.

Transparency log

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

Download URL rocketmq3_py_client-0.3.0-py3-none-any.whl
Size 27.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7999f49421bb3bcaf271671e69758343bbae99e602cd66937baa20683c10e8fa
BLAKE2b-256 checksum
How to use checksums
2e2eb3d79992121a1ad39efa1a048b35e3e261f55b39f318e59552f9a3da5164
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 Aug 8, 2026.

Transparency log

Security for rocketmq3-py-client 0.3.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.3.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 Aug 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