Maven 项目构建笔记 - 单体应用与简单微服务

一、Maven 基础概念

1.1 Maven 核心功能

依赖管理：自动下载和管理项目所需的jar包
项目构建：编译、测试、打包、部署等生命周期管理
项目标准化：统一的项目结构和构建流程

1.2 Maven 目录结构（标准布局）

复制代码

项目根目录/
├── pom.xml                    # Maven项目配置文件
├── src/
│   ├── main/
│   │   ├── java/              # 主Java源代码
│   │   ├── resources/         # 主资源文件
│   │   └── webapp/           # Web应用资源（可选）
│   └── test/
│       ├── java/              # 测试Java代码
│       └── resources/         # 测试资源文件
└── target/                    # 构建输出目录（自动生成）

二、单体应用 Maven 配置

2.1 基础 pom.xml 配置

xml 复制代码

<?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>monolithic-app</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>  <!-- 或war -->
    
    <name>Monolithic Application</name>
    <description>A simple monolithic application</description>
    
    <!-- 属性定义 -->
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
        <java.version>11</java.version>
    </properties>
    
    <!-- 依赖管理 -->
    <dependencies>
        <!-- Spring Boot Starter (可选) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>2.7.0</version>
        </dependency>
        
        <!-- 数据库相关 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <version>8.0.30</version>
        </dependency>
        
        <!-- 测试依赖 -->
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.13.2</version>
            <scope>test</scope>
        </dependency>
        
        <!-- 日志 -->
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-api</artifactId>
            <version>1.7.36</version>
        </dependency>
    </dependencies>
    
    <!-- 构建配置 -->
    <build>
        <plugins>
            <!-- 编译插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.10.1</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                </configuration>
            </plugin>
            
            <!-- 打包插件 -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.2</version>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>com.example.MainApplication</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

2.2 分模块单体应用（可选）

对于大型单体应用，可以按功能分模块：

复制代码

monolithic-app/
├── pom.xml                    # 父POM
├── common/                    # 通用模块
│   ├── src/
│   └── pom.xml
├── domain/                    # 领域模型模块
│   ├── src/
│   └── pom.xml
├── service/                   # 业务服务模块
│   ├── src/
│   └── pom.xml
├── web/                       # Web层模块
│   ├── src/
│   └── pom.xml
└── api/                       # API接口模块
    ├── src/
    └── pom.xml

父POM配置：

xml 复制代码

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>monolithic-parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>  <!-- 注意：父模块必须是pom类型 -->
    
    <modules>
        <module>common</module>
        <module>domain</module>
        <module>service</module>
        <module>web</module>
        <module>api</module>
    </modules>
    
    <!-- 公共依赖和插件配置 -->
    <dependencyManagement>
        <dependencies>
            <!-- 统一管理依赖版本 -->
        </dependencies>
    </dependencyManagement>
    
    <build>
        <pluginManagement>
            <!-- 统一管理插件版本 -->
        </pluginManagement>
    </build>
</project>

三、简单微服务 Maven 配置

3.1 独立微服务项目结构

复制代码

microservices/
├── user-service/              # 用户服务
│   ├── src/
│   └── pom.xml
├── order-service/             # 订单服务
│   ├── src/
│   └── pom.xml
├── product-service/           # 产品服务
│   ├── src/
│   └── pom.xml
└── gateway-service/           # 网关服务（可选）
    ├── src/
    └── pom.xml

3.2 微服务 pom.xml 示例

xml 复制代码

<?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>user-service</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    
    <properties>
        <java.version>11</java.version>
        <spring-boot.version>2.7.0</spring-boot.version>
        <spring-cloud.version>2021.0.3</spring-cloud.version>
    </properties>
    
    <!-- Spring Boot 父依赖（可选，提供默认配置） -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.0</version>
        <relativePath/> <!-- 从仓库查找 -->
    </parent>
    
    <dependencies>
        <!-- Web服务 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- 数据库 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        
        <!-- 服务注册发现（如果使用Eureka等） -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        
        <!-- 配置中心（如果使用Config Server） -->
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-config</artifactId>
        </dependency>
        
        <!-- 健康检查 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        
        <!-- 测试 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    
    <!-- Spring Cloud 依赖管理 -->
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    
    <build>
        <plugins>
            <!-- Spring Boot Maven Plugin -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <mainClass>com.example.userservice.UserServiceApplication</mainClass>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>repackage</goal> <!-- 生成可执行jar -->
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

四、依赖管理详解

4.1 依赖范围（Scope）

Scope	说明	示例
compile	默认，编译/运行/测试都需要	项目核心依赖
provided	容器已提供，编译和测试需要，运行不需要	servlet-api
runtime	运行和测试需要，编译不需要	JDBC驱动
test	仅测试需要	JUnit, Mockito
system	系统路径依赖，不推荐使用	本地特殊jar
import	仅用于dependencyManagement，导入其他POM	BOM管理

4.2 依赖排除

xml 复制代码

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>

4.3 可选依赖（optional）

xml 复制代码

<dependency>
    <groupId>com.example</groupId>
    <artifactId>optional-module</artifactId>
    <version>1.0.0</version>
    <optional>true</optional>  <!-- 不会传递依赖 -->
</dependency>

五、构建生命周期和插件

5.1 Maven 生命周期阶段

复制代码

clean生命周期：clean
default生命周期（主要）：
  validate → compile → test → package → verify → install → deploy
site生命周期：site, site-deploy

5.2 常用插件配置

打包可执行JAR：

xml 复制代码

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <executable>true</executable>  <!-- 可作为Linux服务 -->
        <layers>
            <enabled>true</enabled>    <!-- 分层打包，Docker优化 -->
        </layers>
    </configuration>
</plugin>

资源过滤：

xml 复制代码

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <configuration>
        <delimiters>
            <delimiter>@</delimiter>  <!-- 使用@作为占位符 -->
        </delimiters>
        <useDefaultDelimiters>false</useDefaultDelimiters>
    </configuration>
</plugin>

Docker镜像构建（可选）：

xml 复制代码

<plugin>
    <groupId>com.spotify</groupId>
    <artifactId>dockerfile-maven-plugin</artifactId>
    <version>1.4.13</version>
    <executions>
        <execution>
            <id>default</id>
            <goals>
                <goal>build</goal>
                <goal>push</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <repository>myregistry/${project.artifactId}</repository>
        <tag>${project.version}</tag>
        <buildArgs>
            <JAR_FILE>target/${project.build.finalName}.jar</JAR_FILE>
        </buildArgs>
    </configuration>
</plugin>

六、配置文件管理

6.1 多环境配置

复制代码

src/main/resources/
├── application.yml            # 主配置
├── application-dev.yml        # 开发环境
├── application-test.yml       # 测试环境
├── application-prod.yml       # 生产环境
└── application-local.yml      # 本地环境

pom.xml中配置环境变量：

xml 复制代码

<profiles>
    <profile>
        <id>dev</id>
        <properties>
            <activatedProperties>dev</activatedProperties>
        </properties>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
    </profile>
    
    <profile>
        <id>prod</id>
        <properties>
            <activatedProperties>prod</activatedProperties>
        </properties>
    </profile>
</profiles>

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>  <!-- 启用过滤 -->
            <includes>
                <include>application.yml</include>
                <include>application-${activatedProperties}.yml</include>
            </includes>
        </resource>
    </resources>
</build>

6.2 资源过滤配置

xml 复制代码

<properties>
    <app.name>微服务示例</app.name>
    <app.version>1.0.0</app.version>
    <database.url>jdbc:mysql://localhost:3306/mydb</database.url>
</properties>

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
            <includes>
                <include>**/*.properties</include>
                <include>**/*.xml</include>
            </includes>
        </resource>
    </resources>
</build>

七、多模块项目管理

7.1 统一版本管理

xml 复制代码

<!-- 父POM中 -->
<properties>
    <java.version>11</java.version>
    <spring-boot.version>2.7.0</spring-boot.version>
    <my.project.version>1.0.0-SNAPSHOT</my.project.version>
</properties>

<dependencyManagement>
    <dependencies>
        <!-- 统一版本声明 -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>common-utils</artifactId>
            <version>${my.project.version}</version>
        </dependency>
        
        <!-- 外部依赖版本统一 -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.12.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

7.2 模块依赖声明

xml 复制代码

<!-- 子模块pom.xml -->
<parent>
    <groupId>com.example</groupId>
    <artifactId>microservices-parent</artifactId>
    <version>1.0.0</version>
</parent>

<artifactId>user-service</artifactId>

<dependencies>
    <!-- 内部模块依赖 -->
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>common-utils</artifactId>
        <!-- 不需要版本号，从父POM继承 -->
    </dependency>
    
    <!-- 外部依赖 -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <!-- 不需要版本号，由dependencyManagement管理 -->
    </dependency>
</dependencies>

八、构建优化技巧

8.1 跳过测试

bash 复制代码

# 编译时跳过测试
mvn clean install -DskipTests

# 编译时跳过测试代码编译
mvn clean install -Dmaven.test.skip=true

# 特定模块跳过测试
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <skipTests>${skip.unit.tests}</skipTests>
    </configuration>
</plugin>

8.2 并行构建

bash 复制代码

# 启用并行构建
mvn clean install -T 4  # 使用4个线程

# 每个CPU核心一个线程
mvn clean install -T 1C

8.3 构建缓存（Maven 3.6.1+）

bash 复制代码

# 启用构建缓存
mvn clean install -Daether.connector.resumeDownloads=true

九、常用命令速查

9.1 基础命令

bash 复制代码

# 清理并安装
mvn clean install

# 跳过测试的安装
mvn clean install -DskipTests

# 编译
mvn compile

# 打包
mvn package

# 运行测试
mvn test

# 生成站点文档
mvn site

# 运行特定测试类
mvn test -Dtest=TestClassName

# 运行特定测试方法
mvn test -Dtest=TestClassName#methodName

9.2 多模块操作

bash 复制代码

# 清理所有模块
mvn clean

# 安装所有模块
mvn install

# 只编译指定模块
mvn compile -pl module-name

# 编译指定模块及其依赖
mvn compile -pl module-name -am

# 安装指定模块及其依赖
mvn install -pl module-name -am

# 从指定模块开始构建后续所有模块
mvn install -rf :module-name

9.3 依赖相关

bash 复制代码

# 查看依赖树
mvn dependency:tree

# 分析依赖冲突
mvn dependency:tree -Dverbose

# 下载源代码
mvn dependency:sources

# 下载javadoc
mvn dependency:resolve -Dclassifier=javadoc

# 复制依赖到指定目录
mvn dependency:copy-dependencies -DoutputDirectory=lib

9.4 发布部署

bash 复制代码

# 部署到远程仓库
mvn deploy

# 发布到本地仓库
mvn install

# 生成源码包
mvn source:jar

# 生成javadoc
mvn javadoc:jar

# 发布源码和javadoc
mvn source:jar javadoc:jar deploy

十、最佳实践总结

10.1 单体应用建议

单一职责：每个模块职责明确
依赖最小化：只引入必要的依赖
版本统一：统一管理依赖版本
分模块开发：大型单体应用按功能分模块
环境隔离：使用profile管理不同环境配置

10.2 简单微服务建议

独立项目：每个微服务独立Maven项目
轻量级依赖：避免引入不需要的框架
独立部署：每个服务可独立打包部署
统一配置：使用父POM统一管理公共配置
版本独立：每个服务可独立版本管理

10.3 通用建议

使用.properties或.yml：替代硬编码配置
配置资源过滤：实现环境差异化配置
定期清理依赖：移除无用依赖
使用插件管理：统一插件版本
配置CI/CD：自动化构建和部署
文档化：维护README和CHANGELOG

10.4 版本命名规范

xml 复制代码

<version>1.0.0-SNAPSHOT</version>  <!-- 开发版本 -->
<version>1.0.0-RC1</version>       <!-- 发布候选 -->
<version>1.0.0</version>           <!-- 正式版本 -->
<version>1.0.1-SNAPSHOT</version>  <!-- 下一版开发 -->

通过以上配置和管理，无论是单体应用还是简单的微服务，Maven都能提供稳定、可靠的构建支持。关键是理解项目的实际需求，选择合适的结构和配置，避免过度设计。