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
一键拉取全部依赖 JAR
建一个临时 pom.xml,用 maven-dependency-plugin 把所有传递依赖收集到 target/lib:
<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=target/lib
sudo cp target/lib/*.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.2.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.2.0.tar.gz | 25.2 kB | With provenance | Details for rocketmq3_py_client-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rocketmq3_py_client-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for rocketmq3_py_client-0.2.0-py3-none-any.whl |
Total release size: 52.1 kB
Release files / rocketmq3_py_client-0.2.0.tar.gz
| Download URL | rocketmq3_py_client-0.2.0.tar.gz |
|---|---|
| Size | 25.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99f05ee0fcab51930ed66cf84f46a06298baca22f0f35f457dcaa87b12b3fa7f
|
|
BLAKE2b-256 checksum How to use checksums |
ced75feb9a8a141690316ef1324b937551746a2ee09095619edbe1b1608be3e2
|
| 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.2.0-py3-none-any.whl
| Download URL | rocketmq3_py_client-0.2.0-py3-none-any.whl |
|---|---|
| Size | 27.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a86b104475114f8426e5cbc4854c089524fd717698d5536225c93914db7b7849
|
|
BLAKE2b-256 checksum How to use checksums |
0d33559608a8302630ab937e2358e8c021a80f004a708f1dd4eeaf52df240b08
|
| 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.2.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.2.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.