企业官网建设流程全解析

1. 先想清楚：父子项目到底解决什么问题

很多人一上手就在 IDEA 里点新建、点下一步，把一堆模块堆起来，结果版本号四处散落、依赖冲突排查到半夜。Maven 父子项目（多模块工程）本质上是两件事叠在一起：聚合和继承。聚合解决的是“一次命令行能把多个模块按正确顺序构建完”，继承解决的是“多个模块共享同一套版本、插件和编译配置”。这两件事在 POM 里分别对应<modules>和<parent>，它们可以同时存在，也可以只取其一，但绝大多数业务项目会选择合体，因为维护成本最低。我自己带过的几个中台型项目，早期都是单模块硬扛，等到拆出通用工具包和对外接口层时，代码开始互相引用，构建时间从两分钟涨到十几分钟，那一刻才真正体会到父子结构的价值。

它适合谁？如果你的项目只有一个可执行入口、依赖不超过二十个、永远不会被其他项目复用，那单模块反而是最舒服的选择，别为了架构感强行拆。但只要出现下面任意一种情况，父子结构基本就是必需品：多个可独立部署的服务共享一套实体定义、需要把工具类单独打成 jar 给兄弟团队用、前端资源和后端接口要分开打包、测试代码需要跨模块复用。

1.1 单模块工程撑不住的三类信号

第一类是代码分层开始用包名硬凑。controller、service、dao 全塞在一个 src 下，随着业务堆叠，一个包底下挂两百个类，IDE 索引都变慢。这时候你会本能地想按业务域拆目录，但拆完还是同一个 jar，谁也说不清哪个类属于哪个域。第二类是依赖版本失控，两个开发同时在 pom 里加不同版本的同名库，合并代码时才发现冲突，运行时抛 NoSuchMethodError，排查成本极高。第三类是构建粒度太粗，改一行工具类代码，整个工程从编译到打包跑一遍，五分钟没了。

这三类信号出现之后，父子项目带来的收益就很直接：依赖版本收口到父 POM 一处改全生效、模块边界由目录物理隔离、增量构建只跑受影响模块。代价是前期多花半小时搭骨架，以及新人第一次拉代码时需要理解“为什么这里有两层 pom”。这笔账怎么算都划算。

1.2 聚合与继承是两件事，别混为一谈

这是我最常被问到的问题。聚合只发生在父工程的<modules>标签里，它告诉 Maven“这些子目录也是构建目标”，父工程自己不需要写一行 Java 代码，只需要packaging为pom。继承发生在子工程的<parent>标签里，它告诉 Maven“去这个坐标的 POM 里把 properties、dependencyManagement、pluginManagement 拿过来用”。一个子模块完全可以在别的仓库里，通过<parent>继承某个公司级基础 POM，同时不被父工程的<modules>收录。

理解这一点的实际意义在于：当你要给子模块单独发布、或者把一个模块迁到别的工程时，你只需要关心<parent>能不能解析到，而不必担心<modules>的结构。反过来，如果只想一键构建但不想共享配置，那就只在父 POM 里写<modules>，子模块不写<parent>，这种“纯聚合”结构在混合技术栈的项目里很常见。

1.3 目录结构与命名约定怎么定

我习惯的布局是父目录下pom.xml加若干平级子目录，每个子目录一个模块，不嵌套第二层。嵌套过深会让relativePath变长，出问题时排查路径很痛苦。命名上用项目名-模块职责的形式，比如demo-common、demo-api、demo-web、demo-job，一眼能看出依赖方向。groupId 统一为com.example.demo（这是示例占位，实际按团队规范来），artifactId 用上面的模块名，版本号全部继承父工程，子模块里一个version都不写。

注意：如果父目录本身也是一个 Git 仓库根，记得在.gitignore里把各模块的target/和根目录的.idea/排除掉，否则每次构建都会产生一堆噪音文件，代码评审时很难看。

这套约定最大的好处是可预测。任何人拿到工程，先看根目录有哪些子目录，再看父 POM 的<modules>顺序，基本就能画出模块依赖图。相反，如果子目录名字是core、biz、app这种泛称，三个月后没人说得清core到底依赖谁。

2. 骨架落地：IDEA 里的创建路径与目录约定

IDEA 提供好几条路径能到达同一个结果，但踩坑概率差别很大。我推荐的做法是先在文件系统层面把目录和父 POM 建好，再用 IDEA 打开根目录让它自动识别，而不是全程依赖图形向导。原因很简单：向导会顺手往 POM 里塞一堆你并不需要的东西，比如默认的maven-compiler-plugin版本、junit依赖、maven-site-plugin，甚至会把packaging写错。手工建再让 IDEA 索引，整个过程可控，出问题也容易定位。

具体操作是：新建一个空目录作为工程根，在里面建pom.xml写好父工程坐标和packaging，然后建子目录，每个子目录里建最小可用的pom.xml，最后用 IDEA 的 Open 打开根目录。IDEA 检测到根目录有pom.xml，会弹窗询问是否作为 Maven 工程导入，点确认后右下角会有进度条解析依赖。等索引跑完，右侧 Maven 面板里就会出现聚合树，父节点下面挂着各个模块，这时候骨架就算成了。

2.1 路径一：先建父工程再插模块（推荐）

这是最稳的顺序。第一步，根目录pom.xml只写最小内容：modelVersion、groupId、artifactId、version、packaging为pom，外加空的<modules>。第二步，创建子目录，每个子目录写自己的 POM，<parent>里填父工程坐标，relativePath指向../pom.xml。第三步，回到父 POM 把模块名填进<modules>，IDEA 会自动刷新。

这个顺序的关键在于每一步都是可构建的。父 POM 建完就能mvn validate通过，子模块加一个就能构建一个，不会出现“全写完才发现 parent 解析不到”的窘境。我见过有同事先把五个模块的 POM 全写完再一起刷新，结果其中一个artifactId拼错，报错信息指向父 POM 找不到，排查了二十分钟。

2.2 路径二：IDEA 的 New Module 直连父 POM

在父工程已经导入 IDEA 的前提下，右键根节点 → New → Module，选择 Maven，填写 artifactId，IDEA 会自动生成目录结构并把模块追加到父 POM 的<modules>里，同时写好<parent>。这条路径效率高，但有两个细节必须检查：一是它生成的relativePath有时会被省略，虽然默认值就是../pom.xml，但如果你的目录结构不是标准的一层，就会出现解析问题；二是它默认会给你加一个空的src/main/java和src/test/java，如果这个模块只是纯 POM 的聚合层，记得删掉，否则空目录会被打成空 jar。

我一般会用这条路径快速生成骨架，然后立刻打开生成的 POM 手工精简一遍。用向导省下的时间，远远小于后面排查“为什么多了一个没用的插件”的时间。

2.3 父 POM 该写什么、不该写什么

这是决定后续维护体验的分水岭。父 POM该写的：模块列表、统一版本号属性、dependencyManagement里的依赖版本、pluginManagement里的插件版本和配置、编码与 JDK 版本属性、仓库和分发配置（如果团队有私有仓库）。父 POM不该写的：<dependencies>里的实际依赖（这会把依赖强制注入所有子模块，哪怕它根本用不上）、spring-boot-maven-plugin的实际执行配置（会导致所有子模块尝试 repackage）、任何业务相关的资源目录配置。

一个很典型的反面案例：有人在父 POM 的<dependencies>里加了lombok，觉得“反正大家都要用”。结果某个纯接口定义的模块被打上了 lombok 的注解处理器，编译期行为发生变化，线上排查了半天。父 POM 的定位是契约，不是杂物间。

3. 父 POM 逐项拆解：哪些配置该集中，哪些必须下放

先把一个我实际在用的父 POM 骨架贴出来，然后逐块讲为什么这么写。坐标部分用示例占位，实际替换成团队的规范即可。

<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.demo</groupId> <artifactId>demo-parent</artifactId> <version>1.0.0-SNAPSHOT</version> <packaging>pom</packaging> <modules> <module>demo-common</module> <module>demo-api</module> <module>demo-web</module> </modules> <properties> <java.version>17</java.version> <maven.compiler.source>${java.version}</maven.compiler.source> <maven.compiler.target>${java.version}</maven.compiler.target> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> <spring.boot.version>3.2.0</spring.boot.version> </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.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <version>3.11.0</version> <configuration> <release>${java.version}</release> <encoding>UTF-8</encoding> </configuration> </plugin> </plugins> </pluginManagement> </build> </project>

这段配置里每一个标签都有明确用途，下面拆开讲。

3.1 packaging 必须是 pom，且不能漏

父工程不产出任何构件，它的packaging只能是pom。这个值决定了两件事：Maven 不会尝试给它绑定compile、jar这些生命周期目标；IDEA 在 Maven 面板里会把它渲染成聚合节点而不是普通模块。如果漏写，Maven 会默认用jar，然后在构建时尝试为一个只有pom.xml的目录打包，抛出 “You have to use a classifier” 或者干脆生成一个空 jar 并安装到本地仓库，后续所有依赖它的模块拿到的都是空包，报ClassNotFoundException。

我遇到过一次真实事故：同事复制了子模块的 POM 改造成父 POM，忘了改packaging，本地构建一切正常（因为他先跑了子模块），等到持续集成环境从头构建时才暴露，白白浪费一个下午。所以这条检查现在是我看任何新工程的第一个动作。

3.2 dependencyManagement 的锁版本逻辑

<dependencyManagement>的语义是声明而不引入。它只规定“如果你用了这个依赖，就用这个版本”，但不会真的把 jar 加进 classpath。子模块要用的时候，必须自己写<dependency>，只需要groupId和artifactId，version留空自动继承。这一层间接性带来的最大好处是版本收敛：升级 Spring Boot 只需要改父 POM 的一个属性，所有子模块自动跟随。

有个细节很多人不清楚：子模块一旦自己写了version，就会覆盖父的声明，而且不会有任何警告。所以我在评审时特别留意子模块 POM 里有没有多余的version，尤其是复制粘贴来的依赖。另外，dependencyManagement也支持对同一依赖多次声明，后写的会赢，但这个行为在不同 Maven 版本上有细微差异，不值得依赖，看到重复声明一律要求删掉。

3.3 pluginManagement 与编译插件版本

<pluginManagement>和dependencyManagement的思路一致：声明版本和配置，不实际执行。这解决了一个非常隐蔽的问题——Maven 对某些插件有内置的默认版本绑定，比如maven-compiler-plugin在很老的版本上默认用 JDK 1.5 编译，你明明装了 JDK 17，构建出来的 class 文件版本却是 49，运行时报UnsupportedClassVersionError。显式在pluginManagement里锁死版本，并且用<release>而不是<source>/<target>，能同时保证字节码版本和 API 检查都对齐。

提示：<release>参数需要 JDK 9 以上才支持，它比<source>+<target>更严格，会同时校验你调用的 API 是否在该版本存在。如果你的项目还在用 JDK 8，只能用<source>/<target>，那就要靠团队自查了。

还有一个高频问题：spring-boot-maven-plugin。这个插件的repackage目标只能绑定在真正有main方法的模块上。如果你把它写在父 POM 的<build><plugins>里（注意不是pluginManagement），所有子模块都会尝试 repackage，工具类和接口模块直接报 “Unable to find main class”。正确做法是只在父 POM 的pluginManagement里声明版本，在可执行模块的<build><plugins>里引用。

3.4 properties 与 BOM 导入的取舍

Spring Boot 的 BOM 通过<scope>import</scope>导入到dependencyManagement，这是最省事的版本管理方式，一次导入几百个依赖的版本都对齐了。但要注意import只能在dependencyManagement里使用，写在普通<dependencies>里会直接报错。另外，BOM 导入的顺序有讲究：先导入的优先，如果你在 BOM 之前写了某个依赖的版本，那么 BOM 里同名的不会被覆盖。所以自定义版本要写在 BOM 之后，或者干脆用属性覆盖的方式（比如覆盖spring-boot内部定义的版本属性），后者更稳妥。

属性区还有一个容易被忽略的点：project.build.sourceEncoding如果你不写，某些平台上默认是平台编码，中文注释在编译时会乱码，日志里出现问号，排查起来非常费劲。这条基本属于“写了没感觉，不写必踩坑”的配置。

4. 模块依赖、构建顺序与命令行的正确用法

骨架搭好之后，真正决定体验的是模块之间的依赖关系怎么表达。子模块 A 依赖子模块 B，只需要在 A 的 POM 里写 B 的坐标，版本继承父工程。Maven 在构建时会做拓扑排序，自动先构建 B 再构建 A，你不需要手工调整<modules>的顺序。这一点很多人误解，以为<modules>的顺序决定构建顺序，实际上它只影响列出顺序，真正的顺序由依赖图算出来。

4.1 依赖传递与 scope 的坑

默认的compilescope 会传递：A 依赖 B，B 依赖 C，那么 A 的 classpath 上也会有 C。这在工具模块里是灾难，因为你会不知不觉把 B 的实现细节暴露给 A。我的原则是：工具类模块对外只暴露最小接口，第三方实现库一律标runtime或provided。比如demo-common里用了某个 JSON 序列化库，但对调用方来说是实现细节，那就不要让它以compile传递出去，否则上层模块升级版本时会打架。

另一个高频坑是testscope 不能被传递。有人在demo-common里写了测试基类，想让其他模块复用，结果发现找不到类。这不是配置问题，是 Maven 的设计：test依赖不参与传递。要复用得把测试工具单独做成一个模块，用普通compile依赖引入，或者用maven-jar-plugin打一个 test-jar 再用classifier引用，后者配置繁琐，我更倾向单独建模块。

4.2 reactor 构建顺序与循环依赖

Maven 把一次构建涉及的所有模块称为 reactor（反应堆）。当你在根目录执行mvn clean install，reactor 会包含所有<modules>里的模块，按依赖关系排序后依次构建。如果两个模块互相依赖，Maven 会直接报 “The projects in the reactor contain a cyclic reference”，并且把循环链路打印出来。

循环依赖几乎总是设计问题，不是配置问题。常见的场景是：demo-api里定义接口时用到了demo-common的某个 DTO，而demo-common又为了图方便引用了demo-api的常量类。解决办法是把共享的 DTO 和常量下沉到demo-common，或者再抽一层demo-contract。强行用provided或optional绕过只会把问题推到运行时。

4.3 打包、安装、部署的命令与参数

命令行参数用熟了能省大量时间，下面这几个是我每天都在用的：

-pl配-am的组合是提效关键。全量构建十个模块要三分钟，只构建受影响链条可能只要四十秒。但要注意-am会连带构建上游，如果上游模块有编译错误，你依然会失败，这反而是好事，能提前发现。

5. 打包与发布的实操链路

构建通过只是第一步，能不能正确产出可运行的东西是另一回事。可执行模块（比如demo-web）需要spring-boot-maven-plugin的repackage目标把依赖打进 fat jar，而普通模块只产出瘦 jar。这个区分必须在 POM 里明确表达，否则会出现“jar 里没有依赖，运行报 NoClassDefFoundError”或者“jar 有八十兆，里面塞了三份重复的库”。

5.1 可执行模块的插件配置写法

在demo-web的 POM 里这样写：

<build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <executions> <execution> <goals> <goal>repackage</goal> </goals> </execution> </executions> </plugin> </plugins> </build>

插件版本继承父 POM 的pluginManagement，这里只声明执行目标。repackage会把原有 jar 重命名为xxx.jar.original，把带依赖的新 jar 放在原位置。如果你发现打出来的 jar 只有几十 KB，八成是插件没生效或者被别的插件覆盖了。

5.2 子模块被依赖时的 install 时机

IDEA 内部解析模块依赖走的是自己维护的模型，不需要 install 也能编译通过。但命令行和持续集成环境不一样，它们必须从本地仓库或远程仓库解析。所以会出现“IDEA 里好好的，命令行报找不到 demo-common:1.0.0-SNAPSHOT”的情况。解决办法很简单：在根目录跑一次mvn install，把快照版装进本地仓库。

这个差异也解释了另一个常见现象：同事改了公共模块没 install，你拉代码后编译用的是仓库里的旧快照，行为对不上。养成习惯，动公共模块后先 install，再动业务模块。这个动作虽然朴素，但省掉的沟通成本远超那几十秒。

5.3 版本号管理与快照策略

开发期统一用-SNAPSHOT后缀，这是 Maven 的约定，代表“这个版本可能变”。发布时换成正式版本号，并把所有子模块的版本一次性改掉。手工改容易漏，推荐用versions-maven-plugin的set和update-child-modules目标批量处理，或者更进一步用revision属性配合flatten-maven-plugin，让版本号只在一个地方定义。

快照版的更新策略也值得说一句：Maven 默认每天检查一次远程快照更新，如果你希望每次构建都拉最新，加-U参数强制更新。但持续集成环境不建议加-U，否则构建结果不可复现，出问题无法回溯。我一般只在本地调试跨模块改动时才用。

6. 常见问题与排查实录

父子工程报错信息往往很长，但真正有用的就一两行。下面这张表是我这几年整理出来的高频问题，基本覆盖了八成的踩坑场景。

6.1 三个最容易被忽略的细节

第一个是IDEA 的模块忽略状态。有时候你在 Maven 面板里右键某个模块误点了 “Ignored Files”，之后这个模块就不参与编译，代码全红但命令行构建正常。排查方式是打开 Settings → Build Tools → Maven → Ignored Files，看列表里有没有被勾上的 POM。这个坑我自己踩过两次，第二次才记住。

第二个是Maven 面板没刷新。手工改了 POM 之后，IDEA 有时只提示一个小的刷新图标，如果你没点，它还在用旧模型，表现为“明明加了依赖还是找不到”。习惯是改完 POM 就按一下刷新，或者开启自动导入。

第三个是JDK 与 Language Level 不同步。Project Structure 里 SDK 设成 17，但 Module 的 Language Level 还是 8，写新语法就报错，而 Maven 命令行构建没问题。这两处要一起改，maven.compiler相关属性只影响命令行构建，不影响 IDEA 的语法检查。

6.2 独家避坑心得

我总结出来最有效的一条是：每次结构变更后，先在命令行验证，再回 IDEA。因为命令行是“裸”的，没有 IDEA 的缓存和模型加持，能暴露最真实的问题。具体做法是打开终端，在根目录跑mvn -q clean package -DskipTests，看是否能一路通过。能过，再回 IDEA 刷新；不能过，就盯着错误行改，改完再跑。这个循环比在 IDEA 里点来点去看红波浪线高效得多。

另一条是给父 POM 写注释。听起来很土，但真的有用。在dependencyManagement里每个依赖块上方写一句为什么锁这个版本、什么时候可以升，半年后的你会感谢现在的你。我在一个项目里留了这样一条注释：“此版本锁定是因为 2.4 之后移除了某方法，等上游适配再升”，后来升级时直接省掉了一次回归测试。

7. 工程化收尾：版本号、构建缓存与团队协作约定

骨架能跑起来之后，真正拉开差距的是工程化细节。一个十来人的团队，如果每个人对父子结构的理解不一致，半年内 POM 一定会变成一锅粥。我通常会在项目初期就把几条硬规矩写进 README，并且在代码评审中严格执行。

7.1 版本号只允许在父 POM 出现

这条规矩的收益非常大。所有子模块的version一律不写，靠<parent>继承。需要改版本时，只改父 POM 一处，然后跑一次批量更新子模块引用的命令。如果团队用 Git 分支模型，建议在发布分支上改版本号，改完立刻验证一遍全量构建，避免出现“父 POM 升了、某个子模块还引用旧版本”的错位。

更进一步可以用 CI 友好的版本方案：在父 POM 定义<revision>属性，<version>引用它，再配合 flatten 插件在打包时把变量展开。这样构建时可以用-Drevision=1.2.3动态指定版本，持续集成流水线不需要改文件就能出不同版本的包。

7.2 让持续集成只构建变更模块

模块多了以后，每次提交全量构建是浪费。可以在流水线里加一步，用git diff找出改动的目录，映射到模块名，再用-pl ... -am只构建受影响的部分。实现方式有很多，最朴素的是写个脚本按路径前缀匹配模块名。这套东西不复杂，但能把流水线时间砍掉一半以上。

需要提醒的是，公共模块（比如demo-common）一旦变更，理论上所有下游都受影响，这时候不能只构建直接依赖，得用-amd把整个下游都带上。所以脚本里要区分“叶子模块”和“基础模块”，对后者走全量或下游全量策略。

7.3 新人上手的最小路径

我会在 README 里写清楚三步：第一步，克隆代码，用 IDEA 打开根目录，等待索引完成；第二步，在终端执行mvn clean install -DskipTests，确保本地仓库里有全部快照；第三步，在 IDEA 里启动可执行模块的启动类。这三步走完基本就能跑起来。

如果还有问题，大概率是环境差异，比如 JDK 版本不对、Maven 版本太老、settings.xml里的仓库配置不一致。我一般会额外提供一个mvn -v的输出模板，让新人对照着看，比一句“你环境有问题”有用得多。

7.4 我在实际项目里的几点体会

父子项目最大的价值不是“看起来像个正经工程”，而是把散落在各处的版本约定收敛到一处。我经历过一次跨模块的依赖冲突，某个日志库在两个模块里版本不同，运行时行为不一致，排查了两天才定位到。后来把所有版本收进父 POM 的dependencyManagement，同类问题再没出现过。

另一个体会是不要过度拆分。我见过把每个实体类拆成一个模块的极端案例，结果构建图复杂到没人能看懂，改一个字段要动五个 POM。模块的粒度应该跟着“变更频率”和“复用范围”走，同一个团队维护、总是一起改的代码，放在一个模块里就好，没必要为了形式上的清晰付出维护成本。

最后分享一个小技巧：在根目录放一个mvnw包装器，把 Maven 版本也锁住。这样新人不需要单独装 Maven，直接./mvnw clean install就行，团队里所有人的构建环境完全一致，能省掉一批“我这边能跑你那边不能跑”的扯皮。这个动作花五分钟，收益能持续整个项目周期。