构建与依赖 / 系统课时

项目坐标与制品标识

项目坐标与制品标识

Maven 需要一套稳定标识来区分“当前项目”和“要下载的依赖”。最常见的基础坐标由 groupId、artifactId、version 组成;本节用一个可验证的 POM 演示这三项如何映射到仓库路径,并说明哪些命名错误会导致依赖混淆。

学习目标

  • 解释 groupId、artifactId、version 各自负责什么
  • 根据一组坐标推导 Maven 仓库中的目录与文件名
  • 在 POM 中定义坐标,并用 Maven 命令读取实际生效值

三段坐标怎样组成标识

以 com.acme.billing:invoice-core:1.3.0 为例,冒号分隔的三项就是常说的 GAV。groupId 通常表示组织或命名空间,artifactId 表示模块,version 表示具体版本。

字段 示例 实际约束与建议
groupId com.acme.billing 通常采用反向域名形式,避免与其他组织冲突
artifactId invoice-core 同一 groupId 下应唯一,常用小写加短横线
version 1.3.0 发布版固定;开发迭代常见 1.4.0-SNAPSHOT

基础教学通常用 GAV 标识一个版本,但真正的制品文件还可能受打包类型和 classifier 影响。例如同一 GAV 可以同时存在 POM、JAR,或带 sources classifier 的附加 JAR,因此不要把“GAV”误解成“仓库里永远只有一个文件”。

坐标怎样变成仓库路径

仓库路径的关键规则很机械:把 groupId 中的点替换为目录分隔符,再依次追加 artifactId 和 version。上面的示例会落到 com/acme/billing/invoice-core/1.3.0/,主 JAR 文件名通常是 invoice-core-1.3.0.jar。

Maven 坐标到仓库路径的映射关系

默认本地仓库通常位于用户主目录的 .m2/repository 下,因此 Linux 或 macOS 上可看到类似 ~/.m2/repository/com/acme/billing/invoice-core/1.3.0/ 的路径。若 settings.xml 配置了 localRepository,实际位置会改变,排查时应以有效设置为准。

在 POM 中定义并读取坐标

下面是完整的最小 POM。保存为项目根目录的 pom.xml。

xml
<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.acme.billing</groupId>
  <artifactId>invoice-core</artifactId>
  <version>1.3.0</version>
</project>

用 Maven Help Plugin 读取模型中的三个值。首次执行时 Maven 可能先下载该插件,下载日志会因环境不同而变化;-q 配合 -DforceStdout 可只保留表达式结果。

bash
mvn -q help:evaluate -Dexpression=project.groupId -DforceStdout
mvn -q help:evaluate -Dexpression=project.artifactId -DforceStdout
mvn -q help:evaluate -Dexpression=project.version -DforceStdout

预期输出:

text
com.acme.billing
invoice-core
1.3.0

这三个值也是当前项目安装到本地仓库时使用的基础坐标。执行 mvn install 后,主制品会进入对应的 GAV 路径;具体文件扩展名由 packaging 和实际构建产物决定。

命名错误怎样影响依赖解析

最危险的错误是随意修改已发布模块的 groupId 或 artifactId。Maven 会把新坐标当成全新的制品,而不会自动理解“这是旧模块改名”。例如从 com.acme.billing:invoice-core:1.3.0 改成 com.acme.invoice:invoice-core:1.3.1 后,依赖旧坐标的项目仍会继续解析旧路径。

版本也要区分固定发布版与快照版。1.3.0 表示一个固定版本坐标;1.4.0-SNAPSHOT 表示开发中的快照版本,远程仓库可以在同一快照版本下发布更新内容。对需要可重复构建的发布流程,不要长期依赖变化中的 SNAPSHOT。

项目坐标一旦被其他模块引用,就等同于公开标识。设计坐标时先固定组织命名空间、模块名和版本策略,再让依赖、仓库与发布流程围绕同一套 GAV 工作。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

项目坐标与制品标识

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通