Dubbo 消費端 Eclipse 啟動報 ClassNotFoundException 但打包部署正常的根因與解決

Dubbo 微服務架構中，消費端在 Eclipse 內嵌 Tomcat 啟動拋出 NoClassDefFoundError: Lvaolon/facade/user/service/UserFacade，但打成 WAR 部署到外部 Tomcat 卻正常。這是典型的 Eclipse 發布部署路徑與 Maven 依賴傳遞不一致 導致的類加載問題。

錯誤堆棧核心信息

Caused by: java.lang.ClassNotFoundException: vaolon.facade.user.service.UserFacade
at org.apache.catalina.loader.WebappClassLoaderBase.loadClass(WebappClassLoaderBase.java:1856)

表明 UserFacade 接口類在 Web 應用類加載器中不可見。

根因分析

1. 接口與實現打包在同一模塊：vaolon-facade (接口) 與 vaolon-service (實現) 未分離，導致消費端引入服務端實現類
2. Eclipse WTP 發布機制缺陷：Deployment Assembly 未正確映射 Maven 依賴的 provided/compile scope，或 Maven Dependencies 庫未勾選導出
3. 類加載器隔離差異：外部 Tomcat 類加載器層級不同，掩蓋了依賴缺失問題

標準解決方案：拆分 API 模塊（推薦）

1. 模塊劃分

parent-project
├── vaolon-api          // 只包含接口、DTO、常量 (jar)
│   └── vaolon/facade/user/service/UserFacade.java
├── vaolon-service      // 服務實現，依賴 vaolon-api (war/jar)
│   └── impl/UserFacadeImpl.java
├── vaolon-consumer     // 消費端，依賴 vaolon-api (war)
│   └── controller/UserController.java
└── vaolon-common       // 通用工具 (可選)

2. 消費端 pom.xml 僅依賴 API

<dependency>
    <groupId>com.vaolon</groupId>
    <artifactId>vaolon-api</artifactId>
    <version>1.0.0</version>
</dependency>
<!-- 絕不直接依賴 vaolon-service -->

3. 服務端暴露接口

<dubbo:service interface="vaolon.facade.user.service.UserFacade" ref="userFacadeImpl" />

Eclipse 專項修復（不拆模塊的臨時方案）

1. 檢查 Deployment Assembly：專案右鍵 → Properties → Deployment Assembly → 確保 Maven Dependencies 勾選，且輸出路徑為 WEB-INF/lib
2. Maven 依賴範圍修正：接口模塊在消費端為 compile，服務端實現模塊在消費端不可見（或設為 provided 但不打包）
3. 清理重建：Maven → Update Project → Force Update + Project → Clean + 刪除 Server 發布目錄重新發布
4. Tomcat 發布配置：Server 編輯器 → Modules → 確認路徑正確，勾選 Auto reloading

最佳實踐總結

徹底解決此類問題的關鍵在於架構層面拆分 API 模塊，而非在 IDE 配置層面打補丁。這也是微服務治理的基礎準則。