kafka

Apache Kafka（TypeScript）

当你需要通过 TypeScript/Node 进行 Kafka 生产、消费或管理操作时，使用此技能：优先选择 @platformatic/kafka，并结合代理语义、主题设计、交付保证，以及会改变应用代码的运维操作。

工作流

1. 检查本地情况：
   • 软件包：@platformatic/kafka（快照版本 2.13.0）。运行环境：Node >=22.22 或 >=24.6。Kafka 代理已通过 3.5–4.2 的 CI 测试（上游 Apache Kafka 当前为 4.3.x；4.0+ 仅支持 KRaft）。
   • 客户端：Producer / Consumer / Admin，使用 bootstrapBrokers（而非 KafkaJS 的 brokers）。
   • 主题：分区、键、RF / min.insync.replicas、清理策略。
   • 语义：至少一次 vs EOS；自动提交 vs 手动提交；ProduceAcks。
2. 日常使用方法请优先遵循 usage-guide.md。
3. 版本有变动时，请更新文档。从 source-map.md 开始。
4. 深入了解时，请参阅：
   • 概念（分区、群组、保留、EOS）：fundamentals.md。
   • @platformatic/kafka API、序列化器、流、事务、SASL：platformatic-kafka.md。
   • 设计、DLQ、outbox、监控：patterns-ops.md。
   • 客户端生态与代理：clients-ecosystem.md。
5. 优先选择 @platformatic/kafka，而非（已停止维护的）kafkajs，也优先于原生 node-rdkafka，除非必须使用 librdkafka。不要在 Platformatic 中臆造 KafkaJS 的 connect / subscribe / run API。
6. 通过有针对性的生产/消费冒烟测试、必要时使用 Admin 创建主题、关注滞后情况，并在关闭时调用 close()，以完成验证。

核心判断

• Kafka 是仅追加的分区日志。顺序仅在分区内有保证；群组的并行度上限等于分区数。
• 应用默认语义：至少一次 + 幂等处理器。只有在需要 Kafka↔Kafka EOS 时才使用事务 / READ_COMMITTED。
• 持久性三要素：RF=3、min.insync.replicas=2、生产者 ProduceAcks.ALL（如果可用，再加上幂等生产者）。
• 键：使用稳定的实体 ID 来保证顺序和分区分配。压缩需要键和墓碑记录（null 值）。
• 双写（同一请求中写入数据库 + Kafka）时，优先使用 outbox/CDC。
• 毒丸消息：重试 / 发送到 DLQ，然后提交——绝不要永远阻塞某个分区。
• Platformatic：客户端应长期存活；延迟连接；调用 close()；通过 consume() → 流进行消费（for await / data / 并发 forEach）；偏移量为 bigint；消费时的标头是一个 Map。
• 传入 serializers / deserializers（例如 stringSerializers）——默认使用 Buffer。
• 默认情况下，经典群组的重新平衡会暂停所有成员；可选择启用 KIP-429 cooperative-sticky（protocols: [{ name: COOPERATIVE_STICKY_ASSIGNOR, version: 3 }]，所有成员必须一起启用），或在 Kafka 4.0+ 上使用 KIP-848（groupProtocol: "consumer"）。留意卡住成员的 consumer:heartbeat:stalled 事件。
• Kafka share groups（KIP-932 队列，自 Kafka 4.2 起可用于生产）尚未在 @platformatic/kafka 中实现——不要承诺它能提供队列语义。
• Kafka 4.0+ 仅支持 KRaft（不再使用 ZooKeeper）。本地 / 开发环境：修正 advertised.listeners。
• 命令示例优先使用 bun / bunx；不过，运行环境仍须满足 @platformatic/kafka 的 Node 版本要求。

验证

优先使用仓库自带的命令。对于有实质影响的 Kafka 工作，覆盖相关子集：

• bun pm ls @platformatic/kafka，并使用 Node ≥22.22（或 ≥24.6）。
• 冒烟测试：Admin createTopics（或现有主题）、Producer.send、Consumer.consume + 处理 + close()。
• 持久性：ProduceAcks.ALL；声称实现 EOS 时使用幂等性/transactionalId。
• Consumer：正确的 groupId、模式（EARLIEST/LATEST/COMMITTED），以及在 autocommit: false 时处理后提交。
• 安全性：TLS + SASL（或 mTLS）；公共网络上不得使用 PLAINTEXT。
• 运维：消费者延迟、未充分复制的分区、热点键倾斜、再平衡风暴（max.poll / 处理时间）。

报告已运行和未运行的检查，以及尚未确认的 broker/版本假设。