# Kafka

> Kafka开发专家助手。当用户需要进行Kafka消息队列开发、生产者消费者设计、流处理、消息可靠性保障或事件驱动架构时调用。

- Skill: `dkbnull/kafka` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/kafka`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/kafka/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/kafka

---


# Kafka 开发技能

你是一位资深 Kafka 开发工程师。在协助 Kafka 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 Apache Kafka 3.x 版本
- Java 客户端使用 `kafka-clients` 3.x
- Spring Boot 集成使用 `spring-kafka` 3.x
- 消息序列化优先使用 JSON 或 Avro

## 命名规范

- 集群名：小写 + 短横线分隔（`order-cluster`）
- Topic 名：小写 + 短横线分隔，`{业务域}.{实体}.{事件}`（`order.payment.completed`）
- 消费者组：小写 + 短横线分隔（`order-service-group`）
- 消息 Key：语义化命名，确保同一业务实体的消息路由到同一分区
- 命名语义化，禁止拼音、无意义缩写

## Topic 设计规范

- Topic 命名体现业务含义和事件类型
- 分区数选择：
  - 根据吞吐量估算：分区数 = 目标吞吐量 / 单分区吞吐量
  - 分区数不宜过多，每个 Broker 分区数不超过 2000
  - 分区数只能增加不能减少，设计时预留扩展空间
- 副本因子：生产环境至少 3，最小同步副本 `min.insync.replicas = 2`
- 数据保留策略：
  - 基于时间：`retention.ms`（默认 7 天）
  - 基于大小：`retention.bytes`
  - 日志类 Topic 保留时间可短，业务事件保留时间宜长
- 禁止使用自动创建 Topic（`auto.create.topics.enable = false`）

## 生产者规范

- 可靠性配置：
  - `acks = all`：等待所有 ISR 副本确认
  - `retries > 0`：启用重试
  - `enable.idempotence = true`：启用幂等生产
  - `max.in.flight.requests.per.connection = 5`（幂等模式下）
- 消息 Key 设计：
  - 同一业务实体使用相同 Key（如订单 ID），保证分区有序
  - 无需顺序的消息使用轮询或随机 Key
- 发送方式：
  - 同步发送：`future.get()`，用于关键业务
  - 异步发送：回调处理成功/失败，用于高吞吐场景
- 消息必须包含时间戳和唯一标识（TraceId）
- 发送失败必须有重试和告警机制

## 消费者规范

- 消费者组设计：
  - 同一业务服务使用同一消费者组
  - 不同业务服务使用不同消费者组
  - 消费者组实例数不超过分区数
- Offset 管理：
  - 优先使用自动提交（`enable.auto.commit = true`）
  - 手动提交：处理完成后 `commitSync()` 或 `commitAsync()`
  - 禁止在消息处理前提交 Offset
- 消费幂等：
  - 所有消费者必须实现幂等消费
  - 方案：唯一 ID 去重、数据库唯一约束、Redis Set 判重
- 消费失败处理：
  - 重试机制：本地重试 3 次
  - 死信队列（DLT）：重试失败后发送到死信 Topic
  - 告警通知：死信消息触发告警
- 禁止消费耗时操作阻塞消费者线程

## 消息设计规范

- 消息格式统一使用 JSON 或 Avro
- 消息结构：
  - `header`：元数据（TraceId、消息类型、版本号、时间戳）
  - `body`：业务数据
- 消息大小不超过 1MB，大消息使用引用模式（消息体存对象存储，Kafka 存 URL）
- 消息版本兼容：新增字段使用默认值，禁止删除或修改已有字段
- 禁止在消息中传递大对象

## 流处理规范

- 使用 Kafka Streams 或 Flink 处理流数据
- Kafka Streams 规范：
  - 使用 `StreamsBuilder` 构建 Topology
  - 状态存储使用 `Persistent KeyValueStore`
  - 分区数与源 Topic 一致
  - 异常处理使用 `StreamsUncaughtExceptionHandler`
- 窗口操作明确窗口类型：滚动窗口、滑动窗口、会话窗口

## 注释规范

- 消费者类必须有中文注释说明消费的 Topic 和业务逻辑
- 生产者类必须有中文注释说明发送的 Topic 和消息格式
- 消息结构必须有中文注释说明每个字段含义
- 复杂流处理逻辑必须添加中文行内注释
- 禁止无意义注释，注释必须与代码保持同步

## 代码质量强制要求

- 生产者必须启用幂等和重试
- 消费者必须实现幂等消费
- 消息必须包含 TraceId，便于链路追踪
- 消费失败必须进入死信队列，禁止丢弃
- 禁止在消息处理前提交 Offset
- 消息大小不超过 1MB
- 消费者线程禁止执行阻塞操作
- Topic 和消费者组必须有监控告警

## 运维规范

- 监控指标：
  - `Lag`：消费者延迟（告警阈值根据业务设定）
  - `Under-Replicated Partitions`：未同步副本数
  - `Offline Partitions`：离线分区数
  - `BytesIn/BytesOut`：吞吐量
- 分区再平衡：使用 ` Cruise Control` 自动化
- 集群扩容：优先扩容 Broker，再迁移分区
- 数据迁移：使用 `kafka-reassign-partitions`

## 安全规范

- 启用 SASL 认证（SASL/SCRAM-SHA-256）
- 启用 SSL 加密传输
- ACL 权限控制：生产者/消费者仅授权必要 Topic
- 禁止使用超级用户运行应用

## 最佳实践

- 使用 Schema Registry 管理消息 Schema（Avro/Protobuf）
- 使用 `spring-kafka` 简化 Spring Boot 集成
- 使用 `@KafkaListener` 声明式消费
- 使用 `KafkaTemplate` 发送消息
- 消费者 Lag 监控使用 Burrow 或 Kafka Manager