概览Overview

这个项目做什么What it does

仓库提供一个可执行程序 cmd/main，带有 produce 与 consume 两个子命令。前者把一条消息写入指定主题，并打印 broker 返回的偏移量；后者持续从主题拉取记录，把每条记录的 offset、timestamp、key 与 value 逐条打印出来。

The repository ships one executable, cmd/main, with two subcommands. produce writes a single message to a topic and prints the offset the broker assigned. consume keeps polling a topic and prints each record's offset, timestamp, key and value.

职责边界Where the boundary is

所有 Kafka 行为——broker 连接、元数据处理、Kafka 协议、消息发送与拉取——都由 moonkafka 的 Producer 与 Consumer 完成。本项目只保留 命令行参数解析、UTF-8 文本转换和结果展示，没有实现任何自定义 Kafka 客户端逻辑。

Every Kafka behaviour — broker connection, metadata handling, the Kafka protocol, producing and fetching — comes from moonkafka's Producer and Consumer. What is left here is argument parsing, UTF-8 conversion and result rendering: no custom Kafka client logic is implemented.

API 基线API baseline

项目通过 MoonBit 包管理器引用 daqing/moonkafka@0.3.4。上游称该版本为 纯文档发布——没有任何库代码改动——因此 API 基线仍是 v0.3.3 标签提交 6e0f45f18ae9e5d9b16e30ddf9ac0533a7cdd602。0.3.4 只发布在 mooncakes.io 上，没有自己的 tag。

The project pulls in daqing/moonkafka@0.3.4 through the MoonBit package manager. Upstream calls that release documentation-only — no library code changed — so the API baseline is still the v0.3.3 tag, commit 6e0f45f18ae9e5d9b16e30ddf9ac0533a7cdd602. 0.3.4 lives on mooncakes.io only; it carries no tag of its own.

功能Features

• produce 与 consume 两个子命令，分别映射到 moonkafka 的 Producer 与 Consumer
• broker 地址与端口可覆盖，默认 127.0.0.1:9092
• consume 支持从 earliest 或 latest 开始，并用 --max-messages <n> 打印 n 条后正常退出
• producer 使用 acks=-1，等 broker 确认后打印消息偏移量
• 记录按 UTF-8 解码输出：key 为空显示 <null>，value 为空显示 <tombstone>
• 端口、起始位置、--max-messages 在解析期校验，非法取值直接报错退出
• 端到端集成测试：用容器启动 Kafka、建全新主题，再驱动真实 CLI 走完「发送 → 消费」
• 附单节点 Kafka 4.3 KRaft 的 compose 配置，手动调试与集成测试共用
• Makefile 覆盖类型检查、单元测试、格式化、构建与集成测试

• produce and consume subcommands, mapping onto moonkafka's Producer and Consumer
• Broker host and port are overridable; the defaults are 127.0.0.1:9092
• consume starts from earliest or latest, and --max-messages <n> exits cleanly after printing n records
• The producer uses acks=-1 and prints the offset the broker acknowledged
• Records are decoded as UTF-8: an empty key prints as <null>, an empty value as <tombstone>
• Ports, start position and --max-messages are validated while parsing; a bad value fails fast
• An end-to-end integration test that starts Kafka in a container, creates fresh topics and drives the real CLI through produce → consume
• A single-node Kafka 4.3 KRaft compose file shared by manual debugging and the integration test
• Make targets for type-checking, unit tests, formatting, building and the integration test

项目结构Project layout

moonkafka-demo/
├── cmd/main/                 CLI: produce / consume
│   ├── main.mbt              entry point, subcommand dispatch
│   ├── cli.mbt               argument parsing and help text
│   ├── producer_demo.mbt     produce subcommand
│   ├── consumer_demo.mbt     consume subcommand
│   └── cli_wbtest.mbt        unit tests for argument parsing
├── tests/itest/              end-to-end integration test
│   ├── main.mbt              phases and teardown
│   ├── harness.mbt           Step / Runner, command execution, assertions
│   ├── kafka.mbt             runtime detection, Kafka lifecycle, topics
│   ├── options.mbt           integration-test options
│   ├── cli.mbt               builds CLI commands, parses their output
│   └── harness_wbtest.mbt    unit tests for the harness helpers
├── docs/                     this site
├── docker-compose.kafka.yml  single-node Kafka 4.3 KRaft
├── Makefile                  day-to-day commands and itest targets
└── moon.mod                  module definition and dependencies

下一步Next steps

• 快速开始起一个本地 Kafka，构建并把消息发出去。
• 命令行参考两个子命令的全部参数、输出格式与校验规则。
• 集成测试容器起 Kafka、两个阶段与全部选项。
• 设计与实现代码如何组织，produce/consume 各自走哪条路径。

• Getting startedBring up a local Kafka, build, and send your first message.
• CLI referenceEvery argument, output format and validation rule for both subcommands.
• Integration testContainer-managed Kafka, both phases, and every option.
• DesignHow the code is organised and what each command actually does.