文档中心

消息队列 RocketMQ版

最佳实践

RocketMQ 5.x LiteTopic 使用最佳实践

本文介绍 RocketMQ 5.x LiteTopic 的适用场景、使用限制和接入方法，帮助您基于 Lite 类型父 Topic 动态管理轻量级子 Topic，并完成消息发送与消费。

功能概述

LiteTopic 用于在一个预先创建的父 Topic 下，按业务标识动态划分大量轻量级子 Topic。您需要先创建一个 Lite 类型的父 Topic，LiteTopic 子项由生产消息动态产生。

生产者发送消息时携带 LiteTopic 名称，服务端据此将消息投递到对应的 LiteTopic。

消费者绑定父 Topic 后，可动态订阅或取消订阅其中的 LiteTopic。

适用场景

海量业务维度：租户、设备、订单或任务等业务维度数量大，并且需要独立消费。

动态数量变化：子 Topic 数量变化频繁，不适合逐一提前创建普通 Topic。

灵活订阅管理：希望在同一个父 Topic 下动态增删消费目标。

配额说明

说明

如下配额仅供参考，实际数量请以控制台显示为准。相关参数说明如下：

LiteTopic 数量上限：实例内实际可产生的 LiteTopic 总量上限。Lite 类型父 Topic 本身不计入该数量。

LiteTopic 订阅数上限：实例内 LiteTopic 动态订阅资源总量上限。此外，客户端还会接收服务端下发的单客户端订阅约束。

实例版本	实例规格	LiteTopic 数量上限	LiteTopic 订阅数上限
基础版	rocketmq.b2.2k	150000	150000
		rocketmq.b2.4k	250000	250000
		rocketmq.b2.6k	300000	300000
专业版	rocketmq.x2.2k	150000	150000
		rocketmq.x2.5k	300000	300000
		rocketmq.x2.10k	600000	600000
		rocketmq.x2.20k	840000	840000
		rocketmq.x2.30k	1020000	1020000
		rocketmq.x2.40k	1200000	1200000
		rocketmq.x2.50k	1380000	1380000
		rocketmq.x2.60k	1500000	1500000
		rocketmq.x2.70k	1560000	1560000
		rocketmq.x2.80k	1680000	1680000
		rocketmq.x2.90k	1800000	1800000
		rocketmq.x2.100k	2100000	2100000
		rocketmq.x2.120k	2700000	2700000
		rocketmq.x2.150k	3300000	3300000
		rocketmq.x2.200k	4200000	4200000

使用限制

限制项	说明
实例与版本	仅支持已开通 LiteTopic 能力的 RocketMQ 5.x 实例。需使用 Apache RocketMQ 5.x 社区版 gRPC SDK（版本不低于 5.1.0），旧版 Remoting SDK 不适用。
Topic 相关	父 Topic：需提前创建为 Lite 类型，生产者和消费者均需指定该父 Topic。父 Topic TTL：创建 Lite 类型父 Topic 时必须配置 TTL，取值范围为 30～720 分钟，设置为-1表示关闭 TTL 自动清理。 LiteTopic 名称：不能为空，最长为 64 字节，只能包含字母、数字、连字符（-）和下划线（_）。创建方式：LiteTopic 无需逐一预创建，首次向某个 LiteTopic 名称发送消息时动态产生。
订阅与消费	一个 Lite Consumer 只能绑定一个父 Topic，但可以动态订阅该父 Topic 下的多个 LiteTopic。单个消费者客户端最多可订阅 2000 个 LiteTopic。
消息类型	LiteTopic 消息不支持顺序消息分组、定时/延迟投递和消息优先级，也不能作为事务消息发送。

注意事项

类别	说明
命名设计	建议使用稳定、可追踪的业务标识作为 LiteTopic 名称，例如tenant_10001。避免使用请求 ID、时间戳等取值数量多且频繁变化的字段直接作为 LiteTopic 名称，否则会快速消耗配额。名称最长为 64 字节，仅允许使用 ASCII 字母、数字、连字符（-）和下划线（_）。
客户端生命周期	Producer 和 Consumer 建议在应用启动时创建并长期复用，不要每发送或消费一条消息就重新创建。调用subscribeLite后，应检查订阅是否成功。如果是网络异常，可以设置重试次数和重试间隔。如果是配额超限，应清理无用资源或调整实例规格，不要重复重试。不再消费某个 LiteTopic 时，调用unsubscribeLite取消订阅。应用退出前应关闭客户端。
消费可靠性	Push Consumer 应在消息处理成功后返回SUCCESS。同一条消息被多次投递时，不应产生重复扣款、重复写入等结果。动态订阅 LiteTopic 时，如需指定起始消费位置，请先评估历史消息量。选择MIN_OFFSET时，消费者会从当前最早可用位置开始消费，可能在短时间内拉取大量历史消息。

接入流程

确认实例能力

确认实例已开通 LiteTopic 能力，并获取客户端 Endpoint。具体操作，请参见查看实例详情。

创建父 Topic

在控制台创建 Lite 类型父 Topic，并根据业务需要配置 TTL。具体操作，请参见轻量主题管理。

创建消费组

创建消费组，并绑定该父 Topic。具体操作，请参见创建 Group。

接入社区 SDK

选择支持 LiteTopic API 的 Apache RocketMQ 5.x 社区版 gRPC SDK。相关参数说明，请参见 RocketMQ 5.x 参数说明。

发送消息

生产者将父 Topic 填入topic，将业务标识填入LiteTopic，每条消息只能设置一个LiteTopic。示例代码，请参见 SDK 示例。

动态订阅

消费者创建 Lite Consumer 并绑定父 Topic，然后调用subscribeLite订阅需要消费的 LiteTopic。示例代码，请参见 SDK 示例。

处理异常：根据异常类型分别处理：

网络异常可以设置重试次数和重试间隔。

出现LITE_TOPIC_QUOTA_EXCEEDED或LITE_SUBSCRIPTION_QUOTA_EXCEEDED时，应清理无用资源或调整实例规格，不要重复重试。

释放资源：不再消费某个 LiteTopic 时，及时调用unsubscribeLite取消订阅并释放资源。示例代码，请参见 SDK 示例。

SDK 示例

Java

Maven

<dependency>
<groupId>org.apache.rocketmq</groupId>
<artifactId>rocketmq-client-java</artifactId>
<version>${5.1.0 版本及以上}</version>
</dependency>

生产消息

ClientServiceProvider provider = ClientServiceProvider.loadService();
SessionCredentialsProvider credentials =
new StaticSessionCredentialsProvider("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY");
ClientConfiguration clientConfig = ClientConfiguration.newBuilder()
.setEndpoints("YOUR_ENDPOINT")
.setCredentialProvider(credentials)
.build();

Producer producer = provider.newProducerBuilder()
.setClientConfiguration(clientConfig)
.setTopics("YOUR_PARENT_TOPIC")
.build();

Message message = provider.newMessageBuilder()
.setTopic("YOUR_PARENT_TOPIC")
.setLiteTopic("tenant_10001")
.setKeys("order-123")
.setBody("hello LiteTopic".getBytes(StandardCharsets.UTF_8))
.build();

try {
SendReceipt receipt = producer.send(message);
System.out.println(receipt.getMessageId());
} catch (LiteTopicQuotaExceededException e) {
// 停止创建新的 LiteTopic，清理无用资源或申请扩容。
throw e;
} finally {
producer.close();
}

消费消息

LitePushConsumer consumer = provider.newLitePushConsumerBuilder()
.setClientConfiguration(clientConfig)
.setConsumerGroup("YOUR_CONSUMER_GROUP")
.bindTopic("YOUR_PARENT_TOPIC")
.setMessageListener(messageView -> {
System.out.printf("messageId=%s, liteTopic=%s%n",
messageView.getMessageId(), messageView.getLiteTopic().orElse(""));
return ConsumeResult.SUCCESS;
})
.build();

try {
consumer.subscribeLite("tenant_10001");
consumer.subscribeLite("tenant_10002", OffsetOption.MIN_OFFSET);
} catch (LiteSubscriptionQuotaExceededException e) {
// 取消不再使用的订阅或申请扩容。
throw e;
}

// 不再需要时：
consumer.unsubscribeLite("tenant_10002");
// 应用退出时：
consumer.close();

异常处理

错误码	说明	处理建议
LITE_TOPIC_QUOTA_EXCEEDED	当前实例的 LiteTopic 数量达到上限。	请停止继续创建新的 LiteTopic，并检查是否存在异常命名，例如使用请求 ID、时间戳等频繁变化的字段作为 LiteTopic 名称。修改轻量主题的 LiteTopic 过期时间。如仍无法满足业务需求，可升级实例规格。
LITE_SUBSCRIPTION_QUOTA_EXCEEDED	LiteTopic 订阅资源达到上限。	请取消不再使用的 LiteTopic 订阅，控制单个消费者客户端的订阅数量。如仍无法满足业务需求，可升级实例规格。

最近更新时间：2026.10.13 10:51:54

这个页面对您有帮助吗？

有用

无用