This document introduces the naming conventions and usage guidelines for common concepts of TDMQ for RocketMQ.
Naming Conventions
topic
The name cannot be empty and can contain only letters, digits, percent signs (%), hyphens (-), and underscores (_). It must be 3 to 100 characters in length.
Recommended format: String.format("tp_%s_%s","System name","Business name").
Example: tp_order_check.
tag
The name cannot be empty and can be any string. It is used for secondary message filtering under a topic.
Recommended format: String.format("tag_%s","Business action or category").
Example: Tag + Business action. For example, the tag for order creation can be tag_create, and the tag for order closing can be tag_close.
keys
The name cannot be empty. Setting is recommended. It can be a string or an array of strings. It is used for querying messages or message traces in the console.
Recommended format: String.format("%s","Unique business ID").
Examples: unique IDs such as order ID, transaction ID, serial number, and TraceID.
producer group
The name cannot be empty. It must be 3 to 64 characters in length and can contain only letters, digits, hyphens (-), and underscores (_).
Recommended format: String.format("pg_%s_%s","System name","Business name").
Example: pg_transfer_check.
consumer group
The name cannot be empty. It must be 3 to 64 characters in length and can contain only letters, digits, hyphens (-), and underscores (_).
Recommended format: String.format("cg_%s_%s","System name","Business name").
Example: cg_transfer_check.
role
The name cannot be empty. It can contain only digits, letters, hyphens (-), and underscores (_), and cannot exceed 32 characters in length.
A role represents a marker for read/write permissions in different business scenarios. Recommended format: Business name + send/consume.
Examples: role_order_send, role_order_consume, and role_order_all.
clientId
clientId represents a client instance ID and must be unique across different clients. It cannot be set directly on the client. instanceName is an optional component of the clientId and can be adjusted to modify the clientId.
|
Producer | ${Current IP address}@${instanceName} |
Cluster consumer | ${Current IP address}@${instanceName} |
Broadcast consumer | ${Current IP address}@${instanceName} |
public String buildMQClientId() {
StringBuilder sb = new StringBuilder();
sb.append(this.getClientIP());
sb.append("@");
sb.append(this.getInstanceName());
if (!UtilAll.isBlank(this.unitName)) {
sb.append("@");
sb.append(this.unitName);
}
if (enableStreamRequestType) {
sb.append("@");
sb.append(RequestType.STREAM);
}
return sb.toString();
}
instanceName
Instance name. By default, you do not need to set an instance name. The system randomly generates a unique value by default using the following code.
public void changeInstanceNameToPID() {
if (this.instanceName.equals("DEFAULT")) {
this.instanceName = UtilAll.getPid() + "#" + System.nanoTime();
}
}
Broadcast consumers should keep the consumer instance name unchanged upon each startup and read the local offset file on the client. The instance name should be explicitly set. For broadcasting consumption, the current client IP address should remain consistent before and after startup. In container deployments, fixed pod IP scheduling should be configured. Otherwise, broadcast messages during restarts may result in missed consumption.
Recommended format: String.format("instance-%s-%s","System name","Business name").
Usage Guidelines
Producers
Mandatory: Use only one topic per domain service.
Mandatory: Set the tag based on the business action when you send messages for a domain service.
Mandatory: Set the keys field when you send messages on the producer.
Mandatory: Print message logs regardless of whether the message sending succeeds or fails, and make sure that the SendResult and key fields are included.
Recommended: Store failed messages in a database after sending failures, and then use timer-based threads for scheduled retries to ensure that messages reach the broker.
Recommended: Use one-way messages for business scenarios with low reliability requirements.
Mandatory: Specify a producer group when you create a producer.
Consumers
Mandatory: Specify a consumer group when you create a consumer.
Mandatory: Implement idempotency logic at the business level, as the consumer cannot avoid message duplication.
Recommended: Start multiple consumer instances within the same consumer group to increase consumption parallelism, or modify consumeThreadMin and consumeThreadMax to enhance the parallel consumption capability of a single consumer.
Recommended: Set the consumeMessageBatchMaxSize parameter of the consumer to enable batch consumption of messages and achieve higher throughput.
Recommended: Discard less important messages when you deal with message backlogs, if business data requirements permit.
Recommended: If the message volume is low, print message details and consumption duration at the consumption entry to facilitate subsequent troubleshooting.