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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.