告别依赖冲突！LangChain4j 0.35.0 Jsoup 依赖迁移全指南

2026-02-04 04:07:42作者：劳婵绚Shirley

LangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.

项目地址：https://gitcode.com/GitHub_Trending/la/langchain4j

还在为 Java 项目集成 AI 能力时遇到的依赖冲突头疼？升级 LangChain4j 0.35.0 版本后，Jsoup 依赖变更可能导致编译错误或运行时异常。本文将详解这次变更的技术细节、迁移步骤及避坑指南，让你 10 分钟完成平稳过渡。

变更背景与影响范围

LangChain4j 作为 Java 生态领先的 LLM 集成框架，在 0.35.0 版本中对 HTML 文档处理模块进行架构调整。原核心模块中的 Jsoup 依赖被迁移至独立组件，这一变更影响所有使用 HTML 文档加载或转换功能的应用。

关键变更点

依赖位置迁移：Jsoup 从 langchain4j-core 移至独立模块 document-transformers/langchain4j-document-transformer-jsoup
版本锁定：统一使用 Jsoup 1.18.3 版本，解决多模块版本不一致问题
API 稳定性：新增 HtmlToTextDocumentTransformer 专用转换器，替代原有内联实现

技术原理与架构调整

本次变更遵循 "关注点分离" 设计原则，将 HTML 解析功能从核心模块剥离为专用组件。新架构通过 SPI (Service Provider Interface) 实现文档转换器的插拔式设计，提升框架扩展性。

模块依赖关系

graph TD
    A[langchain4j-core] -->|依赖| B[langchain4j-document-transformer-jsoup]
    B --> C[Jsoup 1.18.3]
    D[应用项目] -->|可选依赖| B

独立后的 Jsoup 转换器模块结构如下：

langchain4j-document-transformer-jsoup/
├── pom.xml               // 声明 Jsoup 1.18.3 依赖
└── src/main/java/dev/langchain4j/data/document/transformer/jsoup/
    ├── HtmlToTextDocumentTransformer.java  // 核心转换实现
    └── JsoupDocumentTransformerConfiguration.java  // SPI 配置

迁移实施步骤

1. 更新 Maven/Gradle 依赖

Maven 项目需在 pom.xml 中添加新依赖：

<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-document-transformer-jsoup</artifactId>
    <version>0.35.0</version>
</dependency>

Gradle 项目添加：

implementation 'dev.langchain4j:langchain4j-document-transformer-jsoup:0.35.0'

2. 代码实现调整

原有 HTML 处理代码：

// 旧版本实现
String html = "<html><body>LLM 应用开发</body></html>";
Document document = Document.from(html); // 内部依赖 Jsoup

需更新为：

// 新版本实现
import dev.langchain4j.data.document.transformer.jsoup.HtmlToTextDocumentTransformer;

String html = "<html><body>LLM 应用开发</body></html>";
Document document = Document.from(html);
Document transformed = new HtmlToTextDocumentTransformer().transform(document).get();

3. 冲突解决与兼容性处理

若项目中存在其他 Jsoup 依赖，需通过 Maven 依赖管理强制统一版本：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.jsoup</groupId>
            <artifactId>jsoup</artifactId>
            <version>1.18.3</version>
        </dependency>
    </dependencies>
</dependencyManagement>

验证与测试策略

测试用例覆盖

建议添加以下测试场景验证迁移效果：

HTML 特殊标签（如 <script>、<style>）过滤测试
中文乱码处理验证
大文件（>10MB HTML）转换性能测试

验证工具推荐

使用 integration-tests 模块中的文档处理测试套件，执行命令：

mvn test -pl integration-tests -Dtest=DocumentTransformerTest

常见问题与解决方案

Q1: 升级后出现 ClassNotFoundException: org.jsoup.Jsoup

解决：检查是否已添加 langchain4j-document-transformer-jsoup 依赖，IDE 需执行 mvn clean install 刷新依赖缓存

Q2: 转换后文本丢失格式信息

解决：新转换器默认启用紧凑模式，可通过配置保留段落结构：

HtmlToTextDocumentTransformer transformer = new HtmlToTextDocumentTransformer.Builder()
    .preserveLineBreaks(true)
    .build();

Q3: 与 Spring Boot 自动配置冲突

解决：在 application.properties 中排除自动配置类：

spring.autoconfigure.exclude=dev.langchain4j.autoconfigure.DocumentTransformerAutoConfiguration

迁移路线图与最佳实践

分阶段实施建议

评估阶段：使用 mvn dependency:tree | grep jsoup 分析现有依赖
开发阶段：优先迁移测试环境，验证核心功能
灰度发布：监控生产环境日志中的 JsoupDocumentTransformer 相关 WARN 日志
全面切换：移除旧依赖，完成最终迁移

性能优化建议

对高频 HTML 转换场景，使用 ThreadLocal 缓存转换器实例
大文件处理建议使用流式转换：HtmlToTextDocumentTransformer.stream(htmlInputStream)

总结与展望

LangChain4j 0.35.0 的 Jsoup 依赖迁移不仅解决了长期存在的依赖冲突问题，更为后续支持多种 HTML 解析引擎（如 TagSoup、HtmlUnit）奠定基础。作为开发者，及时跟进框架架构演进，既能提升项目稳定性，也能更好地利用新特性提升开发效率。

建议收藏本文档并关注 docs/latest-release-notes.md 获取最新更新。如有迁移相关问题，可通过 CONTRIBUTING.md 中指引的社区渠道获取支持。

下期预告：《LangChain4j 向量数据库集成性能对比：Milvus vs Pinecone》

langchain4j