升级Vespa至8.357.16后Java组件出现LinkageError求助

问题场景 #

开发的Java组件用于向Vespa写入文档，在Vespa 7.113.28版本下运行正常，升级至8.357.16版本后触发LinkageError。

核心代码片段 #

Instant instant = Instant.ofEpochSecond(timestamp);
ZoneId timeZone = ZoneId.of("UTC+8");
LocalDateTime dateTime = LocalDateTime.ofInstant(instant, timeZone);
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
String formattedDate = dateTime.format(formatter);

DocumentAccess access = DocumentAccess.createForNonContainer();
AsyncSession session = access.createAsyncSession(new AsyncParameters());
DocumentType type = access.getDocumentTypeManager().getDocumentType("QATracker");
DocumentId id = new DocumentId("id:my-search:QATracker::" + custAcctID + "_" + timestamp);
Document docIn = new Document(type, id);
DocumentPut put = new DocumentPut(docIn);
Document document = put.getDocument();
document.setFieldValue("responseDate", formattedDate);
document.setFieldValue("responseDateTime", timestamp);
document.setFieldValue("content", content);
document.setFieldValue("custAcctID", custAcctID);

session.put(docIn);

错误日志 #

[2024-07-01 14:04:13.698] ERROR   container        Container.com.yahoo.jrt.Transport    
    fatal error in com.yahoo.jrt.TransportThread@6982fc54
    exception=
    java.lang.LinkageError: loader constraint violation: when resolving method 'void com.yahoo.component.Version.<init>(com.yahoo.text.Utf8Array)' the class loader org.apache.felix.framework.BundleWiringImpl$BundleClassLoader @37baddde of the current class, com/yahoo/messagebus/network/rpc/RPCTarget, and the class loader org.apache.felix.framework.BundleWiringImpl$BundleClassLoader @23bff419 for the method's defining class, com/yahoo/component/Version, have different Class objects for the type com/yahoo/text/Utf8Array used in the signature (com.yahoo.messagebus.network.rpc.RPCTarget is in unnamed module of loader org.apache.felix.framework.BundleWiringImpl$BundleClassLoader @37baddde, parent loader 'bootstrap'; com.yahoo.component.Version is in unnamed module of loader org.apache.felix.framework.BundleWiringImpl$BundleClassLoader @23bff419, parent loader 'bootstrap')
    at com.yahoo.messagebus.network.rpc.RPCTarget.handleRequestDone(RPCTarget.java:141)
    at com.yahoo.jrt.InvocationClient.handleReply(InvocationClient.java:61)
    at com.yahoo.jrt.Connection.handlePackets(Connection.java:280)
    at com.yahoo.jrt.Connection.read(Connection.java:295)
    at com.yahoo.jrt.Connection.handleReadEvent(Connection.java:311)
    at com.yahoo.jrt.TransportThread.handleIOEvents(TransportThread.java:150)
    at com.yahoo.jrt.TransportThread.run(TransportThread.java:329)
    at com.yahoo.jrt.TransportThread$Run.run(TransportThread.java:24)
    at java.base/java.lang.Thread.run(Thread.java:840)

当前POM依赖 #

<dependency>
    <groupId>com.yahoo.vespa</groupId>
    <artifactId>documentapi</artifactId>
    <version>8.357.16</version> <!-- Find latest version at search.maven.org/search?q=g:com.yahoo.vespa%20a:documentapi -->
</dependency>

成因分析 #

1. 类加载器冲突
   com.yahoo.text.Utf8Array被两个不同的Felix Bundle类加载器实例加载，导致com.yahoo.component.Version的构造方法签名在不同类加载上下文下不兼容。Vespa 8.x对模块化结构进行了重构，核心组件的打包与依赖关系发生变化，若项目依赖树中存在重复的Vespa组件（如同时引入7.x和8.x版本），就会触发此类冲突。

2. Vespa 7到8的底层API变更
   虽然上层DocumentAPI的调用方式未明显变化，但底层MessageBus、JRT等通信组件的类加载隔离规则被调整，跨Bundle的类引用逻辑发生改变，导致原本兼容的类路径出现加载约束违反。

解决方法 #

1. 统一Vespa依赖版本 #

• 执行mvn dependency:tree查看完整依赖树，排查是否存在间接引入的旧版本Vespa组件。
• 使用Maven的dependencyManagement统一管理所有Vespa依赖版本，避免版本不一致：

  <dependencyManagement>
      <dependencies>
          <dependency>
              <groupId>com.yahoo.vespa</groupId>
              <artifactId>vespa-dependencies</artifactId>
              <version>8.357.16</version>
              <type>pom</type>
              <scope>import</scope>
          </dependency>
      </dependencies>
  </dependencyManagement>
  

• 若存在冲突的间接依赖，在documentapi依赖中排除重复组件：

  <dependency>
      <groupId>com.yahoo.vespa</groupId>
      <artifactId>documentapi</artifactId>
      <version>8.357.16</version>
      <exclusions>
          <exclusion>
              <groupId>com.yahoo.vespa</groupId>
              <artifactId>component</artifactId>
          </exclusion>
          <exclusion>
              <groupId>com.yahoo.vespa</groupId>
              <artifactId>text</artifactId>
          </exclusion>
      </exclusions>
  </dependency>
  

2. 调整OSGi类加载策略（若运行在Felix容器中） #

在Bundle的MANIFEST.MF中明确指定核心包的版本范围，确保统一加载：

Import-Package: com.yahoo.text, com.yahoo.component;version="[8.357.16,9)"

3. 验证DocumentAPI使用规范 #

• 确认DocumentAccess.createForNonContainer()在Vespa 8.x中的初始化逻辑是否有变更，按照官方规范调整初始化参数。
• 尝试改用同步Session（access.createSession()）测试，看是否能绕过冲突的异步通信路径。

验证步骤 #

1. 执行mvn clean install清理并重新构建项目，确保依赖完整且无版本冲突。
2. 用mvn dependency:analyze检查依赖的有效性，排除未使用或冗余的依赖。
3. 运行组件测试文档写入功能，确认LinkageError是否消失。

内容的提问来源于stack exchange，提问作者jiajia.liu