Maven用户指南(4)

最新推荐文章于 2023-07-21 11:04:21 发布

原创最新推荐文章于 2023-07-21 11:04:21 发布

· 925 阅读

2 ·

版权

文章标签：

#maven #jar #dependencies #stylesheet #文档 #javadoc

Java开源技术专栏收录该内容

78 篇文章

订阅专栏

本文档介绍了Maven的命名约定，包括项目ID、组ID和版本的规范，以及依赖声明的正确方式。此外，还讨论了远程和本地Repository的布局，并提及了Maven如何生成项目站点和自定义站点样式。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

命名约定
这部分将简要的描述项目对象模型(POM)中命名约定。本篇文档希望可以统一各式各样jar包命名方法，这些jar包一般为java开发者社区广泛使用。

规则和指南
项目
一个项目必须由一个唯一的的标识，标识由a-z小写字母和连线号构成，其首字母必须以小写字母开头。

<project>
  <groupId>bar</groupId>
  <artifactId>foo</artifactId>
  ...
</project>
所有项目间的引用都由组id和包id构成。到现在为止，在POM与此相关的是下面将要（上面提到的？）谈到的项目的依赖声明。

项目的名称应该易于阅读，可用于文档。

<project>
  <groupId>bar</groupId>
  <artifactId>foo</artifactId>
  <name>The Grand Master Foo</name>
  ...
</project>
项目应该有一个组标识，组标识是名称的基础部分。

<project>
  <groupId>bar</groupId>
  <artifactId>foo</artifactId>
  <name>The Grand Master Foo</name>
  ...
</project>
所有项目发布的包都应基于项目唯一的标识，并且放在基于项目的组id的目录中。对于上面的项目来说，假定发布的包是jar类型的包，我们就会有如下目录结构：

repository
|
+-- bar
   |-- distribution
   `-- jar
      |-- foo-1.0.jar
      `-- foo-2.0.jar
依赖
一个理想的典型依赖声明的例子可能会象这样：

<project>
  <groupId>yourProject</groupId>
  <artifactId>yourArtifact</artifactId>
  <name>Your Groovey Machine</name>
  ...

  <dependencies>

<dependency>
   <groupId>bar</groupId>
   <artifactId>foo</artifactId>
   <version>1.0</version>
</dependency>

</dependencies>

</project>
这样一来，依赖于id为foo1.0 版本的bar项目属于org.foo.bar组。这个依赖会被解析为本地repository中jar文件。上面的情形假定发布的包是基于包id命名的。因此对于上述依赖，Maven就会采用 foo-1.0.jar作为jar名。

就像用户反映的那样，这种理想的方式并不能适应所有的项目。有几种情形我们必须考虑调整理想的依赖机制：

发布的jar包的并未使用项目作为基础名，如xercesImpl就是所有发布的jar包的基础名它与gump id和maven中的id都不一样。
发布的jar包没有使用任何版本声明，如许多commons组件并没有把版本号作为包名的一部分。
有些项目即没有使用项目id作为基础名也没有版本声明。例如，最坏的情形是Java Activation Framework 的jar包，它没有遵循其他Sun的命名规则，也没有在jar包中声明版本号，甚至在manifest中都没有任何版本信息。

在多数情形下，任何例外的情况都可以用 <jar>(可选节点)、或者是重命名来解决。现在，许多Jarkata的产品在repository已经被重命名，因为在不久的未来，绝大多数的Jarkarta的项目将用maven进行构建。但这不是公司政策，我们不需要解决所有情况的问题。

发布多个包的项目
Maven的依赖机制完全支持任何形式的多项目包。 Maven's dependency mechanism completely supports multiple project artifacts of any given type.

下面的代码包含了ant的主jar包和optional包加上hypothetical包。

<dependencies>

  
  <dependency>
<groupId>ant</groupId>
<artifactId>ant</artifactId>
<version>1.4.1</version>
  </dependency>

  
  <dependency>
<groupId>ant</groupId>
<artifactId>ant-optional</artifactId>
<version>1.4.1</version>
  </dependency>

  
  <dependency>
<groupId>ant</groupId>
<artifactId>poorly-named</artifactId>
<version>1.4.1</version>
  </dependency>

</dependencies>
所以A), B) 和 C)实际上是指向属于同一组的单个包的指针，这就是说，一个单独的依赖就是对某个组中的某个包的引用。目前artifact如果没有特别说明的话，一般指的是jar包。但是依赖也可能是一个war文件或一个发行包。我们试图在提供多数情况下(构建大多需要jar包)使用的缺省方式的同时，也顾及灵活性。

远程Repository布局
这部分文档将对Maven的远程repositories做一个概要的说明。目前，主repository位于 Ibiblio，但是你也可以自己创建一个远程repositories，其结果描述可以在这部分文档中找到。

任何独立的项目在repository都有自己的目录。每个项目有一个唯一的项目id和同名目录，项目的发行包就放在这个目录中。

项目的目录中可以存放各种各样的artifacts，目前最为广泛使用的两种类型是jar包和发行包下面是一个远程repository快照：

repository
|
|-- ant
| |-- distribution
| `-- jars
|    |-- ant-1.4.1.jar
|    `-- ant-optional-1.4.1.jar
+-- jsse
|-- distribution
`-- jars
   |-- jsse.jar
   |-- jcert.jar
   `-- jnet.jar
本地Repository布局
应该有一个接口集合的紧凑实现使本地repository目录结构更加随意一些。现在我只使用了一个类来实现，显得有些臃肿。我还是认为本地和远程repositories应保持相同的结构但是为了使用更乐于使用，我开始设计一些接口，用于满足用户自己安排自己本地Repository 布局，相似的远程Repositor也在设计中。尽管目前本地repository仍与远程repository 完全一致，我希望听到更多的用户反馈，以促进这些接口的开发，或者完全抛弃它。

生成项目站点
Maven可以为项目产生一个完成的web站点。这个web站点将包含各种各样、由许多Maven插件产生的报告，如javadocs，代码度量，单元测试，changlog，及其它... 本节文档接下来的部分将阐述Maven支持的站点定制选项。

颜色
考虑到一致性，缺省情况下，所有Maven产生的站点都使用相似的外观。这使用户一眼就能认出由Maven产生的站点，产生熟悉的感觉，更加方便信息的获取。当然，Maven开发组也考虑到用户可能会希望定制他们的站点。修改Maven产生的站点，最简单的方法是指定你要使用的颜色搭配。这只需要在project.properties简单的设置适当的属性即可。下面是所有可用的属性描述在 xdoc plugin。

风格
如果你感觉颜色太过于简单，无法满足你的要求，你可以用自己的stylesheet。为了重载在${basedir}/xdocs/stylesheets/中的maven.css stylesheet，你可以通过设置maven.javadoc.stylesheet 属性来指定你的 javadoc风格。

报告
最后，如果你希望定制哪些报告需要自动产生，你需要在你的项目描述中包含 reports 标签库。到目前为止，如果没有reports标签指定，所有插件报告都会产生。这个标签允许你选择产生哪些报告而排斥另外一些报告，而且允许你安排顺序。

目前的标准报告集在xdoc中是硬编码实现的，它们是：

maven-changelog-plugin
maven-changes-plugin
maven-checkstyle-plugin
maven-developer-activity-plugin
maven-file-activity-plugin
maven-javadoc-plugin
maven-jdepend-plugin
maven-junit-report-plugin
maven-jxr-plugin
maven-license-plugin
maven-linkcheck-plugin
maven-pmd-plugin
maven-tasklist-plugin

   如果你希望产生缺省的报告，但是还想增加或删除一两个，最好的方法是：给 xdoc:register-reports目标写一个前置目标(postGoal)。

<postGoal name="xdoc:register-reports">
  <attainGoal name="maven-changelog-plugin:deregister"/>
  <attainGoal name="maven-myown-plugin:register"/>
</postGoal>

      排除所有Maven产生的内容
某些情况下，用户需要构建只有文档的站点，或是构建聚合许多子项目的站点，但不希望在站点上有个整体“项目文档”导航条。设置 maven.xdoc.includeProjectDocumentation属性值为no 即可解决这一问题。缺省的，Maven会包含“项目文档”导航条，下面挂的是许多Maven 生成的报告。