Maven多模块项目正确结构是：父模块packaging必须为pom，子模块路径在父pom的<modules>中显式声明且目录需在父模块下；子模块通过<parent>继承版本与插件，依赖需在各自pom中声明才能生效。
什么是Maven多模块项目的正确结构
多模块项目不是把多个 pom.xml 放进不同文件夹就完事。核心是：一个父模块（pom packaging 为 pom）统一管理子模块的版本、插件和依赖，子模块必须在父模块的 <modules></modules> 中显式声明。
常见错误是子模块目录不在父模块下，或父模块的 packaging 写成 jar —— 这会导致 Maven 完全忽略 <modules></modules> 配置，子模块压根不参与构建。
- 父模块根目录下必须有
pom.xml，且<packaging>pom</packaging> - 所有子模块路径写在父
pom.xml的<modules></modules>里，如：<module>user-service</module> - 子模块的
<parent></parent>必须指向父模块的groupId+artifactId+version，不能只写坐标不写<relativepath></relativepath> - 推荐将
<relativepath></relativepath>显式设为空：<relativepath></relativepath>，避免 Maven 错误向上查找
子模块如何继承父模块的依赖与插件
父模块的 <dependencymanagement></dependencymanagement> 只做**版本仲裁**，不引入实际依赖；子模块需在自己 pom.xml 中声明 <groupid></groupid> 和 <artifactid></artifactid> 才会真正引入——这点极易混淆，导致编译报 ClassNotFoundException。
插件同理：<pluginmanagement></pluginmanagement> 在父模块中统一配置插件版本和默认参数，但子模块必须在自己的 <build><plugins></plugins></build> 中显式写出插件坐标，才会生效。
立即学习“Java免费学习笔记（深入）”；
- 父模块用
<dependencymanagement></dependencymanagement>管理 Spring Boot 版本：<artifactid>spring-boot-dependencies</artifactid>，子模块只需写<dependency><groupid>org.springframework.boot</groupid><artifactid>spring-boot-starter-web</artifactid></dependency>即可 - 若子模块需要跳过测试，应在自己
pom.xml中写：<plugin><groupid>org.apache.maven.plugins</groupid><artifactid>maven-surefire-plugin</artifactid><configuration><skiptests>true</skiptests></configuration></plugin> - 避免在父模块的
<dependencies></dependencies>中直接写依赖（除非是所有子模块共用的 API 模块），否则会强制所有子模块都引入该依赖
模块间依赖怎么写才不会循环或失败
子模块之间依赖必须用 compile 范围（默认），且依赖的模块必须已安装到本地仓库或在同一构建中被先编译。最常踩的坑是：A 模块依赖 B，但 B 尚未构建，又没执行 mvn install，直接运行 A 会提示 Could not find artifact。
更隐蔽的问题是“隐式传递依赖”：B 模块依赖了 C 的某个旧版 jar，而 A 模块又直接依赖新版 C —— 此时 Maven 默认按“第一声明优先”策略选旧版，导致 A 运行时报 NoSuchMethodError。
- 模块间依赖写法：
<dependency><groupid>com.example</groupid><artifactid>common-utils</artifactid><version>${project.version}</version></dependency>，用${project.version}确保版本同步 - 禁止用
system范围或systemPath引入 jar，这会让模块无法被其他机器构建 - 检查循环依赖：用
mvn dependency:tree -Dverbose查看依赖链，若出现 A → B → A，则必须拆分或引入中间接口模块
IDEA 中刷新/导入多模块项目的关键动作
IDEA 不会自动识别父子关系，单纯打开父目录 ≠ 正确导入多模块项目。常见现象是：父 pom.xml 显示 “Maven project”，但子模块只是普通文件夹，没有小蓝标，也无法右键运行 mvn clean compile。
根本原因是 IDEA 没触发 Maven import 流程，或缓存了旧配置。此时靠“Reload project”按钮往往无效，必须重置上下文。
- 关闭项目后，彻底删除项目根目录下的
.idea文件夹和所有*.iml文件 - 重新打开父模块根目录，选择 “Open as Project” → 勾选 “Import project from external model” → 选 Maven
- 确保勾选 “Search for projects recursively”，否则子模块不会被发现
- 导入完成后，在 Maven 工具窗口检查是否列出所有子模块，每个模块节点下应有
clean、compile等生命周期命令
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>parent-project</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
<module>user-service</module>
<module>order-service</module>
<module>common-utils</module>
</modules>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.2.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
</project>
模块名拼错、relativePath 指向偏差、IDE 缓存残留——这三个点卡住的人最多。别急着查文档，先确认父 pom 是否真被识别为 packaging=pom，再看 IDEA 的 Maven 面板有没有列出全部子模块。别的都可以调，这个结构对不上，后面全是白忙。
