第 1 章 作战室开局：坐标、仓库与诊断武器

第 1 章 作战室开局：坐标、仓库与诊断武器

本章要回答的三个问题：

1. 一个 jar 是怎么被 Maven 找到、搬进项目、装进本地缓存的？
2. 值班工程师手上那十几个 mvn 命令，各自在什么战况下使用？
3. 出了依赖问题，第一发诊断炮弹应该打向哪里？

为什么会有这一章

每个进作战室的人都要先认地形。Maven 的地形由三样东西构成：给构件编号的坐标系统、存放构件的仓库网络、把两者连起来的解析与下载机制。多数教程把它们当名词解释讲，结果是工程师背得出 groupId 和 artifactId 的定义，却在"依赖为什么下载不下来"面前束手无策。

本章换一种讲法：以风控服务 risk-engine 的创建为起点，沿着一次真实的依赖引入过程走一遍，看 Maven 如何把一个坐标翻译成本地仓库里的一份文件。讲清这条链路，第 3 章的依赖战争、第 4 章的私服治理才有着落点。

读完能解决什么

对照开篇的三个问题，读完本章你应当能够：

• 说清 GAV 坐标、SNAPSHOT 与 RELEASE 的差别，以及本地仓库、远程仓库、中央仓库的寻址顺序；
• 用 clean、compile、test、package、install、deploy 组织日常构建，用 -U、-o、-pl、-am 处置异常战况；
• 用 dependency:tree 与 help:effective-pom 完成第一次依赖现场勘查，读出"谁把谁带进来了"。

本章知识点清单

• 理解 jar 地狱的形成机制与 Maven 的应对思路（约定优于配置）；
• 掌握 GAV 三元组的语义与 packaging、classifier 的补充定位作用；
• 理解本地仓库、镜像、私服、中央仓库的寻址顺序与命中规则；
• 掌握六大核心命令的触发阶段与常见参数的组合用法；
• 掌握 dependency:tree 的输出格式、过滤参数与 omitted 信息含义；
• 掌握 effective-pom 与 effective-settings 的生成与阅读方法。

图：第 1 章战况板

各节怎么分工

先决条件

• 会用命令行，装好 JDK 8 或以上版本与 Maven 3.6 以上版本；
• 了解 Java 的 classpath 概念，知道 jar 是类的容器；
• 不需要先学过构建工具，Ant 与 Make 的历史对比会随讲随补。

值班台前的三个预检问题

学 Maven 必须先学 XML 吗？

不必系统学，认得出标签的嵌套结构即可。POM 的标签集合是封闭而小的（坐标、依赖、插件、属性四大族），本章各节的示例读下来自然就覆盖了高频标签。真正要下功夫的不是 XML 语法，而是每个标签背后 Maven 做了什么——这正是本章的讲法。

本地仓库在哪里？我怎么知道它有没有被塞满？

默认在用户主目录下 Maven 配置目录里的 repository 文件夹。查看体积用系统的目录大小统计即可；它的内容全部可以按坐标重建（第 4.2 节讲治理），所以"塞满"只影响磁盘不影响正确性。别急着清理——清错了目录反而制造下载风暴。

为什么我执行 mvn version 和 mvn clean 的输出风格差很多？

前者是直接调用的诊断类目标（不进生命周期），后者跑的是 clean 生命周期。两种输出风格对应两种出场方式，第 2.2 节会把这套"常规军与特种兵"的编制讲透。

往下走到哪

本章结束时你已经能看懂 Maven 的一次完整取件过程。第 2 章把镜头转向构建机器内部：生命周期如何分阶段推进、插件如何被绑定到阶段上执行。诊断工具箱里看到的"插件执行日志"，到那时会变成你能逐行解读的作战记录。