LangChain4j 依赖版本参差报 NoClassDefFoundError

工程里同时存在两个 LangChain4j 版本时，core 升级删掉了某个类，上层集成还在引用它。编译能过，跑起来才炸 NoClassDefFoundError，根子是依赖解析选中了不匹配的版本。用 langchain4j-bom 对齐稳定模块，beta / 预览模块再显式 pin 到同一版本号。

Issue & Env（案发现场与环境）

业务场景：基于 Quarkus 的项目用 quarkus-langchain4j。把 langchain4j-core 从 1.0.0-beta2 升到 1.0.0-beta3 后，构建期报错。
环境：JDK 17+，Maven 或 Gradle 管理依赖，core 与第三方集成各自声明版本。
缺的类：dev.langchain4j.model.chat.TokenCountEstimator。

StackTrace（堆栈日志）

报错原文（来自 issue #2873）：

java.lang.RuntimeException: io.quarkus.builder.BuildException: Build failure: Build failed due to errors
        [error]: Build step io.quarkiverse.langchain4j.deployment.AiServicesProcessor#watchResourceFiles threw an exception: java.lang.NoClassDefFoundError: dev/langchain4j/model/chat/TokenCountEstimator
        at io.quarkiverse.langchain4j.deployment.LangChain4jDotNames.<clinit>(LangChain4jDotNames.java:49)
        at io.quarkiverse.langchain4j.deployment.AiServicesProcessor.watchResourceFiles(AiServicesProcessor.java:942)

Reproduce（复现代码）

pom 里 core 升了版本，集成模块还停在旧的：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-core</artifactId>
    <version>1.0.0-beta3</version>
</dependency>
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-open-ai</artifactId>
    <version>1.0.0-beta2</version>
</dependency>

mvn compile 不报错。一跑起来，找类就失败。

Root Cause（根因分析）

先解释「编译能过、运行才炸」。core 从 1.0.0-beta2 升到 1.0.0-beta3 时，TokenCountEstimator 被删掉了。依赖 core 的上层模块（这里是 quarkus-langchain4j 的 deployment 层）仍在引用它。引用写在字节码里，编译期不会去校验目标类在不在，于是没报。等运行或构建期真要加载这个类，才抛 NoClassDefFoundError。

更深一层是依赖解析。工程里只要出现两个 langchain4j 版本，选谁由解析规则定。Maven 走 nearest-wins，声明层级近的优先。Gradle 默认选最高版本。选中的那个不一定和所有模块匹配。

langchain4j-bom 能把稳定模块对齐。但 beta / 预览模块常常不在 BOM 管理范围内，得自己显式 pin 版本。这类问题在「core 版本 vs 第三方集成版本」混着用的时候尤其多。升级 core 前，先确认上层集成跟没跟。

有一点要说清：官方没把「BOM 覆盖 beta 模块」写成承诺。这属于社区说法，截至撰写时未核实。

The Fix（解决方案）

用 BOM 统一版本。Maven 在 dependencyManagement 里引 langchain4j-bom，版本与 core 一致。各 langchain4j 模块只写 groupId 和 artifactId，不写 version：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-bom</artifactId>
            <version>1.0.0-beta3</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Gradle 用 platform 引同一份 BOM：

implementation(platform("dev.langchain4j:langchain4j-bom:1.0.0-beta3"))
implementation("dev.langchain4j:langchain4j-core")
implementation("dev.langchain4j:langchain4j-open-ai")

beta / 预览模块别指望 BOM。把它们的版本号都 pin 成同一个。

然后自查依赖树，目标只有一个版本的 langchain4j-core：

mvn dependency:tree -Dincludes=dev.langchain4j

./gradlew dependencies | grep langchain4j

升级也有讲究。core 的 patch / minor 版本也可能删类。升级前先读 release notes。真遇到 NoClassDefFoundError，先用 -verbose:class，或用 jarviz、IDE 定位这个类来自哪个 jar，再回查那个版本删没删过它。

小结

编译过、运行炸，多半是版本没对齐。先确认依赖树里只有一个 core，再用 BOM 管住稳定模块，beta 模块手动 pin。升级前看 release notes，比出事再查省事。

References（参考来源）

TokenCountEstimator class missing in langchain4j-core-1.0.0-beta3 — langchain4j issue #2873github-issue
langchain4j-bom — Maven Centralmaven-central
Introduction to the Dependency Mechanism（nearest-wins 与 dependencyManagement）— Maven 官方文档official-docs
Dependency Constraints and Conflicts — Gradle 官方文档official-docs