依赖声明与坐标引用

依赖管理是 Maven 最核心的功能。传统项目中，开发者需要手动下载 jar 包、放入 lib 目录、管理版本冲突，这个过程繁琐且容易出错。Maven 通过坐标系统统一管理所有依赖，让开发者只需在 pom.xml 中声明依赖坐标，Maven 自动完成下载、版本管理和依赖传递。

为什么需要依赖管理

传统方式的痛点

在 Maven 出现之前，Java 项目管理依赖的方式：

项目/lib/
├── spring-core-5.3.0.jar      ← 手动下载
├── spring-context-5.3.0.jar   ← 手动下载
├── commons-logging-1.2.jar    ← spring-core 依赖，也要下载
├── junit-4.13.jar             ← 手动下载
└── 其他几十个 jar...

传统方式的问题：

Maven 解决方案

Maven 通过以下方式解决这些问题：

开发者只需声明：
<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-core</artifactId>
  <version>5.3.20</version>
</dependency>

Maven 自动完成：
✓ 从仓库下载 spring-core-5.3.20.jar
✓ 自动下载 spring-core 依赖的其他 jar
✓ 自动管理版本冲突
✓ 本地缓存，团队共享

核心概念：坐标（GAV）

什么是坐标

Maven 使用坐标（Coordinates）唯一标识一个构件（jar、war、pom 等）。坐标由三要素组成，简称 GAV：

groupId:artifactId:version

坐标三要素详解

重点理解：groupId 通常反向使用域名，如 org.springframework 对应 springframework.org，这保证了全球唯一性。

坐标示例解析

<!-- Spring Core 的坐标 -->
<dependency>
  <groupId>org.springframework</groupId>    <!-- 组织：Spring 社区 -->
  <artifactId>spring-core</artifactId>     <!-- 项目：Spring 核心模块 -->
  <version>5.3.20</version>                <!-- 版本：5.3.20 -->
</dependency>

<!-- 完整坐标字符串 -->
org.springframework:spring-core:5.3.20

坐标到仓库路径的映射

这是理解 Maven 仓库结构的关键。Maven 将坐标映射为仓库路径：

坐标：org.springframework:spring-core:5.3.20

映射规则：
groupId → 目录层级（点号替换为斜杠）
artifactId → 子目录
version → 版本目录

仓库路径：
org/springframework/spring-core/5.3.20/spring-core-5.3.20.jar

本地仓库实际路径：

~/.m2/repository/
└── org/
    └── springframework/
        └── spring-core/
            └── 5.3.20/
                ├── spring-core-5.3.20.jar    ← 主构件
                ├── spring-core-5.3.20.pom    ← POM 文件
                └── _remote.repositories      ← 仓库来源记录

实际应用：理解这个映射关系后，当你遇到依赖下载问题，可以直接去本地仓库对应路径查看 jar 是否存在，或手动删除重新下载。

依赖声明完整结构

基本语法

<dependencies>
  <dependency>
    <groupId>组织标识</groupId>
    <artifactId>项目名称</artifactId>
    <version>版本号</version>
    <!-- 以下为可选元素 -->
    <scope>依赖范围</scope>
    <type>构件类型</type>
    <optional>是否可选</optional>
    <exclusions>
      <exclusion>排除传递依赖</exclusion>
    </exclusions>
  </dependency>
</dependencies>

所有元素说明

实际开发场景示例

场景1：引入 Spring 框架

开发 Spring 应用时，需要引入 Spring 核心依赖：

<dependencies>
  <!-- Spring 核心：提供 IoC、Bean 等核心功能 -->
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>5.3.20</version>
  </dependency>

  <!-- Spring Context：提供 ApplicationContext 等上下文功能 -->
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>5.3.20</version>
  </dependency>

  <!-- Spring Web：提供 Web 相关功能 -->
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>5.3.20</version>
  </dependency>
</dependencies>

注意：这三个依赖都依赖 spring-jcl（Spring 的日志桥接），Maven 会自动下载，无需手动声明。

场景2：引入测试框架

单元测试需要 JUnit，但测试依赖只在测试时使用：

<dependencies>
  <!-- JUnit：单元测试框架 -->
  <!-- scope=test 表示仅在测试代码中使用 -->
  <dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>4.13.2</version>
    <scope>test</scope>    <!-- 重要：测试依赖不打包到最终产物 -->
  </dependency>
</dependencies>

实际效果：

• 测试代码可以使用 JUnit
• 最终打包的 jar/war 不包含 junit.jar
• 减少产物体积，避免测试库混入生产环境

场景3：引入 Servlet API（Web 项目）

Servlet API 由 Tomcat 等容器提供，项目只需编译时可用：

<dependencies>
  <!-- Servlet API：Web 容器提供 -->
  <!-- scope=provided 表示编译时可用，运行时由容器提供 -->
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
    <scope>provided</scope>   <!-- 重要：不打包，由 Tomcat 提供 -->
  </dependency>
</dependencies>

实际效果：

• 编写 Servlet 代码时可以引用 javax.servlet.*
• 打包的 war 不包含 servlet-api.jar
• Tomcat 运行时提供自己的 servlet-api 实现
• 避免容器和项目 servlet-api 版本冲突

场景4：引入数据库驱动

数据库驱动运行时才需要：

<dependencies>
  <!-- MySQL 驱动：运行时加载 -->
  <!-- scope=runtime 表示编译时不需要，运行时需要 -->
  <dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <version>8.0.28</version>
    <scope>runtime</scope>    <!-- 编译时不可见，运行时加载 -->
  </dependency>
</dependencies>

适用场景：

• JDBC 代码只使用 java.sql.* 接口（JDK 内置）
• 具体驱动实现运行时动态加载
• 切换数据库只需改驱动依赖，代码不变

依赖查找与下载流程

Maven 下载依赖的完整流程

┌─────────────────────────────────────────────────────────────┐
│                    Maven 依赖查找流程                         │
└─────────────────────────────────────────────────────────────┘

1. 解析 pom.xml 依赖声明
         ↓
2. 检查本地仓库 ~/.m2/repository
    ┌──────────────────┐
    │ 存在且完整？      │
    ├──────────────────┤
    │ ✓ 是 → 直接使用  │ ← 大多数情况走这里
    │ ✗ 否 → 继续查找  │
    └──────────────────┘
         ↓
3. 检查 settings.xml 配置的镜像
    ┌──────────────────┐
    │ 镜像有该依赖？    │
    ├──────────────────┤
    │ ✓ 是 → 从镜像下载│ ← 国内推荐用阿里云镜像
    │ ✗ 否 → 继续查找  │
    └──────────────────┘
         ↓
4. 检查中央仓库 repo.maven.apache.org
    ┌──────────────────┐
    │ 中央仓库下载      │
    ├──────────────────┤
    │ 下载 jar + pom   │
    │ 缓存到本地仓库   │
    └──────────────────┘
         ↓
5. 解析下载的 pom.xml
    查找该依赖的传递依赖
    重复步骤 2-4 下载所有传递依赖

首次构建 vs 后续构建

实际建议：新项目首次 mvn compile 时，建议使用国内镜像（阿里云），否则从国外中央仓库下载可能很慢或失败。

依赖版本管理策略

问题：版本分散导致维护困难

<!-- 不推荐：版本号分散在各处 -->
<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-core</artifactId>
  <version>5.3.20</version>
</dependency>
<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-context</artifactId>
  <version>5.3.20</version>    <!-- 重复写版本 -->
</dependency>
<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-web</artifactId>
  <version>5.3.19</version>    <!-- 版本不一致！问题根源 -->
</dependency>

风险：Spring 各模块版本不一致可能导致兼容性问题。

解决方案1：使用 properties 统一版本

<properties>
  <!-- 定义版本属性 -->
  <spring.version>5.3.20</spring.version>
  <junit.version>4.13.2</junit.version>
</properties>

<dependencies>
  <!-- 引用属性 -->
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <version>${spring.version}</version>
  </dependency>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>${spring.version}</version>    <!-- 自动统一 -->
  </dependency>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>${spring.version}</version>    <!-- 自动统一 -->
  </dependency>
</dependencies>

优势：升级时只需修改 <spring.version>5.3.21</spring.version>，所有依赖自动更新。

解决方案2：使用 dependencyManagement

<!-- 在父 POM 或当前 POM 定义 -->
<dependencyManagement>
  <dependencies>
    <!-- 统一管理版本，不实际引入 -->
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-core</artifactId>
      <version>5.3.20</version>
    </dependency>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-context</artifactId>
      <version>5.3.20</version>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- 实际声明依赖 -->
<dependencies>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-core</artifactId>
    <!-- 无需写版本，继承 dependencyManagement -->
  </dependency>
  <dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <!-- 无需写版本 -->
  </dependency>
</dependencies>

适用场景：多模块项目，父 POM 统一管理所有模块的依赖版本。

如何查找依赖坐标

方式1：MVNRepository（推荐）

https://mvnrepository.com/

使用步骤：

1. 搜索库名（如 "spring core"）
2. 选择版本
3. 复制 Maven 依赖声明

搜索结果：
Spring Core  »  5.3.20

Maven依赖声明：
<dependency>
  <groupId>org.springframework</groupId>
  <artifactId>spring-core</artifactId>
  <version>5.3.20</version>
</dependency>

方式2：Maven Central 搜索

https://search.maven.org/

官方仓库搜索，信息准确。

方式3：IDE 内搜索

IntelliJ IDEA：

pom.xml → Alt+Insert → Add Dependency
输入关键词搜索 → 选择版本 → OK

Eclipse：

pom.xml → Dependencies 标签页 → Add
搜索 → 选择 → OK

方式4：查看已有项目的 pom.xml

如果知道某个项目使用了某个库，直接查看其 pom.xml：

# 查看开源项目的 pom.xml
https://github.com/spring-projects/spring-framework/blob/main/spring-core/pom.xml

常见问题与解决方案

问题1：依赖下载失败

[ERROR] Failed to execute goal on project my-app: 
Could not resolve dependencies for project com.example:my-app:jar:1.0.0:
Could not find artifact org.springframework:spring-core:jar:5.3.20 in central

原因与解决：

问题2：本地仓库损坏

[ERROR] invalid LOC header (bad signature)

解决：删除本地仓库中的对应依赖，重新下载：

rm -rf ~/.m2/repository/org/springframework/spring-core
mvn compile -U    # -U 强制更新

问题3：找不到坐标

不知道某个库的 Maven 坐标：

解决流程：

1. MVNRepository 搜索库名
2. 确认 groupId、artifactId、version
3. 确认是否是最稳定版本（Usages 数量高）
4. 复制依赖声明到 pom.xml

常用依赖坐标速查表

要点总结

1. 坐标是 Maven 的核心：GAV（groupId:artifactId:version）唯一标识构件
2. 依赖声明三要素必填：groupId、artifactId、version 缺一不可
3. scope 控制依赖范围：compile（默认）、test、provided、runtime 各有用途
4. 版本管理要统一：使用 properties 或 dependencyManagement 集中管理版本
5. 首次构建下载慢：配置国内镜像加速（阿里云）
6. 查找坐标用 MVNRepository：最方便的依赖搜索网站
7. 理解仓库路径映射：遇到问题时可直接检查本地仓库