架构与系统设计 / 系统课时

消息租户元数据

消息租户元数据

本课解决多租户消息离开请求线程后“租户信息丢失”的问题。完成后,你将能设计统一消息元数据,在消息头和消息体中同时携带租户标识与追踪信息,并在发送前完成一致性校验。

学习目标

  • 区分消息头与消息体中租户元数据的职责
  • 设计可用于路由、追踪、重放和幂等处理的字段
  • 在生产端构造并校验一条完整的多租户消息

元数据应该放在哪里

消息头适合放中间件和基础设施需要读取的信息,例如 tenantId、traceId、eventId 与 schemaVersion。消费者可以在反序列化业务体之前读取这些字段,用于恢复上下文、日志追踪和路由判断。

消息体应保存业务事件及可审计的元数据副本。这样消息被落库、转存或离线重放时,即使原始消息头丢失,仍能确认事件属于哪个租户。头和体同时保存租户标识时,消费端必须校验两者一致,不能静默选择其中一个。

字段 推荐位置 作用
tenantId 消息头和消息体 标识数据归属,并用于恢复租户上下文
traceId 消息头和消息体 串联生产、投递、消费和下游调用日志
eventId 消息头和消息体 作为幂等键,避免重复消费产生副作用
schemaVersion 消息头和消息体 支持消息结构演进与兼容判断
业务字段 消息体 描述本次事件本身,不参与基础设施路由

消息租户元数据在生产端、消息中间件和消费端之间的流向

生产端构造统一消息

下面的 Java 17 示例不依赖具体消息中间件。headers 对应 RabbitMQ、Kafka 或其他中间件的消息头,Envelope 对应序列化后的消息体。生产端只从可信的租户上下文读取 tenantId,不能直接相信接口请求中任意传入的租户值。

java
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");
        }
    }
}

预期输出

text
{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 分别解决幂等、追踪和结构演进问题

下一课预告

下一课将把这些元数据用于消费端,在业务处理前恢复租户上下文,并通过可靠清理避免线程复用造成跨租户污染。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

消息租户元数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通