Kafka 系列 —（22）Topic 设计规范文档（适用于 Kafka + MQTT + IoT Core 智能锁类产品）

少 Topic，多 Key：避免为每台设备开 topic；用统一 topic + deviceId 作为 key。
设备为 Key 保证顺序：key = deviceId，单设备事件写入同一分区保证顺序。
分区数按吞吐与并行度规划：高并发场景下分区数应 >= consumer 实例数。
分层 Topic 设计：Raw → Processed → Alert/Command → Audit。
Schema 管理：使用 Schema Registry（Avro/Protobuf）管理演进。
保留策略分层：Raw 保留短期（7-30天），Processed/Alert 保留更短或按合规。Archive 入 S3。
多租户隔离：通过 topic 前缀或 payload 中 tenantId 做隔离（推荐两者结合）。
可靠性配置：Producer acks=all, enable.idempotence=true; Broker replication.factor>=3；min.insync.replicas=2。

3.命名规范（统一）

统一格式（Kafka & MQTT 映射一致）：

{kafka_prefix}.{domain}.{data_class}.{message_type}

推荐前缀：

iot.<tenant?>.<domain>.<data_class>.<message_type>

字段说明：

iot：系统前缀
<tenant?>：可选租户前缀（multi-tenant 环境）
domain：业务域，如 lock、sensor
data_class：raw / processed / command / audit / alert / status
message_type：telemetry / event / heartbeat / lifecycle / config

示例：

iot.lock.raw.telemetry
iot.lock.processed.alert
iot.lock.command
iot.lock.audit

MQTT 与 Kafka 映射建议保留层次（规则引擎可配置）。

4.核心 Topic 清单

所有 topic 均为共享式多数设备使用，不为单设备建 topic。

Topic name	说明	partitions	replication	retention	cleanup.policy
iot.lock.raw.telemetry	原始设备上行（时间序列）	144 (or tuned)	3	7 days	delete
iot.lock.raw.event	原始事件（unlock, tamper）	72	3	30 days	delete
iot.lock.processed.telemetry	清洗后/归一化 telemetry	144	3	30 days	delete
iot.lock.processed.alert	实时告警	12	3	90 days	compact,delete (hybrid)
iot.lock.command	平台下发指令（cloud→device）	12	3	7 days	delete
iot.lock.audit	操作审计（只追加）	12	3	365 days	compact
iot.lock.status	设备心跳/在线状态（KTable）	12	3	2 days	compact
iot.lock.backup.raw	用于重处理的备份 topic（可选）	same as raw	3	90 days	delete

说明：分区数需结合预计设备数、每设备速率与消费者并发数调整。示例分区数为中大型部署参考值。

5.Key 与 Partition 策略

Message Key：始终用 deviceId（或 tenantId|deviceId）作为消息 key。
- JSON 示例： key = "tenantA|esp32-0001"
Partitioner：使用默认 hash-partitioner（基于 key 做一致哈希）。
避免热点：若单设备高吞吐（异常），采取采样/拆分策略（deviceId + sub-shard），或专门流转到高吞吐 topic。
分区数原则：
- 预估消费者实例数（C）与目标并发 = 分区数 >= C * safety_factor (1.2~2)
- 设备数 N 与预期每设备吞吐 r：total throughput = N * r, 根据 broker 吞吐能力确定分区。

6.Schema（示例 JSON / Avro）

建议使用 Avro/Protobuf + Schema Registry，下列同时给出 JSON 示例便于阅读。

6.1 Telemetry（Raw） — JSON 示例

{
  "tenantId": "tenantA",
  "deviceId": "esp32-0001",
  "productKey": "lock-v1",
  "timestamp": 1699999999000,
  "ts_timezone": "UTC",
  "payload": {
    "battery": 87,
    "rssi": -64,
    "temperature": 23.5,
    "event_seq": 12345
  },
  "meta": {
    "protocol": "mqtt",
    "gatewayId": "gw-01",
    "rawFormatVersion": "v1"
  }
}

6.2 Event（Raw event） — JSON 示例

{
  "tenantId": "tenantA",
  "deviceId": "esp32-0001",
  "timestamp": 1699999999000,
  "eventType": "unlock",
  "eventSource": "app",
  "eventDetail": {
    "method": "password",
    "userId": "user-123",
    "success": true
  },
  "meta": {
    "seq": 3456,
    "gatewayId": "gw-01"
  }
}

6.3 Command（downstream） — JSON 示例

{
  "tenantId": "tenantA",
  "deviceId": "esp32-0001",
  "commandId": "cmd-20250101-0001",
  "timestamp": 1700000000000,
  "commandType": "unlock",
  "params": {
    "durationSec": 5
  },
  "issuedBy": "operator-ui-12",
  "ttlMs": 60000,
  "meta": {
    "priority": "high"
  }
}

6.4 Status (KTable-style) — JSON 示例 (compact)

{
  "deviceId": "esp32-0001",
  "lastSeenTs": 1700000001000,
  "online": true,
  "firmwareVersion": "1.2.3",
  "health": {
    "battery": 87,
    "temp": 23.5
  }
}

Avro / Protobuf

为生产使用，请把上述结构迁移为 Avro/Protobuf schema 并注册到 Schema Registry。示例（简化 Avro）：

{
  "namespace": "com.company.iot",
  "type": "record",
  "name": "TelemetryV1",
  "fields": [
    {"name":"tenantI

最低0.47元/天解锁文章