LangChain4j 0.35.0 版本升级指南：Jsoup 依赖变更解析

在 LangChain4j 0.35.0 版本中，团队对 Jsoup 的依赖管理进行了重要调整，这一变更可能对部分用户的项目构建产生影响。本文将深入分析这一变更的技术背景、潜在影响以及解决方案，帮助开发者顺利完成版本升级。

变更背景

在 0.35.0 版本中，LangChain4j 对 HTML 文档处理模块进行了重构：

1. 将原有的 HtmlToTextDocumentTransformer 重命名为 HtmlTextExtractor
2. 将该功能提取到新的独立模块 langchain4j-document-transformer-jsoup 中
3. 从主 POM 文件中移除了对 Jsoup 的直接依赖

这种模块化设计遵循了软件工程的高内聚低耦合原则，使得依赖关系更加清晰，但也带来了兼容性挑战。

潜在影响分析

当开发者升级到 0.35.0 版本时，可能会遇到以下两类问题：

1. 直接依赖问题：如果项目中直接使用了 HtmlToTextDocumentTransformer 或 HtmlTextExtractor 类，需要显式引入新的 transformer 模块。

2. 间接依赖问题：更为隐蔽的是，如果项目中任何位置（包括测试代码）使用了 Jsoup 的相关类（如 org.jsoup.select.NodeVisitor），由于主 POM 移除了 Jsoup 依赖，会导致 ClassNotFoundException 或 NoClassDefFoundError。

典型的错误堆栈会显示：

java.lang.NoClassDefFoundError: org/jsoup/select/NodeVisitor

解决方案

根据使用场景的不同，开发者需要采取不同的应对措施：

1. 仅使用 LangChain4j 的 HTML 处理功能： 添加新模块依赖即可：

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

2. 项目中直接使用 Jsoup： 需要显式添加 Jsoup 依赖：

   <dependency>
       <groupId>org.jsoup</groupId>
       <artifactId>jsoup</artifactId>
       <version>1.17.2</version> <!-- 使用适合的版本 -->
   </dependency>
   

最佳实践建议

1. 依赖检查：升级前使用 mvn dependency:tree 检查项目是否间接依赖了 Jsoup。

2. 测试覆盖：确保升级后执行充分的测试，特别是涉及 HTML 处理的代码路径。

3. 版本管理：建议在父 POM 或 dependencyManagement 中统一管理 Jsoup 版本，避免版本冲突。

4. 文档参考：虽然本文不提供链接，但建议开发者仔细阅读对应版本的官方变更说明。

技术思考

这种依赖关系的调整反映了现代 Java 库开发的一个重要趋势：通过模块化减少不必要的依赖，提高库的灵活性和可维护性。作为使用者，我们需要：

1. 理解"显式优于隐式"的依赖管理哲学
2. 建立完善的依赖变更监控机制
3. 在项目初期就规划好第三方库的升级策略

通过这次变更，LangChain4j 为未来的功能扩展奠定了更好的架构基础，虽然短期可能带来一些升级成本，但从长远看有利于生态的健康发展。

希望本文能帮助开发者顺利完成版本过渡，享受 LangChain4j 新版本带来的改进和优化。