ITADN · 发现全球开源项目

Apache Kafka 是一个开源的分布式事件流平台，被数千家企业用于高性能数据管道、流分析、数据集成以及关键任务应用。

您需要安装 Java。

我们使用 Java 17 和 25 版本构建和测试 Apache Kafka。javac 中的 release 参数对 clients 和 streams 模块设置为 11，对其他模块设置为 17，以确保与其各自的最低 Java 版本兼容。同样，scalac 中的 release 参数对 streams 模块设置为 11，对其他模块设置为 17。

Scala 2.13 是 Apache Kafka 中唯一支持的版本。

构建 JAR 并运行

./gradlew jar

请遵循 https://kafka.apache.org/quickstart 中的说明

构建源码 JAR

./gradlew srcJar

构建聚合的 javadoc

./gradlew aggregatedJavadoc --no-parallel

构建 javadoc 和 scaladoc

./gradlew javadoc
./gradlew javadocJar # builds a javadoc jar for each module
./gradlew scaladoc
./gradlew scaladocJar # builds a scaladoc jar for each module
./gradlew docsJar # builds both (if applicable) javadoc and scaladoc jars for each module

运行单元/集成测试

./gradlew test  # runs both unit and integration tests
./gradlew unitTest
./gradlew integrationTest
./gradlew test -Pkafka.test.run.flaky=true  # runs tests that are marked as flaky

强制重新运行测试（无代码更改）

./gradlew test --rerun-tasks
./gradlew unitTest --rerun-tasks
./gradlew integrationTest --rerun-tasks

运行特定的单元/集成测试

./gradlew clients:test --tests RequestResponseTest
./gradlew streams:integration-tests:test --tests RestoreIntegrationTest

运行特定的单元/集成测试 N 次

N=500; I=0; while [ $I -lt $N ] && ./gradlew clients:test --tests RequestResponseTest --rerun --fail-fast; do (( I=$I+1 )); echo "Completed run: $I"; sleep 1; done

运行单元/集成测试中的特定测试方法

./gradlew clients:test --tests org.apache.kafka.clients.MetadataTest.testTimeToNextUpdate
./gradlew clients:clients-integration-tests:test --tests org.apache.kafka.clients.producer.ProducerFailureHandlingTest.testCannotSendToInternalTopic
./gradlew streams:integration-tests:test --tests org.apache.kafka.streams.integration.RestoreIntegrationTest.shouldRestoreNullRecord

使用 log4j 输出运行特定的单元/集成测试

默认情况下，测试期间只会输出少量日志。您可以通过修改模块 src/test/resources 目录中的 log4j2.yaml 文件来调整。

例如，如果您想查看 clients 项目测试的更多日志，您可以将 clients/src/test/resources/log4j2.yaml 中的该行修改为 level: INFO，然后运行：

./gradlew cleanTest clients:test --tests NetworkClientTest

并且您应该在 clients/build/test-results/test 目录下的文件中看到 INFO 级别的日志。

指定测试重试

默认情况下，重试功能是禁用的，但您可以设置 maxTestRetryFailures 和 maxTestRetries 来启用重试。

以下示例声明了 -PmaxTestRetries=1 和 -PmaxTestRetryFailures=3，以启用失败测试重试一次，总重试次数限制为 3。

./gradlew test -PmaxTestRetries=1 -PmaxTestRetryFailures=3

有关更多详细信息，请参阅 Test Retry Gradle 插件和 build.yml。

生成测试覆盖率报告

为整个项目生成覆盖率报告：

./gradlew reportCoverage -PenableTestCoverage=true -Dorg.gradle.parallel=false

为单个模块生成覆盖率，即：

./gradlew clients:reportCoverage -PenableTestCoverage=true -Dorg.gradle.parallel=false

覆盖率报告位于模块的构建目录中，按模块类型分类：

核心模块（:core）：core/build/reports/scoverageTest/index.html

其他模块：<module>/build/reports/jacoco/test/html/index.html

构建二进制发布版的 gzip 压缩 tar 包

./gradlew clean releaseTarGz

发布文件可在 ./core/build/distributions/ 中找到。

构建自动生成的消息

在切换分支时，有时只需重新构建 RPC 自动生成的消息数据，因为它们可能因代码更改而失败。您可以直接运行：

./gradlew processMessages processTestMessages

有关 Apache Kafka 消息协议的详细信息，请参阅 Apache Kafka Message Definitions。

运行 Kafka broker

使用编译后的文件：

KAFKA_CLUSTER_ID="$(./bin/kafka-storage.sh random-uuid)"
./bin/kafka-storage.sh format --standalone -t $KAFKA_CLUSTER_ID -c config/server.properties
./bin/kafka-server-start.sh config/server.properties

使用 docker 镜像：

docker run -p 9092:9092 apache/kafka:latest

See docker/README.md for detailed information.

清理构建

./gradlew clean

为特定项目运行任务

这适用于 core、examples 和 clients

./gradlew core:jar
./gradlew core:test

Streams 包含多个子项目，但你可以运行所有测试：

./gradlew :streams:testAll

列出所有 gradle 任务

./gradlew tasks

构建 IDE 项目

注意：开发 Kafka 时，请确保使用 JDK 17。

IntelliJ 原生支持 Gradle，并且会自动检查每个模块的 Java 语法和兼容性，即使 Structure > Project Settings > Modules 中显示的 Java 版本可能不正确。

对于 Eclipse，请运行：

./gradlew eclipse

eclipse 任务已配置为使用 ${project_dir}/build_eclipse 作为 Eclipse 的构建目录。Eclipse 的默认构建目录（${project_dir}/bin）与 Kafka 的脚本目录冲突，且为避免该配置下的已知问题，我们未使用 Gradle 的构建目录。

将 streams quickstart archetype 构件发布到 maven

对于 Streams archetype 项目，无法使用 gradle 上传到 maven；相反，需要在 quickstart 文件夹中调用 mvn deploy 命令：

cd streams/quickstart
mvn deploy

请注意，为了使此操作生效，您应创建/更新用户 maven 设置（通常为 ${USER_HOME}/.m2/settings.xml），以分配以下变量

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                       https://maven.apache.org/xsd/settings-1.0.0.xsd">
...                           
<servers>
   ...
   <server>
      <id>apache.snapshots.https</id>
      <username>${maven_username}</username>
      <password>${maven_password}</password>
   </server>
   <server>
      <id>apache.releases.https</id>
      <username>${maven_username}</username>
      <password>${maven_password}</password>
    </server>
    ...
 </servers>
 ...

将所有项目安装到本地 Maven 仓库

./gradlew -PskipSigning=true publishToMavenLocal

将特定项目安装到本地 Maven 仓库

./gradlew -PskipSigning=true :streams:publishToMavenLocal

构建测试 JAR

./gradlew testJar

运行代码质量检查

我们定期运行两个代码质量分析工具，SpotBugs 和 Checkstyle。

Checkstyle

Checkstyle 在 Kafka 中强制执行一致的编码风格。您可以使用以下命令运行 Checkstyle：

./gradlew checkstyleMain checkstyleTest spotlessCheck

Checkstyle 警告将在子项目构建目录中的 reports/checkstyle/reports/main.html 和 reports/checkstyle/reports/test.html 文件中找到。它们也会打印到控制台。如果 Checkstyle 失败，构建将失败。对于实验（或回归测试目的），请添加 -PcheckstyleVersion=X.y.z 开关（以覆盖项目定义的 checkstyle 版本）。

Spotless

导入顺序是静态检查的一部分。请在提交拉取请求之前调用 spotlessApply 来优化 Java 导入。

./gradlew spotlessApply

SpotBugs

SpotBugs 使用静态分析来查找代码中的 bug。您可以使用以下命令运行 SpotBugs：

./gradlew spotbugsMain spotbugsTest -x test

SpotBugs 警告将出现在子项目构建目录中的 reports/spotbugs/main.html 和 reports/spotbugs/test.html 文件中。使用 -PxmlSpotBugsReport=true 可生成 XML 报告而非 HTML 报告。

JMH 微基准测试

我们使用 JMH 来编写在 JVM 中产生可靠结果的微基准测试。

有关如何运行微基准测试的详细信息，请参阅 jmh-benchmarks/README.md。

依赖项分析

Gradle 依赖项调试文档提到使用 dependencies 或 dependencyInsight 任务来调试根项目或各个子项目的依赖项。

或者，使用 allDeps 或 allDepInsight 任务来递归遍历所有子项目：

./gradlew allDeps

./gradlew allDepInsight --configuration runtimeClasspath --dependency com.fasterxml.jackson.core:jackson-databind

这些与内置变体接受相同的参数。

确定是否有任何依赖项可以更新

./gradlew dependencyUpdates

常用构建选项

以下选项应使用 -P 开关进行设置，例如 ./gradlew -PmaxParallelForks=1 test。

commitId: 设置构建提交 ID，因为如果存在为构建目的添加的本地提交，.git/HEAD 可能不正确。
mavenUrl: 设置 maven 部署仓库的 URL（可以使用 file://path/to/repo 指向本地仓库）。
maxParallelForks: 并行启动的最大测试进程数。默认为 JVM 可用的处理器数量。
maxScalacThreads: scalac 后端的最大工作线程数。默认为 8 和 JVM 可用处理器数量中的较小值。该值必须在 1 到 16 之间（含边界）。
ignoreFailures: 忽略来自 junit 的测试失败
showStandardStreams: 在控制台显示测试 JVM 的标准输出和标准错误。
skipSigning: 跳过工件的签名。
testLoggingEvents: 要记录日志的单元测试事件，以逗号分隔。例如 ./gradlew -PtestLoggingEvents=started,passed,skipped,failed test。
xmlSpotBugsReport: 为 SpotBugs 启用 XML 报告。这也会禁用 HTML 报告，因为一次只能启用一种。
maxTestRetries: 失败测试用例的最大重试次数。
maxTestRetryFailures: 在后续测试中禁用重试之前的最大测试失败次数。
enableTestCoverage: 启用测试覆盖率插件和任务，包括跟踪所述覆盖率所需的类字节码增强。请注意，这会在运行测试时引入一些开销，因此默认情况下是禁用的（开销因情况而异，但 15-20% 是一个合理的估计值）。
keepAliveMode: 配置 Gradle 编译守护进程的 keep-alive 模式 - 重用可改善启动时间。值应为

为 daemon 或 session 之一（默认值为 daemon）。daemon 使守护进程保持运行，直到被显式停止，而 session 使其保持运行直到构建会话结束。目前这仅影响 Scala 编译器，请参阅 https://github.com/gradle/gradle/pull/21034 查看一个尝试对 Java 编译器执行相同操作的 PR。

scalaOptimizerMode：配置 Scala 编译器的优化行为，其值应为 none、method、inline-kafka 或 inline-scala 之一（默认值为 inline-kafka）。none 是 Scala 编译器的默认值，仅消除不可达代码。method 还包括方法局部优化。inline-kafka 添加了 kafka 包内方法的内联。最后，inline-scala 还包括 scala 库内方法的内联（这避免了诸如 Option.exists 之类方法的 lambda 分配）。inline-scala 仅在编译时和运行时的 Scala 库版本相同时才是安全的。由于我们无法保证在所有情况下都如此（例如，用户可能在集成测试中依赖 kafka jar，其中可能包含不同版本的 scala 库），因此我们默认不启用它。有关更多详细信息，请参阅 https://www.lightbend.com/blog/scala-inliner-optimizer。

升级 Gradle 版本

请参阅 gradle/wrapper/README.md 了解升级 Gradle 版本的说明。

运行系统测试

请参阅 tests/README.md。

使用 Trogdor 进行测试

我们使用 Trogdor 作为 Apache Kafka 的测试框架。您可以使用它来运行基准测试和其他工作负载。

请参阅 trogdor/README.md。

在 Vagrant 中运行

请参阅 vagrant/README.md。

Kafka 客户端示例

请参阅 examples/README.md。

贡献

Apache Kafka 致力于建设社区；我们欢迎任何想法或补丁。您可以通过 Apache 邮件列表联系我们。

要做出贡献，请遵循以下说明：

https://kafka.apache.org/contributing.html