JAVA后端开发——多模块项目重命名体系解析

在使用多模块 Spring Boot 项目时，我们经常会遇到这样一个问题：

在 IDEA 中右键模块 → 重命名，会看到三个选项：

• 重命名模块（Rename Module）
• 重命名目录（Rename Directory）
• 重命名模块和目录（Rename Module & Directory）

与此同时，Maven 多模块项目中又存在：

• <artifactId>
• <module>
• 目录名

这些"名字"看起来很像，但其实完全不是一个体系。

如果不搞清楚，在做项目改造（比如改项目名、拆模块）时，很容易踩坑。

---

一、IDEA 的三个"重命名"到底在改什么？

1、重命名模块（Rename Module）

👉 修改的是：

IDEA 的 Module 名（IDE 内部标识）

特点：

• 只影响 IDEA
• 不影响 Maven
• 不影响目录
• 不影响 pom.xml

本质是改：

.iml 文件 + .idea/modules.xml

👉 可以理解为：IDE 里的"显示名 / 逻辑名"

---

2、重命名目录（Rename Directory）

👉 修改的是：

操作系统里的文件夹名称

例如：

order-service → order-service-new

特点：

• 会影响 Maven（因为路径变了）
• 不会自动修改 pom.xml
• 不会改 <module>

👉 本质是：改物理路径

---

3、重命名模块和目录（Rename Module & Directory）

👉 同时做两件事：

• 改 IDEA Module 名
• 改文件夹名

但注意：

❗ 仍然不会修改 Maven 的 pom.xml

---

二、Maven 多模块中的"名字体系"

一个模块在 Maven 中，其实有三种"名字"：

---

1、<artifactId>（最核心）

<artifactId>order-service</artifactId>

👉 作用：

• 唯一标识模块（配合 groupId）
• 生成的 jar 名
• 依赖引用使用

👉 这是 Maven 世界的"真正名字"

---

2、<module>（父工程引用）

<modules>
    <module>order-service</module>
</modules>

👉 本质：

目录路径（相对路径）

Maven 会去找：

./order-service/pom.xml

---

3、目录名（文件夹）

order-service/

👉 作用：

• 被 <module> 引用
• 组织代码结构

---

三、三者关系总结（核心认知）

名称	属于谁	是否影响构建	本质
Module 名（IDEA）	IDEA	❌	IDE 标识
目录名	文件系统	✅	路径
<module>	Maven	✅	路径引用
<artifactId>	Maven	✅	构建坐标

---

四、为什么会"改了目录就报错"？

因为：

👉 <module> = 目录路径

如果你只改：

order-service → order-service-new

但父 POM：

<module>order-service</module>

👉 Maven 会找：

./order-service/pom.xml ❌（不存在）

于是报错：

Child module does not exist

---

五、实战：多模块项目重命名（ruoyi → mobilecom）

假设你的项目结构：

ruoyi/
 ├── ruoyi-admin
 ├── ruoyi-system
 ├── ruoyi-common
 └── pom.xml

现在你要改成：

mobilecom/
 ├── mobilecom-admin
 ├── mobilecom-system
 ├── mobilecom-common

---

1、改造步骤（推荐顺序）

---

第一步：修改根工程（父 POM）

<artifactId>mobilecom</artifactId>

同时：

<modules>
    <module>mobilecom-admin</module>
    <module>mobilecom-system</module>
    <module>mobilecom-common</module>
</modules>

---

第二步：修改子模块 artifactId

例如：

<artifactId>ruoyi-admin</artifactId>

改为：

<artifactId>mobilecom-admin</artifactId>

所有模块都要改。

---

第三步：修改目录名（非常关键）

ruoyi-admin → mobilecom-admin
ruoyi-system → mobilecom-system

---

第四步：修改父子引用关系

子模块中：

<parent>
    <groupId>xxx</groupId>
    <artifactId>ruoyi</artifactId>
</parent>

改为：

<artifactId>mobilecom</artifactId>

---

第五步：全局搜索替换（按需替换）

搜索：

ruoyi

可能涉及：

• 包名（package）
• 配置文件（yml）
• 日志路径
• 前端接口路径

---

第六步：重新导入 Maven

在 IDEA：

Reload Maven Project

---

2、常见坑

❌ 只改目录

👉 父 <module> 没改 → 直接炸

---

❌ 只改 artifactId

👉 依赖引用全失效

---

❌ 忘记改 parent

👉 子模块找不到父工程

---

❌ 本地缓存问题

建议执行：

mvn clean install -U

---

六、推荐最佳实践

1、命名统一原则

artifactId = 目录名 = Module 名（IDEA）

例如：

mobilecom-admin/
artifactId: mobilecom-admin
Module: mobilecom-admin

---

2、展示名称用 <name>

<name>移动通信后台服务</name>

---

七、总结

IDEA 的 Module 是"开发视角"，Maven 的 artifactId 是"构建视角"，而 <module> 只是"路径"。
改名字本质上不是"改一个地方"，而是要同时修改：路径、引用关系、构建坐标。