Apache Kafka

有关项目的详细信息，请参阅我们的网站。

您需要安装Java。

我们使用Java 8、11、17和21来构建和测试Apache Kafka。我们在javac和scalac中将release参数设置为8，以确保生成的二进制文件与Java 8或更高版本兼容（与用于编译的Java版本无关）。自Apache Kafka 3.0以来，项目范围内的Java 8支持已被弃用，自Apache Kafka 3.7以来，代理和工具的Java 11支持已被弃用，计划在Apache Kafka 4.0中移除这两者（有关更多详细信息，请参阅KIP-750和KIP-1013）。

支持Scala 2.12和2.13，默认使用2.13。自Apache Kafka 3.0以来，Scala 2.12支持已被弃用，并将在Apache Kafka 4.0中移除（有关更多详细信息，请参阅KIP-751）。有关如何使用特定Scala版本或所有支持的Scala版本，请参见下文。

构建jar包并运行

./gradlew jar

按照https://kafka.apache.org/quickstart中的说明操作

构建源代码jar包

./gradlew srcJar

构建聚合javadoc

./gradlew aggregatedJavadoc

构建javadoc和scaladoc

./gradlew javadoc
./gradlew javadocJar # 为每个模块构建javadoc jar包
./gradlew scaladoc
./gradlew scaladocJar # 为每个模块构建scaladoc jar包
./gradlew docsJar # 为每个模块构建javadoc和scaladoc jar包（如适用）

运行单元/集成测试

./gradlew test # 运行单元和集成测试
./gradlew unitTest
./gradlew integrationTest

在代码没有更改的情况下强制重新运行测试

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

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

./gradlew clients:test --tests RequestResponseTest

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

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

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

./gradlew core:test --tests kafka.api.ProducerFailureHandlingTest.testCannotSendToInternalTopic
./gradlew clients:test --tests org.apache.kafka.clients.MetadataTest.testTimeToNextUpdate

运行带有log4j输出的特定单元/集成测试

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

例如，如果您想查看clients项目测试的更多日志，可以修改clients/src/test/resources/log4j.properties中的这一行为log4j.logger.org.apache.kafka=INFO，然后运行：

./gradlew cleanTest clients:test --tests NetworkClientTest

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

指定测试重试

默认情况下，每个失败的测试会重试一次，每次测试运行最多重试五次。测试会在测试任务结束时重试。通过以下方式调整这些参数：

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

更多详细信息，请参阅测试重试Gradle插件。

生成测试覆盖率报告

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

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

为单个模块生成覆盖率报告，例如：

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

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

./gradlew clean releaseTarGz

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

构建自动生成的消息

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

./gradlew processMessages processTestMessages

在KRaft模式下运行Kafka代理

使用编译后的文件：

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

使用docker镜像：

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

在ZooKeeper模式下运行Kafka代理

使用编译后的文件：

./bin/zookeeper-server-start.sh config/zookeeper.properties
./bin/kafka-server-start.sh config/server.properties

由于ZooKeeper模式已被弃用，计划在Apache Kafka 4.0中移除，docker镜像仅支持在KRaft模式下运行

清理构建

./gradlew clean

使用可用的Scala版本之一（2.12.x或2.13.x）运行任务

请注意，如果使用2.13.x以外的版本构建jar包，您需要在bin/kafka-run-class.sh中设置SCALA_VERSION变量或更改它以运行快速启动。

您可以传递主版本号（如2.12）或完整版本号（如2.12.7）：

./gradlew -PscalaVersion=2.12 jar
./gradlew -PscalaVersion=2.12 test
./gradlew -PscalaVersion=2.12 releaseTarGz

使用默认启用的所有Scala版本运行任务

调用gradlewAll脚本，后跟任务：

./gradlewAll test
./gradlewAll jar
./gradlewAll releaseTarGz

为特定项目运行任务

适用于core、examples和clients

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

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

./gradlew :streams:testAll

列出所有gradle任务

./gradlew tasks

构建IDE项目

请注意，这并非严格必要（例如，IntelliJ IDEA对Gradle项目有很好的内置支持）。

./gradlew eclipse
./gradlew idea

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

将所有Scala版本和所有项目的jar包发布到maven

推荐的命令是：

./gradlewAll publish

为了向后兼容，以下命令也可以工作：

./gradlewAll uploadArchives

请注意，要使其正常工作，您应该创建/更新${GRADLE_USER_HOME}/gradle.properties（通常是~/.gradle/gradle.properties）并分配以下变量

mavenUrl=
mavenUsername=
mavenPassword=
signing.keyId=
signing.password=
signing.secretKeyRingFile=

将streams快速启动原型制品发布到maven

对于Streams原型项目，不能使用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>
 ...

将所有jar包安装到本地Maven仓库

推荐的命令用于同时构建Scala 2.12和2.13版本是：

./gradlewAll publishToMavenLocal

为了向后兼容，以下命令也可以工作：

./gradlewAll install

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

./gradlew -PskipSigning=true :streams:publishToMavenLocal

如果需要，您可以使用-PscalaVersion=2.13指定Scala版本。

构建测试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失败，构建将失败。

请注意，./gradlew spotlessCheck目前在Java 21上存在问题（参见https://github.com/diffplug/spotless/pull/1920），因此请确保使用JDK 11或17运行此命令

Spotless

导入顺序是静态检查的一部分。在提交拉取请求之前，请调用spotlessApply（需要JDK 11+）来优化Java代码的导入。

./gradlew spotlessApply

请注意，./gradlew spotlessApply目前在Java 21上存在问题（参见https://github.com/diffplug/spotless/pull/1920），因此请确保使用JDK 11或17运行此命令

Spotbugs

Spotbugs使用静态分析来查找代码中的错误。您可以使用以下命令运行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编译守护进程的保活模式 - 重用可以改善启动时间。值应为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。