Apache Thrift Java 库（libthrift）构建与发布全指南：源码编译、Gradle 构建、测试报告与 Maven 发布

后端微服务API设计【免费下载链接】thriftApache Thrift项目地址https://gitcode.com/gh_mirrors/thrift2/thrift点击查看免费下载Apache Thrift 的 Java 语言库即libthriftMaven 坐标org.apache.thrift:libthrift是 Thrift 跨语言 RPC 框架在 JVM 生态中的核心实现。本文以仓库内 lib/java/README.md 为骨架结合 lib/java/build.gradle、lib/java/gradle.properties、lib/java/gradle/ 下的构建脚本以及org.apache.thrift核心源码完整讲解 libthrift 的两种构建路径CMake 集成与纯 Gradle、单元测试与覆盖率报告的生成、Maven Central 发布流程以及 0.12.0 / 0.13.0 两个版本的破坏性变更。读完本文你将能够从源码独立编译、测试、安装并发布 libthrift同时规避升级过程中最常见的 API 兼容性问题。一、库的定位与版本信息Java 库在 Thrift 仓库中位于 lib/java其 Gradle 工程名由 lib/java/settings.gradle 中的rootProject.name libthrift定义。构建所需的核心元数据集中在 lib/java/gradle.propertiesthrift.version0.21.0 thrift.groupidorg.apache.thrift releasefalse # 测试执行属性 testPort9090 # 使用 Clover 覆盖率默认关闭 cloverEnabledfalse # Maven 依赖下载地址 mvn.repohttps://repo1.maven.org/maven2 apache.repohttps://repository.apache.org/content/repositories/releases其中thrift.version定义了产物版本号release属性控制版本是否带有-SNAPSHOT后缀。从 lib/java/build.gradle 的实现看版本号并非写死if (Boolean.parseBoolean(project.release)) { version property(thrift.version) } else { version property(thrift.version) -SNAPSHOT }也就是说默认releasefalse构建出的 jar 版本形如0.21.0-SNAPSHOT只有传入-Preleasetrue时才是正式版本号0.21.0。这一点在后续发布到 Maven Central一节至关重要。与大多数 Apache Thrift 语言库不同Java 库不采用 GNU Autotools 工具链而是使用 Java 开发者主流的Gradle构建系统。Automakelib/java/Makefile.am与 CMakelib/java/CMakeLists.txt只是外层封装真正干活的是 Gradle 任务。二、从源码构建与安装CMake 集成方式在 Linux 上使用源码发行版的 CMake 构建时最简单的构建与安装命令是make all sudo make install/fast这里强调必须使用install/fast选项而不是普通的make install。原因是构建工具链在设计上会在用户主目录缓存文件若使用带依赖自动重建的普通 install会因为自动重建而引发问题install/fast会在预期的本地构建树中完成编译然后直接调用 CMake 的 install 逻辑把产物复制到目标位置绕开这一干扰。从 lib/java/CMakeLists.txt 可以看到这一机制的具体实现CMake 定义一个名为ThriftJava的自定义目标内部调用${GRADLE_EXECUTABLE} assemble生成build/libs/libthrift.jar随后通过install(DIRECTORY ...)将libthrift-${thrift_VERSION}.jar、依赖 jar 以及 javadoc 分别安装到JAVA_INSTALL_DIR与JAVA_DOC_INSTALL_DIR。注释中明确写道This works best when make all sudo make install/fast is used使用make all sudo make install/fast效果最佳与 README 的说法相互印证。CMake 方式还支持两种补充入口执行make MavenPublishCMake 生成的目标名即可完成 Maven 发布内部调用gradle clean uploadArchives开启BUILD_TESTING时会注册名为JavaTest的 CTest 测试通过-Pthrift.compiler${THRIFT_COMPILER}把 Thrift 编译器路径传给 Gradle 测试任务。此外若目标是 Androidlib/java/CMakeLists.txt 会改用android子工程构建出thrift-debug.aar与thrift-release.aar。三、不使用 CMake/Autoconf 的纯 Gradle 构建3.1 准备 Gradle 环境当前仓库使用 Gradle 8.0 构建 Java 源码lib/java/build.gradle 要求构建时 JDK 不低于 1.8否则直接抛出GradleException。常规 Gradle 项目的做法是把gradle-wrapper.jar放入工程后通过 wrapper 引导但为了避免向源码树中提交二进制文件本仓库有意忽略了 wrapper 文件需要手动安装 Gradle。README 给出了与 Travis CI Docker 镜像一致的标准安装步骤export GRADLE_VERSION8.4 # 安装依赖 apt-get install -y --no-install-recommends openjdk-17-jdk-headless wget unzip # 下载 Gradle 发行包 wget https://services.gradle.org/distributions/gradle-$GRADLE_VERSION-bin.zip -q -O /tmp/gradle-$GRADLE_VERSION-bin.zip # 校验二进制完整性 echo 3e1af3ae886920c3ac87f7a91f816c0c7c436f276a6eefdb3da152100fef72ae /tmp/gradle-$GRADLE_VERSION-bin.zip | sha256sum -c - # 解压并安装 unzip -d /tmp /tmp/gradle-$GRADLE_VERSION-bin.zip mv /tmp/gradle-$GRADLE_VERSION /usr/local/gradle ln -s /usr/local/gradle/bin/gradle /usr/local/bin安装完成后gradle可执行文件位于/usr/local/bin/。如果你仍希望本地生成 wrapper即使它被 .gitignore 忽略可以执行gradle wrapper --gradle-version $GRADLE_VERSION3.2 编译 Java 库在 lib/java 目录下直接执行gradle即可完成编译defaultTasks build已定义在 lib/java/build.gradle。产物为libthrift-version.jar位于build/libs目录。这里的version受 lib/java/gradle.properties 的thrift.version与release共同决定默认得到libthrift-0.21.0-SNAPSHOT.jar。构建对 JDK 版本的处理在 lib/java/gradle/sourceConfiguration.gradle 中定义java { toolchain { languageVersion JavaLanguageVersion.of(17) } } tasks.withType(JavaCompile).configureEach { options.encoding UTF-8 options.debug true options.release 8 // ... }即使用 Java 17最新 LTStoolchain 编译但通过--release 8保证最终产物是 Java 8 级别的字节码同时开启-Werror与一系列-Xlint警告检查确保库的代码质量。这也解释了为何 CI 中还有基于 Java 11 的运行时验证。3.3 只编译不跑测试gradle assemble默认的gradle即build会执行单元测试而单元测试依赖系统上存在可用的 Thrift 编译器。若只想构建库而不运行测试使用gradle assemble3.4 安装到本地 Maven 仓库如果希望其他 Maven 或 Gradle 工程能够直接引用可执行gradle publishToMavenLocal库会被安装到用户主目录下的.m2/repository中之后即可在任意构建工具中以org.apache.thrift:libthrift:version坐标引用。3.5 在应用中集成 libthrift最简单的方式是把libthrift.jar添加到应用 classpath或安装到默认系统 classpath。若使用依赖管理工具则可直接引用本地 Maven 仓库中的坐标lib/java/gradle/publishing.gradle 中定义了完整的 Maven 坐标信息artifactId固定为libthriftPOM 中声明了 Apache License 2.0、开发者邮箱devthrift.apache.org等元数据。四、单元测试与 Thrift 编译器4.1 测试对编译器的两种处理方式默认构建会运行单元测试而测试前需要用 Thrift 编译器生成测试代码因此系统上必须存在可用的thrift可执行文件。README 给出两种选择从源码构建 Thrift 可执行文件并放在源码树中的默认位置。Gradle 构建默认就会去那里寻找——lib/java/gradle/environment.gradle 中有明确逻辑ext.thriftRoot rootProject.file(../..) ext.thriftCompiler findProperty(thrift.compiler) ?: $thriftRoot/compiler/cpp/thrift即默认编译器路径是仓库根目录下compiler/cpp/thrift由 C 编译器工程产出。安装官方二进制发行版并把路径写入~/.gradle/gradle.properties使用属性名thrift.compiler。例如在 Windows 上若 Thrift 安装在C:\Thriftthrift.compilerC:/Thrift/thrift.exe4.2 测试代码的生成与测试配置测试用 Java 代码并非手工编写而是由 lib/java/gradle/generateTestThrift.gradle 在构建期调用 Thrift 编译器生成到build/gen-java、build/gen-javabean、build/gen-fullcamel等多个目录默认生成器为java:jakarta_annotationsthrift 源文件取自仓库根目录 test 下的*.thrift文件。测试任务配置在 lib/java/gradle/unitTests.gradle使用 JUnit PlatformJUnit 5并开启测试类与方法级别的并行执行junit.jupiter.execution.parallel.enabledtrue堆上限maxHeapSize 512m默认测试端口来自gradle.properties的testPort9090注入javax.net.ssl.trustStore/keyStore等 SSL 系统属性指向src/crossTest/resources下的.truststore/.keystore供 TLS 相关测试使用。4.3 HTML 单元测试报告构建会自动生成 HTML 格式的单元测试报告位置在build/reports/tests/test/index.html可直接用浏览器打开查看。五、Clover 代码覆盖率报告构建支持可选的 Clover 覆盖率统计通过 Gradle 属性cloverEnabledtrue开启可在~/.gradle/gradle.properties中设置或通过命令行-PcloverEnabledtrue传入。生成报告的位置HTML 报告build/reports/clover/html/index.htmlPDF 报告build/reports/clover/clover.pdf一条命令完成构建 单元测试 Clover 报告gradle -PcloverEnabledtrue从 lib/java/gradle/cloverCoverage.gradle 的实现看该特性默认关闭cloverEnabledfalse定义于 lib/java/gradle.properties仅在属性为 true 时才应用com.bmuschko.clover插件并设置testIncludes [**/Test*.java]、排除自动生成的thrift/test/Test*.java报告同时输出 HTML 与 PDF且build任务依赖cloverGenerateReport。六、代理环境下的构建在企业内网或需要代理访问外网依赖时可通过 JVM 系统属性指定 HTTP 代理gradle -Dhttp.proxyHostmyproxyhost -Dhttp.proxyPort8080 -Dhttp.proxyUserthriftuser -Dhttp.proxyPasswordtopsecret若使用 Autotools/CMake 方式构建即外层调用 configure 生成 Makefile可通过环境变量透传同样的参数./configure --with-java GRADLE_OPTS-Dhttp.proxyHostmyproxyhost -Dhttp.proxyPort8080 -Dhttp.proxyUserthriftuser -Dhttp.proxyPasswordtopsecret七、发布 Maven 制品到 Maven Central7.1 通过 Automake / CMake 触发发布Automake 构建生成的 Makefile 会在运行构建时提供正确参数前提是 configure.ac 已设置正确版本号CMake 构建同理会读取configure.ac中的版本值。执行以下命令之一即可make maven-publish # Automake Linux 构建 make MavenPublish # CMake 生成的构建从 lib/java/Makefile.am 可见maven-publish实际执行的是gradle publish -Preleasetrue -Pthrift.version$(PACKAGE_VERSION)lib/java/CMakeLists.txt 中的MavenPublish目标则执行gradle clean uploadArchives。二者都以-Preleasetrue强制使用正式版本号。7.2 配置签名与认证信息Gradle 的publish任务已预配置了向 Apache Maven staging 仓库签名并发布制品所需的全部细节但需要外部提供以下属性用于仓库认证与制品 PGP 签名。推荐在~/.gradle/gradle.properties中创建/编辑# 制品 PGP 签名的密钥信息示例值 signing.keyId24875D73 signing.passwordsecret signing.secretKeyRingFile/Users/me/.gnupg/secring.gpg # Apache Maven staging 仓库的用户凭据 mavenUsermeMyselfAndI mavenPasswordMySuperAwesomeSecretPassword如果没有secring.gpg文件可参考 Gradle 官方 signing 插件文档生成注意新版 GnuPG 生成的通常是*.gpg私钥文件而非secring.gpg可根据实际情况调整signing.secretKeyRingFile指向。从 lib/java/gradle/publishing.gradle 的实现看签名逻辑为signing { required { !version.endsWith(SNAPSHOT) gradle.taskGraph.hasTask(publish) } sign publishing.publications.mavenJava }即只有发布非 SNAPSHOT版本且确实执行publish任务时才会要求签名仓库凭据则仅在同时提供mavenUser与mavenPassword两个属性时注入。7.3 使用 Gradle 手动发布凭据与密钥就绪后执行gradle -Preleasetrue publish该命令会按需生成构建产物并完成发布。注意这里同样要加-Preleasetrue否则产物版本带-SNAPSHOT后缀签名与仓库路径行为都会不同。7.4 覆盖目标仓库地址通过 Gradle 属性maven-repository-url可以覆盖默认的发布目标仓库默认值定义在 lib/java/gradle.propertiesmaven-repository-urlhttps://repository.apache.org/service/local/staging/deploy/maven2。例如把签名后的 jar 发布到公司内部 Nexus 服务器maven-repository-urlhttps://my.company.com/service/local/staging/deploy/maven2或在命令行一次性指定以下示例同时覆盖了仓库地址、强制 release 版本并显式指定版本号gradle -Pmaven-repository-urlhttps://my.company.com/service/local/staging/deploy/maven2 -Preleasetrue -Pthrift.version0.11.0 publish八、依赖说明libthrift 的编译期依赖与测试依赖全部声明在 lib/java/gradle/environment.gradle版本号统一托管在 lib/java/gradle.properties依赖用途org.slf4j:slf4j-api日志门面org.apache.httpcomponents.client5:httpclient5/httpcore5HTTP 传输层THttpClientjakarta.servlet:jakarta.servlet-api嵌入式 Servlet 服务器支持jakarta.annotation:jakarta.annotation-apiJakarta 注解org.apache.commons:commons-lang3通用工具org.junit.jupiter:junit-jupiter、org.mockito:mockito-core单元测试框架仅测试期依赖仓库默认指向 Maven Centralmvn.repo与 Apache 发行仓库apache.repo。构建时还会把仓库根目录的 LICENSE 与 NOTICE 文件以META-INF/*.txt形式打入 jar见 lib/java/gradle/sourceConfiguration.gradle 的processResources配置。九、破坏性变更与升级注意事项README 末尾专门记录了升级时需要关注的破坏性变更这些都可以在当前仓库源码中得到印证。9.1 0.13.0TAsyncProcessor / TProcessor 的 process 方法签名变更TAsyncProcessor与TProcessor中process方法的签名发生了变化移除了 boolean 返回值改为依赖异常表达处理结果。对照当前源码 lib/java/src/main/java/org/apache/thrift/TProcessor.javapublic interface TProcessor { void process(TProtocol in, TProtocol out) throws TException; }以及 lib/java/src/main/java/org/apache/thrift/TAsyncProcessor.javapublic interface TAsyncProcessor { void process(final AsyncFrameBuffer fb) throws TException; }两个接口的process现在都是void返回、通过抛出TException表达失败。升级到 0.13.0 及以后版本时所有自定义的 TProcessor / TAsyncProcessor 实现都必须相应调整方法签名。9.2 0.13.0TSaslTransportException 移除THRIFT-4805TSaslTransportException已被移除对应 JIRA 单 THRIFT-4805原来由该异常表达的对端提前关闭/文件结束场景现在统一由TTransportException覆盖判定条件为TTransportException.getType() END_OF_FILEEND_OF_FILE常量定义在 lib/java/src/main/java/org/apache/thrift/transport/TTransportException.javapublic static final int UNKNOWN 0; public static final int NOT_OPEN 1; public static final int ALREADY_OPEN 2; public static final int TIMED_OUT 3; public static final int END_OF_FILE 4; public static final int CORRUPTED_DATA 5;9.3 0.12.0AutoExpandingBuffer 与 ShortStack 可见性收窄0.12.0 将AutoExpandingBuffer与ShortStack两个内部优化类的访问修饰符从public改为默认包内级别第三方库不再能直接访问。对照当前源码ShortStack在 lib/java/src/main/java/org/apache/thrift/protocol/ShortStack.java 中确实以包私有形式存在class ShortStack其 Javadoc 说明它是为TCompactProtocol的 field id 栈量身定制的short专用栈实现性能约为java.util.Stack的 10 倍以上。而AutoExpandingBufferlib/java/src/main/java/org/apache/thrift/transport/AutoExpandingBuffer.java在当前 0.21.0 源码中显示为public class——README 记载的是 0.12.0 当时的变化若你的第三方代码在 0.12.0 之后仍能引用到该类说明其可见性在后续版本中又得到了恢复。升级建议无论当前可见性如何这类内部优化类都未被承诺为公共 API第三方代码不应依赖它们。十、小结围绕 lib/java/README.md本文完整还原了 Apache Thrift Java 库的工程化全景两条构建路径CMake 集成make all sudo make install/fast与纯 Gradlegradle/gradle assemble/gradle publishToMavenLocal产物统一为build/libs/libthrift-version.jar测试与质量门禁单元测试依赖 Thrift 编译器默认compiler/cpp/thrift可用thrift.compiler属性覆盖HTML 报告位于build/reports/tests/test/index.html可选 Clover 覆盖率-PcloverEnabledtrue发布链路通过make maven-publish/make MavenPublish或gradle -Preleasetrue publish配合签名与认证属性发布到 Maven Centralmaven-repository-url可覆盖目标仓库升级红线0.13.0 的process方法签名变化与TSaslTransportException移除、0.12.0 的AutoExpandingBuffer/ShortStack可见性收窄均可在 lib/java/src/main/java/org/apache/thrift 源码中找到对应实现。无论你是想为定制化需求编译本地 libthrift还是计划向 Maven 仓库发布内部版本亦或是正在评估从旧版本升级的兼容性成本上述命令、属性与源码依据都可以直接作为实操参考。若需进一步了解库的编码规范可阅读 lib/java/coding_standards.md各 Gradle 构建脚本environment.gradle、unitTests.gradle、publishing.gradle 等也是理解构建细节的第一手资料。赞分享后端微服务API设计【免费下载链接】thriftApache Thrift项目地址https://gitcode.com/gh_mirrors/thrift2/thrift点击查看免费下载相关推荐Apache Thrift Java 库libthrift构建、测试与 Maven 发布实战指南Apache Thrift Java 库libthrift构建、测试与 Maven 发布实战指南 导读 本指南以 Apache Thrift 仓库中 lib后端RPC框架序列化代码生成Apache ZooKeeper 仓库指南源码结构、构建产物与 Maven 打包发布全解析Apache ZooKeeper 仓库指南源码结构、构建产物与 Maven 打包发布全解析 本篇技术指南以 Apache ZooKeeper 官方仓库根目录的后端配置中心服务注册发现OpenRocket 构建与发布完全指南Gradle 构建系统、Maven Central 发布与多平台签名安装包OpenRocket 构建与发布完全指南Gradle 构建系统、Maven Central 发布与多平台签名安装包 本文是基于 OpenRocket 仓库 d桌面应用科学计算3D渲染上一篇Scrutor装饰器链式调用构建复杂业务逻辑的完整解决方案下一篇OpenVAS Scanner开源漏洞扫描器的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考