---

name: "kafka" description: "Kafka开发专家助手。当用户需要进行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