告别依赖冲突！LangChain4j 0.35.0 Jsoup 依赖迁移全指南
2026-02-04 04:07:42作者：劳婵绚Shirley
还在为 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》
登录后查看全文
相关内容推荐
热门项目推荐
相关项目推荐
atomcodeClaude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust069- DDeepSeek-V4-ProDeepSeek-V4-Pro（总参数 1.6 万亿，激活 49B）面向复杂推理和高级编程任务，在代码竞赛、数学推理、Agent 工作流等场景表现优异，性能接近国际前沿闭源模型。Python00
MiniMax-M2.7MiniMax-M2.7 是我们首个深度参与自身进化过程的模型。M2.7 具备构建复杂智能体应用框架的能力，能够借助智能体团队、复杂技能以及动态工具搜索，完成高度精细的生产力任务。Python00
GLM-5.1GLM-5.1是智谱迄今最智能的旗舰模型，也是目前全球最强的开源模型。GLM-5.1大大提高了代码能力，在完成长程任务方面提升尤为显著。和此前分钟级交互的模型不同，它能够在一次任务中独立、持续工作超过8小时，期间自主规划、执行、自我进化，最终交付完整的工程级成果。Jinja00
Kimi-K2.6Kimi K2.6 是一款开源的原生多模态智能体模型，在长程编码、编码驱动设计、主动自主执行以及群体任务编排等实用能力方面实现了显著提升。Python00
Hy3-previewHy3 preview 是由腾讯混元团队研发的2950亿参数混合专家（Mixture-of-Experts, MoE）模型，包含210亿激活参数和38亿MTP层参数。Hy3 preview是在我们重构的基础设施上训练的首款模型，也是目前发布的性能最强的模型。该模型在复杂推理、指令遵循、上下文学习、代码生成及智能体任务等方面均实现了显著提升。Python00
热门内容推荐
最新内容推荐
如何快速提升编程技能：80+实用应用创意项目完全指南80个实战项目：如何用App Ideas快速提升编程技能终极指南：如何用Android Asset Studio快速生成Android应用图标资源如何快速上手Ollama：本地运行Kimi、GLM、DeepSeek等主流大模型的完整指南终极指南：如何快速生成专业级Android应用图标如何快速部署本地AI模型：Ollama完整指南如何通过80+个应用创意项目快速提升编程技能：终极学习指南如何快速部署本地AI模型：Ollama完整指南与实战教程80个实战项目创意：从零到一提升编程技能的完整指南终极应用创意宝典：100+实战项目助你快速提升编程技能
项目优选
收起
docs暂无描述
Dockerfile
687
4.45 K
pytorchAscend Extension for PyTorch
Python
540
664
atomcodeClaude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed.
Get Started
Rust
388
69
ops-math本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
953
919
community本项目是CANN开源社区的核心管理仓库，包含社区的治理章程、治理组织、通用操作指引及流程规范等基础信息
646
230
kernelopenEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
407
322
Oohos_react_native
React Native鸿蒙化仓库
C++
336
385
RuoYi-Vue3🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.59 K
923
MindSpeed-LLM昇腾LLM分布式训练框架
Python
145
172
flutter_flutter暂无简介
Dart
935
234