# kakfka工具库

**Repository Path**: code_01_1/kakfka-tool-library

## Basic Information

- **Project Name**: kakfka工具库
- **Description**: Kafka Toolkit (Go) / Kafka 工具套件（Go）
Minimal CLI + SDK for Kafka config validation, smoke tests (send/optional consume), and baseline perf checks. 简洁的 CLI/SDK，用于配置校验、发送/可选消费烟测、性能基线验证。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-14
- **Last Updated**: 2025-12-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kafka Toolkit (Go) / Kafka 工具套件（Go）

Minimal CLI + SDK for Kafka config validation, smoke tests (send/optional consume), and baseline perf checks. 简洁的 CLI/SDK，用于配置校验、发送/可选消费烟测、性能基线验证。

## Quick Start / 快速开始
- Go 1.25+，Kafka 运行中（示例 `localhost:9092`）。
- 安装：`go install ./cmd/kafkatool` 或 `go run ./cmd/kafkatool --help`
- 配置示例：`configs/kafka-dev.yaml`（默认 `smoke-topic`，消费可选）。

### CLI
烟测：
```bash
kafkatool validate --config configs/kafka-dev.yaml \
  --smoke-count 5 --payload-bytes 128 \
  --output json --report-out reports/validate.json
```
性能：
```bash
kafkatool perf --config configs/kafka-dev.yaml \
  --messages 1000 --parallel 2 --payload-bytes 256 \
  --duration 1m --success-target 0.999 --early-stop 0.02 \
  --output json --report-out reports/perf.json
```
模块验收：
```bash
kafkatool accept --config configs/kafka-dev.yaml \
  --module send --output json --report-out reports/send.json
```
常用参数：`--output json|text`，`--report-out <path>`，生产压测需 `allow_prod_tests=true` 且 `--force-prod`。

### Embed SDK / 嵌入 SDK
`pkg/kafkatoolkit` 可在你的项目中通过 go.mod replace 使用：
```go
require kafkaDemo v0.0.0
replace kafkaDemo => ../kafkaDemo

import (
  "context"
  "time"
  ktool "kafkaDemo/pkg/kafkatoolkit"
  "kafkaDemo/internal/validate"
  "kafkaDemo/internal/perf"
)

cfg, _ := ktool.LoadConfig("configs/kafka-dev.yaml")
_ = ktool.RunSmoke(context.Background(),
  validate.RetryPolicy{MaxAttempts: 3, Base: 2 * time.Second},
  func(ctx context.Context) error { return nil }, // TODO: 实际 send/consume
)
_ = ktool.RunPerf(context.Background(),
  perf.Params{Messages: 100, Parallel: 2, Duration: time.Minute, SuccessTarget: 0.99},
  func(ctx context.Context, idx int) error { return nil }, // TODO: 实际发送
)
```
仅做静态校验：`ktool.ValidateConfigOnly`。

## Testing / 测试
```bash
./scripts/ci.sh      # fmt/vet/test
go test -race ./...  # 推荐
# 集成（需 Kafka，默认 skip，可选）
export KAFKA_BROKERS=localhost:9092
go test -tags=integration ./tests/integration/...
```

## Notes / 说明
- 报告含状态/指标/配置摘要，`--report-out` 可持久化；metrics 可通过 `report.SetMetricsEnabled/SetMetricsSink` 控制。
- TLS 已支持 CA/客户端证书加载（文件路径或 PEM）；生产需提供真实证书。
- 消费校验可选：配置 `topics.consume` 即会尝试消费同量消息；留空仅验证发送。