Skip to main content

客户端 SDK 开发指南

AutoMQ 完全兼容 Apache Kafka，支持使用 Apache Kafka 的客户端 SDK 进行集成和收发消息。本文档介绍 AutoMQ 推荐的客户端 SDK 以及使用注意事项。

兼容性说明​

AutoMQ 完全兼容 Apache Kafka （0.10 ~ 3.9 版本），推荐使用 Apache kafka 的客户端 SDK 访问 AutoMQ 进行收发消息。根据 Apache Kafka 的协议协商原则，在上述范围内的客户端版本均可以正常接入。

建议应用侧尽可能升级到更新的 SDK 版本，以修复历史版本的隐藏缺陷。

推荐的客户端 SDK 列表​

Apache Kafka 社区针对不同的开发语言提供了多种 SDK 选择，用户可查看社区的文档信息。AutoMQ 技术团队基于大量的生产实践，针对不同的开发语言推荐客户使用如下 SDK 接入 AutoMQ。 在 AutoMQ Labs 准备了对应客户端的快速开始样例，作为接入参考。

开发语言
客户端 SDK
推荐版本
样例
Java
Apache Kafka Java Client
>= 3.2.0
Demo
C/C++
librdkafka
>= 2.8.0
Demo
Go
franz-go
>= 1.17.1
Demo
Python
kafka-python
>= 2.2.3
Demo
NodeJS
KafkaJS
>= 2.2.4
Demo

如果目前使用的 SDK 不在上述推荐列表范围内，只要兼容 Apache Kafka 协议，则仍然可以继续访问 AutoMQ，建议查看下方的已知问题列表，进行适当的参数调整。

客户端参数调优​

使用 Apache Kafka SDK 收发消息时，除了选择推荐的 SDK 版本，还需要针对 Producer、Consumer 的关键参数进行调整，以达到最佳的性能。

建议参考Kafka 客户端配置调优▸ 进行参数检查和调整。

附录：其他已知问题​

Sarama Go SDK​

已知缺陷
缺陷信息
修复方法
Async Producer 在发送重试时没有限制内存占用
  • 缺陷版本：V1.43.3
  • 社区 Issue：https://github.com/IBM/sarama/issues/1358
  • 社区 PR：https://github.com/IBM/sarama/pull/3026
  • 现象：在使用 async_producer 发送消息，且对应 Topic 发生分区迁移时，Producer 内存占用会异常升高，甚至导致 OOM。
  • 原因：当 async_producer 接收到服务端的可重试错误（如分区迁移导致的 NOT_LEADER_OR_FOLLOWER）时，会将消息暂存于内存中，并根据策略进行重试。然而，该重试缓存没有大小限制，若大量且持续的重试发生，内存使用可能意外增加。
  • 升级版本到 >= V1.44.0

Kafka-Go SDK​

已知缺陷
缺陷信息
修复方法
Consumer 无法识别 Group Coordinator 变更
  • 缺陷版本：V0.4.47
  • 现象：__consumer_offsets Topic 发生分区迁移后，部分 Group 消费中断，日志报错
  • 原因：当 __consumer_offsets 分区迁移后，会导致部分 Group 的 Coordinator 发生变更。而 kafka-go 没有正确地处理该情况——在 Coordinator 变更后，仍然向老的 Coordinator 发送请求，导致了 NOT_COORDINATOR 报错。
  • 临时重启 Consumer 恢复。
  • 更换 SDK ，推荐使用 Franz-Go SDK，参考本文档推荐版本。

Kafka JS SDK​

已知缺陷
缺陷信息
修复方法
Consumer 配置 heartbeatInterval 不准确
  • 缺陷版本：V2.2.4
  • 社区说明：https://github.com/tulios/kafkajs/issues/130#issuecomment-422024849
  • 现象：当 Consumer 配置的 heartbeatInterval 和 sessionTimeout 过于接近时，Consumer 会周期性 Leave & Rejoin Group（但基本不影响消费），日志报错。
  • 原因：kafkajs 中的配置 heartbeatInterval 仅保证了“两次心跳间的最小间隔时间”，即在某些场景下（例如，Consumer 消费到 Topic 末尾，没有新的消息可供消费），Consumer 向 Coordinator 发送心跳的间隔可能超过 heartbeatInterval ；而如果该值配置地过大，就可能超过 sessionTimeout 进而导致 Coordinator 将 Consumer 驱逐。
  • 调低 heartbeatInterval 或调高 sessionTimeout （建议heartbeat.interval.ms 不应超过 session.timeout.ms 的 1/3）。