多模块SpringBoot项目如何正确打包成WAR？

Question

在多模块SpringBoot项目中，将子模块打包为WAR文件时，常遇到主应用无法正确识别Web启动类或内嵌容器未正确配置的问题。典型表现为部署到外部Tomcat时抛出“NoClassDefFoundError”或“Failed to start bean”的错误。其根源往往在于：未将主模块的打包方式设为`war`、缺少对`SpringBootServletInitializer`的继承实现、或依赖模块未正确引入`spring-boot-starter-web`。此外，Maven的模块聚合与依赖管理配置不当，也会导致构建后的WAR缺失必要类文件或配置资源。如何正确配置父POM及子模块的构建插件，成为成功打包的关键。

Answer 1

多模块SpringBoot项目中子模块打包为WAR的深度解析与实践

1. 问题背景与典型表现

在企业级Java应用开发中，使用Spring Boot构建微服务架构已成为主流。然而，在某些场景下（如需集成传统Web容器、满足安全审计要求或兼容遗留系统），开发者仍需将Spring Boot应用打包为WAR文件并部署至外部Tomcat等Servlet容器。

当项目采用多模块结构时，主模块依赖多个子模块，若配置不当，极易出现以下异常：

• NoClassDefFoundError: org/springframework/boot/web/servlet/context/AnnotationConfigServletWebServerApplicationContext
• Failed to start bean 'webServerStartStop'; nested exception is java.lang.NoSuchMethodError
• 部署后访问路径404，或上下文未正确加载

这些错误的根本原因往往不是单一的代码问题，而是构建配置、依赖传递和启动机制之间的协同失效。

2. 核心原理：Spring Boot WAR包的运行机制

Spring Boot默认以内嵌Tomcat方式运行（JAR模式）。要支持外部Servlet容器，必须通过实现SpringBootServletInitializer接口，使应用能被Servlet容器识别为标准Web应用。

该类会重写configure方法，引导Spring Boot应用上下文在Servlet环境中初始化，并确保自动配置、条件注解等功能正常工作。

运行模式	入口类要求	内嵌容器	部署方式
JAR	@SpringBootApplication	内置Tomcat/Jetty	java -jar
WAR	继承SpringBootServletInitializer	由外部容器提供	部署到Tomcat等

3. 常见错误根源分析

1. 主模块<packaging>未设置为war
2. 主应用启动类未继承SpringBootServletInitializer
3. 子模块缺少spring-boot-starter-web依赖，导致Web环境组件缺失
4. Maven聚合模块中依赖范围（scope）误设为provided，影响类路径
5. 父POM中未统一管理Spring Boot版本，引发依赖冲突
6. 资源文件未正确包含在构建输出中
7. 插件配置遗漏repackage目标
8. 模块间依赖未显式声明，造成类找不到
9. Tomcat版本与Spring Boot不兼容（如使用Tomcat 7运行Spring Boot 3+）
10. IDE缓存未清理，编译输出陈旧

4. 解决方案：分层配置策略

4.1 父POM配置规范

确保所有子模块共享一致的依赖管理和插件配置。

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>multi-module-parent</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>

  <modules>
    <module>common-module</module>
    <module>web-module</module>
  </modules>

  <properties>
    <spring-boot.version>3.1.5</spring-boot.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-dependencies</artifactId>
        <version>${spring-boot.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.springframework.boot</groupId>
          <artifactId>spring-boot-maven-plugin</artifactId>
          <version>${spring-boot.version}</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
</project>

4.2 主模块（可执行WAR模块）配置

主模块应为最终打包模块，其pom.xml需明确指定打包类型及Servlet初始化器。

<packaging>war</packaging>

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <!-- 子模块依赖 -->
  <dependency>
    <groupId>com.example</groupId>
    <artifactId>common-module</artifactId>
    <version>1.0.0</version>
  </dependency>
  
  <!-- 提供Servlet容器API，但不打包进WAR -->
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-tomcat</artifactId>
    <scope>provided</scope>
  </dependency>
</dependencies>

4.3 启动类实现SpringBootServletInitializer

这是WAR模式启动的关键一步。

@SpringBootApplication
public class Application extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) {
        return builder.sources(Application.class);
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

5. 构建流程可视化

graph TD A[父POM定义] --> B[子模块继承] B --> C{是否为主模块?} C -- 是 --> D[设置packaging=war] C -- 是 --> E[引入spring-boot-starter-tomcat with provided] C -- 是 --> F[继承SpringBootServletInitializer] D --> G[Maven构建] E --> G F --> G G --> H[生成可部署WAR] H --> I[部署至外部Tomcat] I --> J[Servlet容器调用onStartup] J --> K[Spring Boot上下文初始化] K --> L[Web MVC注册完成]

6. 验证与调试建议

为确保构建结果正确，可采取如下措施：

• 解压生成的WAR文件，检查WEB-INF/lib目录是否包含所有必要JAR包
• 确认WEB-INF/classes中存在主启动类和配置文件
• 查看META-INF/MANIFEST.MF中的Main-Class是否指向org.springframework.boot.loader.WarLauncher
• 在Tomcat日志中搜索Tomcat started on port(s)以判断是否成功启动
• 使用mvn dependency:tree分析依赖传递是否完整
• 启用Maven调试模式：mvn clean package -X
• 对比JAR与WAR构建输出差异
• 测试在不同版本Tomcat（8.5/9.0/10.0）下的兼容性
• 检查IDE项目结构是否同步Maven配置
• 验证spring-boot-maven-plugin是否执行了repackage任务