Design and Implementation of a Simplified RocketMQ SDK

In 2018, as the architecture lead, I received a request to create a simple and easy‑to‑use RocketMQ SDK because native client configurations across teams were complex and risky.

After researching existing open‑source solutions, I found that the RocketMQ‑Spring project was not yet open, while Alibaba Cloud's ONS SDK was. I therefore based the design on ONS, which helped me deepen my understanding of RocketMQ client internals and led to the development of an internal SDK.

The main goal of the SDK is to reduce the mental burden for developers when using RocketMQ. Three concrete examples illustrate how the SDK simplifies common tasks.

1. Sending Ordered Messages

Using the native client requires a custom MessageQueueSelector :

SendResult sendResult = producer.send(msg, new MessageQueueSelector() {
    @Override
    public MessageQueue select(List
mqs, Message msg, Object arg) {
        Integer id = (Integer) arg;
        int index = id % mqs.size();
        return mqs.get(index);
    }
}, orderId);

The SDK reduces this to a single method call:

SendResult send(final ProducerMessage message, final String shardingKey);

Developers only need to provide the sharding key (e.g., orderId ) without writing a selector.

2. Consuming a Single Message

With the native API, a consumer registers a MessageListenerConcurrently that processes a list of messages:

consumer.registerMessageListener(new MessageListenerConcurrently() {
    @Override
    public ConsumeConcurrentlyStatus consumeMessage(List
msgs, ConsumeConcurrentlyContext context) {
        System.out.printf("%s Receive New Messages: %s %n", Thread.currentThread().getName(), msgs);
        // return consumption status
        return ConsumeConcurrentlyStatus.CONSUME_SUCCESS;
    }
});

The SDK provides a streamlined API that delivers one ConsumerMessage at a time:

consumer.subscribe("mytest", new ConsumerListener() {
    @Override
    public ConsumerAction consumer(ConsumerMessage msg) {
        byte[] body = msg.getBody();
        System.out.println("msg:" + new String(body));
        return ConsumerAction.CommitMessage;
    }
});

This makes per‑message handling much clearer.

Additionally, the SDK unifies the consumption result enums for both normal and ordered consumption:

/**
 * Consumption result
 */
public enum ConsumerAction {
    /** Consumption succeeded, continue with next message */
    CommitMessage,

    /** Consumption failed, ask broker to redeliver later */
    ReconsumeLater;
}

3. Ensuring Consistent Subscription Relationships

In real scenarios, inconsistent subscription settings (different TAGs within the same consumer group) often cause messages to be missed because the broker overwrites subscription info across instances.

The SDK enforces that all consumer instances within a group share identical topic, TAG, and listener logic, eliminating this source of errors.

4. Final Thoughts

The project is not about writing perfect code but about helping developers understand that the first step to growth is imitation and that developers should be treated as users, prioritizing their experience.

By studying Alibaba Cloud SDK designs and iteratively refining the implementation, the internal RocketMQ SDK became a practical tool for the organization.

Further learning resources include a three‑part RocketMQ series covering principles, Raft algorithm analysis, and deep dives into RocketMQ 5.x.