Maven practice (1)-coordinate planning

What are coordinates? Why planning?

Coordinate is the most basic concept of Maven. It is like the ID number of each component. With it, we can locate any component that we are interested in among tens of millions of components. In the simplest example, if there is no coordinate, You need to download the dependent jar package when using JUnit, and use the dependency Method for simple configuration, such as JUnit: 4.8.2. Here, the first JUnit is groupid, the second JUnit is artifactid, and 4.8.2 is version.

Many of Maven's other core mechanisms depend on coordinates. The most significant one is repository and dependency management. For a warehouse, with coordinates, you can know where to store the component content. For example, JUnit: 4.8.2 corresponds to the path in the warehouse./junit/junit/4.8.2/junit-4.8.2.pomAnd/junit/junit/4.8.2/junit-4.8.2.jarFor such files, you can directly access the central repository address to see the repository layout, or browse the local repository directory.~/.m2/repository/For an intuitive experience.

The dependency configuration is based entirely on coordinates, for example:

<dependency>   <groupId>junit</groupId>   <artifactId>junit</artifactId>   <version>4.8.2</version>   <scope>test</scope> </dependency>

With the correct coordinates, Maven can find and use the dependency file in the correct position. The scope with the value of test is used to control the dependency, which is only available during testing and has nothing to do with the coordinates.

Because coordinates are the core of Maven, it is vital to plan the correct coordinates. If you use ambiguous coordinates, it is difficult for your users to find your components, or even if it is found, it is easy to write errors. If you use a groupid like JUnit, what will happen? Next, let's take a look at some non-standard coordinate usage methods.

Coordinate planning principles

Examples of misuse of coordinates and misuse of coordinates are everywhere. In the central repository, we can see that springframework has two types of coordinates. One is to directly use springframework as the groupid, such as springframework: Spring-Beans: 1.2.6, the other is to use Org. springframework as a groupid, such as Org. springframework: Spring-Beans: 2.5. Take a closer look, the previous method seems casual, and the latter is derived from the domain name. Obviously, the latter is more reasonable, because the user can refer to the maven coordinates of the domain name at a glance, easy to find. Therefore, the new springframework component uses org. springframework as the groupid. In this example, we can see that the principle of coordinate planning isDerivative based on project domain name. In fact, many popular open-source projects have broken this principle. For example, JUnit, this is because the maven community has no strict restrictions when it first accepts components and deploys them to the central repository, for these popular projects, changing the coordinates at a time will affect a large number of users, so it is also a historical issue.

Another common problem is to directly match the groupid to the company or organization name, because it is obvious at first glance. For example, if the organization is zoo.com and the project is dog, some people will directly use groupid com. Zoo. If a project has only one module, there is no problem, but projects in the real world often have many modules. One of the advantages of Maven is to manage projects through multiple modules. The dog project may have many modules. Which part of the coordinates are used to define the modules? The groupid is obviously incorrect, and the version cannot be. That is, only artifactid. Therefore, we have another principle,Use artifactid to define a moduleInstead of defining projects. Next, obviously,The project must be defined using groupid.. Therefore, for the dog project, you should use groupid COM. zoo. dog not only indicates that this is a project under zoo.com, but also can be associated with other projects under the organization, such as COM. zoo. cat is distinguished.

In addition, the definition of artifactid also has best practices. We often see that a project has many modules, such as API, Dao, service, and Web. The name of a component generated by a Maven project by default is not generated based on artifactid, version, or packaging. For exampleapi-1.0.jar,dao-1.0.jarWait, they don't carry the groupid information, it will cause a problem, for example, when we put all these components under the Web Container, you will find that the project dog has a api-1.0.jar, the project CAT also has a api-1.0.jar, which causes a conflict. Worse, the dog project has a api-1.0.jar, the CAT project has a api-2.0.jar, in fact the two have nothing to do, can be put together, but it is easy to confuse. To make the coordinates clearer, another principle emerged:Add project information when defining artiafctidFor example, in the API module of the dog project, artifactid dog-API is used, and the others are dog-Dao and Dao-service. Although the font size cannot appear in the Java package name, Maven does not have this restriction. Now dog-api-1.0.jar, when the cat-2.0.jar is put together, it is not easy to confuse.

We haven't talked about the coordinates yet. We will not detail them here, because the readers can find a detailed explanation from Maven: the complete guide. In short, the following format is used:

<Main version>. <minor version>. <incremental version>-<qualifier>

The main version mainly represents a large architecture change, while the minor version mainly represents an increase in features. The incremental version mainly serves bug fixes, And the delimiters such as alpha and beta are used to represent milestones. Of course, these four parts are not used for each project version. You can choose to use them as needed. On this basis, Maven also introduces the snapshot concept to indicate the development status of the activity. Because coordinate planning is not involved, we will not detail it here. However, it should be noted that, due to the existence of snapshot, it is not necessary to explicitly use the timestamp string in version.

Classifier

Classifier may be the maven feature most easily overlooked, but it is really important and we also need it to help plan coordinates. Suppose there is a jar project. dog-cli-1.0.jar You can draw a puppy on the command line. Now, you want to provide a zip package that contains not only the runable jar, but also the source code and documentation. In other words, this is a formal distribution package. What is the file name?dog-cli-1.0.zip? It is not clear enough that it is difficult to tell from the extension what is the default component generated by Maven and what is the additional configuration to generate the distribution package. If yesdog-cli-1.0-dist.zipIt would be better. The Dist here is classifier. By default, Maven only generates one component, which is called the main component.When we want Maven to generate other ancillary components, we can use Classifier. Common Classifierdog-cli-1.0-sources.jarIndicates the source code package,dog-cli-1.0-javadoc.jarIndicates the javadoc package and so on. Classifier can be created in a variety of ways. The most important one is to use Maven assembly in, which can be further studied by interested readers.

Summary

This is the first article in The infoq Maven column, discussing Maven coordinate planning, including how to correctly use groupid, artifactid, version, and classfier. The author encountered various fuzzy or even wrong coordinates during the maintenance of the maven central warehouse. Their existence caused great inconvenience to the majority of Maven users. This article provides some good practices to help you better use Maven. If you have a summary of your experience, do not share it.