架构与系统设计 / 系统课时
消息租户元数据
消息租户元数据
本课解决多租户消息离开请求线程后“租户信息丢失”的问题。完成后,你将能设计统一消息元数据,在消息头和消息体中同时携带租户标识与追踪信息,并在发送前完成一致性校验。
学习目标
- 区分消息头与消息体中租户元数据的职责
- 设计可用于路由、追踪、重放和幂等处理的字段
- 在生产端构造并校验一条完整的多租户消息
元数据应该放在哪里
消息头适合放中间件和基础设施需要读取的信息,例如 tenantId、traceId、eventId 与 schemaVersion。消费者可以在反序列化业务体之前读取这些字段,用于恢复上下文、日志追踪和路由判断。
消息体应保存业务事件及可审计的元数据副本。这样消息被落库、转存或离线重放时,即使原始消息头丢失,仍能确认事件属于哪个租户。头和体同时保存租户标识时,消费端必须校验两者一致,不能静默选择其中一个。
| 字段 | 推荐位置 | 作用 |
|---|---|---|
tenantId |
消息头和消息体 | 标识数据归属,并用于恢复租户上下文 |
traceId |
消息头和消息体 | 串联生产、投递、消费和下游调用日志 |
eventId |
消息头和消息体 | 作为幂等键,避免重复消费产生副作用 |
schemaVersion |
消息头和消息体 | 支持消息结构演进与兼容判断 |
| 业务字段 | 消息体 | 描述本次事件本身,不参与基础设施路由 |

生产端构造统一消息
下面的 Java 17 示例不依赖具体消息中间件。headers 对应 RabbitMQ、Kafka 或其他中间件的消息头,Envelope 对应序列化后的消息体。生产端只从可信的租户上下文读取 tenantId,不能直接相信接口请求中任意传入的租户值。
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Map;
public class TenantMessageDemo {
record Metadata(String tenantId, String traceId, String eventId, int schemaVersion) {
Metadata {
requireText(tenantId, "tenantId");
requireText(traceId, "traceId");
requireText(eventId, "eventId");
if (schemaVersion < 1) {
throw new IllegalArgumentException("schemaVersion must be positive");
}
}
private static void requireText(String value, String name) {
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(name + " must not be blank");
}
}
}
record OrderCreated(String orderNo, long amountCent) {
}
record Envelope(Metadata metadata, OrderCreated data) {
}
record OutboundMessage(Map<String, String> headers, Envelope body) {
}
public static void main(String[] args) {
Metadata metadata = new Metadata(
"tenant-1001",
"trace-a8f21",
"event-20260803-001",
1
);
Map<String, String> headers = new LinkedHashMap<>();
headers.put("tenantId", metadata.tenantId());
headers.put("traceId", metadata.traceId());
headers.put("eventId", metadata.eventId());
headers.put("schemaVersion", String.valueOf(metadata.schemaVersion()));
Envelope body = new Envelope(
metadata,
new OrderCreated("ORDER-10001", 8800)
);
OutboundMessage message = new OutboundMessage(
Collections.unmodifiableMap(new LinkedHashMap<>(headers)),
body
);
validateConsistency(message);
System.out.println(message.headers());
System.out.println(message.body());
}
private static void validateConsistency(OutboundMessage message) {
String headerTenantId = message.headers().get("tenantId");
String bodyTenantId = message.body().metadata().tenantId();
if (!bodyTenantId.equals(headerTenantId)) {
throw new IllegalArgumentException("tenantId mismatch");
}
}
}预期输出
{tenantId=tenant-1001, traceId=trace-a8f21, eventId=event-20260803-001, schemaVersion=1}
Envelope[metadata=Metadata[tenantId=tenant-1001, traceId=trace-a8f21, eventId=event-20260803-001, schemaVersion=1], data=OrderCreated[orderNo=ORDER-10001, amountCent=8800]]接入真实中间件时,将 headers 映射到消息属性,将 Envelope 序列化为 JSON 或二进制协议。实际日志时间、消息分区和投递标签可能不同,但四个核心元数据字段应保持原值透传。
发送前必须校验的边界
发送前至少检查租户标识非空、格式合法、租户状态可用,以及消息头和消息体中的元数据完全一致。若消息由定时任务或批处理产生,应显式遍历租户并为每条消息写入对应上下文,不能沿用上一次循环留下的值。
traceId 用于观测,不应承担幂等职责;eventId 才应作为业务幂等键。重试同一事件时应复用原 eventId,但可以根据追踪策略复用或派生新的 traceId。
本课总结
- 消息头服务于路由、拦截和上下文恢复,消息体保存业务事件与可审计元数据
- 头和体同时携带租户标识时必须校验一致,避免消息被错误归属
eventId、traceId和schemaVersion分别解决幂等、追踪和结构演进问题
下一课预告
下一课将把这些元数据用于消费端,在业务处理前恢复租户上下文,并通过可靠清理避免线程复用造成跨租户污染。