Maven多模块项目正确结构需父POM设packaging=pom并声明modules，子模块通过parent继承且依赖由dependencyManagement统一版本管理，模块间依赖须单向向下、避免循环。
什么是Maven多模块项目的正确结构
不是把几个 pom.xml 放一起就叫多模块——核心在于父 POM 的 <packaging>pom</packaging> 声明和子模块的 <modules></modules> 列表。父模块本身不写业务代码，只负责统一管理版本、插件、依赖和构建生命周期。
常见错误是父模块设成 jar 或 war，导致 mvn clean install 报错 Non-resolvable parent POM；或子模块没在父 POM 的 <modules></modules> 中声明，IDE 无法识别为模块。
- 父项目
pom.xml必须含：<packaging>pom</packaging> <modules> <module>common</module> <module>service</module> <module>web</module> </modules>
- 每个子模块根目录下必须有独立
pom.xml，且含<parent>指向父项目坐标 - 子模块的
<groupId>通常继承父项目，<version>强烈建议用${project.parent.version}统一控制
如何避免依赖冲突和版本错乱
多模块里最常踩的坑是：子模块 A 依赖了 spring-boot-starter-web:2.7.18，子模块 B 又显式声明了 spring-boot-starter-web:3.1.0，结果编译时类加载失败或运行时报 NoClassDefFoundError。
根本解法是用 <dependencymanagement></dependencymanagement> 统一“锁定”版本，而不是靠子模块各自声明。
立即学习“Java免费学习笔记（深入）”；
- 所有第三方依赖（如 Spring Boot、MyBatis、Logback）只在父 POM 的
<dependencymanagement><dependencies></dependencies></dependencymanagement>中定义<groupId>、<artifactId>、<version>，不写<scope>和<optional> - 子模块中引用时只需写
<groupId>和<artifactId>，连<version>都不用写——Maven 自动按父 POM 的dependencyManagement补全 - 若某子模块需覆盖全局版本（极少数场景），可在其自身
<dependencies></dependencies>中显式指定<version>，但必须同步更新父 POM 的dependencyManagement注释说明原因
模块间依赖怎么写才不循环、不冗余
典型反模式：service 依赖 web，web 又依赖 service —— Maven 直接拒绝构建，报错 Failed to execute goal on project xxx: Could not resolve dependencies for project xxx: The projects in the reactor contain a cyclic reference。
模块职责必须清晰分层，依赖只能单向向下：
-
common：放实体类、工具类、常量、DTO，packaging=jar，无外部依赖（或仅provided级别） -
service：调用common，封装业务逻辑，可依赖 DAO 层（如mapper模块），但绝不依赖web或controller -
web：只依赖service和common，处理 HTTP 入口，返回 JSON，不写任何 service 逻辑 - 模块间依赖写在子模块自己的
pom.xml的<dependencies></dependencies>中，用完整坐标：<dependency> <groupId>com.example</groupId> <artifactId>common</artifactId> <version>${project.parent.version}</version> </dependency>
IDEA 中模块识别失败或编译报红怎么办
即使 pom.xml 结构完全正确，IntelliJ IDEA 也可能显示 “Project JDK not configured” 或子模块标红，本质是 Maven 导入未触发或缓存错乱。
不要反复点击 “Reload project”，先确认三件事：
- 父项目根目录下执行过
mvn compile？这是验证 POM 语法和模块关系是否合法的第一步，比 IDE 更早暴露问题 - IDEA 中 File → Project Structure → Project Settings → Project → Project SDK 是否指向有效 JDK（不是 JRE），且 Language level ≥ 模块要求（如
service用 Java 17，则不能选 8） - 右键父项目 → Maven → Reload，**不是** “Reimport”；若仍无效，删掉项目根目录下的
.idea和*.iml文件，重新 Import Project → 选中父项目pom.xml→ 勾选 “Import Maven projects automatically”
真正麻烦的是跨模块调试时找不到源码——确保每个子模块的 pom.xml 中都配置了 maven-source-plugin，否则 debug 进 common 方法时只会看到 “Source not found”。
