1.2 坐标、POM 与仓库体系

1.2 坐标、POM 与仓库体系

本节摘要：GAV 坐标决定构件在仓库中的物理路径，仓库体系按"本地、镜像或私服、中央"的顺序接力寻址，POM 则是继承与合并后的最终构建事实。掌握这三者的映射规则，是诊断一切"找不到构件"类故障的地形基础。

先看一条下载日志

第一次构建 risk-engine 时，控制台出现过这样几行：

Downloading from central: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-databind/2.13.4/jackson-databind-2.13.4.pom
Downloaded from central: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-databind/2.13.4/jackson-databind-2.13.4.pom (13 kB at 42 kB/s)
Downloading from central: https://repo.maven.apache.org/maven2/com/fasterxml/jackson/core/jackson-databind/2.13.4/jackson-databind-2.13.4.jar
​

把 URL 拆开：主机名是仓库地址，后面的路径正是坐标的逐级展开——groupId 中的点号变成目录分隔符，接 artifactId 目录、version 目录，最后是"构件名-版本"的文件。换句话说，坐标不是抽象编号，而是仓库里的物理地址。看懂这一点，后面很多故障（比如本地缓存损坏、镜像没同步某构件）的排查路径就自然浮现：先查这个地址在本地是否存在，再查远程是否能访问。

POM：一份会被继承和合并的蓝图

POM（Project Object Model）不只是依赖清单。它同时描述坐标、父子关系、依赖与依赖管理、插件配置、环境 Profile。更关键的是，Maven 实际执行时用的不是你写的 POM，而是合并了父 POM、超级 POM（内置默认值）与各种 Profile 之后的有效 POM。一个最小的有效化演示：

<!-- 你在 POM 里只写了这些 -->
<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
</dependency>
<!-- 没写版本也没写 scope？如果父 POM 的 dependencyManagement 管了 junit 4.13.2，
     有效 POM 里它就带着版本 4.13.2 和 scope test 出现。
     这就是"为什么我没声明版本也能构建"的答案：
     版本来自某个父级，第 1.4 节的有效 POM 工具能把它照出来。 -->
​

超级 POM 里定义了默认的目录布局、插件版本区间与中央仓库地址，所以"什么都没写也能构建"并不是魔法，是内置蓝图在兜底。作战室视角下的推论是：排查配置问题时，眼睛只盯着当前 POM 是不够的，要盯有效结果。第 1.4 节会给出把有效 POM 完整打印出来的命令。

仓库接力：本地、远程、中央

Maven 找一个构件的顺序是固定的三步。第一步查本地仓库（默认在用户主目录的 .m2 之下，可改），命中即用，绝不联网。第二步未命中则按 POM 与 settings 中声明的远程仓库逐个询问。第三步都失败才报错，错误信息里会列出它问过的所有地址。三步之间还有一个常见插入项：镜像，它可以把"对某仓库的请求"整体改道，第 4 章讲私服时会大量用到。

图：仓库寻址接力顺序

三步接力里有两个容易误判的点。其一，本地命中是"文件存在"级别的：本地仓库里只要有对应目录与文件就不再询问远程，哪怕远程已经更新了版本（对 RELEASE 构件这是正确行为，对 SNAPSHOT 则要靠 -U 强制刷新，见 1.3 节）。其二，失败会留下痕迹：本地仓库对应目录下的 .lastUpdated 文件记录了"何时在哪个仓库没找到它"，Maven 在一段时间内不会重试。这就是"明明网恢复了还是下载失败"的经典原因之一，处置办法在第 3.4 节展开。

SNAPSHOT 与 RELEASE：两种完全不同的弹药

坐标里的 version 字段暗藏一条分界线：带 -SNAPSHOT 后缀的是快照版，其余是发布版。它们的仓库行为完全不同。

⚠️ 常见坑：项目要上线了，POM 里还挂着兄弟模块的 SNAPSHOT 依赖。今天打包的内容与明天打包的可能不同，发布记录形同虚设。第 5 章讲可复现构建时会立一条军规：release 分支禁 SNAPSHOT。

动手验证：亲手走一遍寻址链

光看图不够，五分钟就能把链路走一遍。在 risk-engine 目录执行解析命令并观察日志来源：

mvn dependency:resolve
# 首次输出示例：
# Downloading from central: .../jackson-databind/2.13.4/jackson-databind-2.13.4.pom
# 第二次执行同一命令：
# 无任何 Downloading 行 直接进入构建
# 原因：本地仓库已命中 寻址链第一步即返回
​

再来一个反向实验——删掉本地仓库里 jackson 的目录（精确到该构件的版本目录，别清库），重新执行，Downloading 行重新出现。这两个实验价值很高：它把"本地命中即不联网"从书上的一句话变成你亲手观测到的行为，后面第 3.4 节排查下载故障时，你对"它到底有没有去问远程"会有肌肉记忆级的判断力。

顺带认识两个坐标的补充定位字段。packaging 默认是 jar，改成 war、pom（父工程与 BOM 都用它）会影响默认插件绑定（第 2 章展开）；classifier 用来区分"同版本下的不同变体"，比如同一版本出的 jdk11 编译版与普通版、带调试符号与不带的二进制。完整的定位式子是五元组：组、名、版本、打包形态、变体——落到文件名上就是大家熟悉的"构件名-版本-变体.后缀"。

本节要点回顾

• 坐标即地址：groupId 的点号展开为目录，拼上 artifactId 与 version 就是仓库物理路径，下载日志里的 URL 可直接肉眼核对；
• 五元组完整定位：组、名、版本、packaging、classifier，缺省有默认但语义要记牢；
• 有效 POM 才是事实：实际执行的是父 POM、超级 POM、Profile 合并后的结果，排查配置要看合并产物；
• 寻址三步：本地缓存命中即断网使用，否则问远程（私服或镜像优先），中央仓库兜底；
• 失败留痕：.lastUpdated 标记会让 Maven 暂时拒绝重试，是"网络恢复仍失败"的头号嫌疑；
• SNAPSHOT 是进行时弹药：内部联调方便，发布场景必须清场。

下一节把镜头从"文件从哪来"切到"命令怎么打"：六个核心命令、四组高频参数，构成作战室的日常频道表。