Как да създадете приставка Maven

1. Въведение

Maven предлага голямо разнообразие от приставки, които да ни помогнат при изграждането на нашия проект. Можем обаче да открием случаи, когато тези приставки не са достатъчни и трябва да разработим свои собствени.

За щастие Maven предоставя някои полезни инструменти, които да ни помогнат в този процес.

В този урок ще бъдем доста практични и ще покажем стъпка по стъпка как да създадем плъгин Maven от нулата.

Ще покажем също как да го използваме в нашите проекти и как да създаваме документация за него.

2. Създаване на приставка

По време на този урок ще разработим приставка, наречена counter-maven-plugin, която ще отчита броя на зависимостите, които проектът съдържа. Много е важно да следвате конвенцията за именуване на приставки, която Maven препоръчва, когато избираме името за нашия плъгин.

След като вече знаем какво ще разработим, следващото нещо, което трябва да направим, е да създадем проект на Maven. В pom.xml ще дефинираме groupId , artifactId и версията на нашия плъгин:

 4.0.0 com.baeldung counter-maven-plugin maven-plugin 0.0.1-SNAPSHOT counter-maven-plugin Maven Mojo //maven.apache.org  1.8 1.8  

Забележете, че сме задали опаковката на maven-plugin .

В този случай създадохме проекта ръчно, но бихме могли да го направим и с помощта на maven-archetype-mojo :

mvn archetype:generate -DgroupId=com.baeldung -DartifactId=counter-maven-plugin -Dversion=0.0.1-SNAPSHOT -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-mojo

Когато правим това, трябва да актуализираме версиите по подразбиране на зависимостите, за да използваме най-новите.

3. Създаване на Mojo

Сега е време да създадем първото си моджо. Mojo е клас на Java, който представлява цел, която нашата приставка ще изпълни . Приставка съдържа един или повече mojos.

Нашият mojo ще бъде отговорен за преброяване на броя на зависимостите на даден проект.

3.1. Добавяне на зависимости

Преди да създадем mojo, трябва да добавим някои зависимости към нашия pom.xml :

  org.apache.maven maven-plugin-api 3.6.3   org.apache.maven.plugin-tools maven-plugin-annotations 3.6.0 provided   org.apache.maven maven-project 2.2.1  

The Maven-плъгин-API зависимостта се изисква и съдържа необходимите класове и интерфейси за създаване на нашето Mojo . The Maven-Plugin-анотации зависимостта е по-удобен за използване анотации в нашите класове. The Maven-проект зависимостта ни дава достъп до информацията за проекта, за който сме включили приставката.

3.2. Създаване на Mojo Class

Сега сме готови да създадем нашето mojo!

Mojo трябва да внедри интерфейса Mojo . В нашия случай ще продължим от AbstractMojo, така че ще трябва само да приложим метода за изпълнение :

@Mojo(name = "dependency-counter", defaultPhase = LifecyclePhase.COMPILE) public class DependencyCounterMojo extends AbstractMojo { // ... }

Както виждаме, броячът на зависимости е името на целта. От друга страна, ние сме го прикачили към фазата на компилиране по подразбиране, така че не е задължително да посочваме фаза, когато използваме тази цел.

За да имаме достъп до информацията за проекта, трябва да добавим MavenProject като параметър:

@Parameter(defaultValue = "${project}", required = true, readonly = true) MavenProject project;

Този обект ще бъде инжектиран от Maven, когато се създаде контекстът.

На този етап ние сме в състояние да приложим метода за изпълнение и да преброим броя на зависимостите на проекта:

public void execute() throws MojoExecutionException, MojoFailureException { List dependencies = project.getDependencies(); long numDependencies = dependencies.stream().count(); getLog().info("Number of dependencies: " + numDependencies); }

Методът getLog () осигурява достъп до дневника на Maven. В AbstractMojo вече дръжки на неговия жизнен цикъл.

3.3. Добавяне на параметри

Параметърът, който сме добавили преди, е само за четене и не може да бъде конфигуриран от потребителя. Освен това се инжектира от Maven, за да можем да кажем, че е някакъв специален.

В този раздел ще добавим параметър, където потребителите могат да определят обхвата на зависимостите, които искаме да преброим.

Следователно, нека създадем параметър на обхвата в нашето mojo:

@Parameter(property = "scope") String scope;

Задали сме само атрибута свойство . Позволява ни да зададем това свойство чрез командния ред или свойството pom . За останалите атрибути сме добре със стойностите по подразбиране.

Сега ще модифицираме нашия метод за изпълнение , за да използваме този параметър и ще филтрираме зависимостите при броене:

public void execute() throws MojoExecutionException, MojoFailureException  List dependencies = project.getDependencies(); long numDependencies = dependencies.stream() .filter(d -> (scope == null 

По-усъвършенстваните видове параметри са обяснени в официалната документация.

4. Тестване на приставката

Приключихме с разработката на приставката. Нека да го тестваме, за да видим дали работи!

На първо място, трябва да инсталираме приставката в нашето локално хранилище:

mvn clean install

В следващите раздели първо ще видим как да стартираме нашия плъгин от командния ред. След това ще разгледаме и как да го използваме в проект на Maven.

4.1. Изпълнение на нашата приставка

Можем да изпълним целта на приставката в командния ред, като посочим пълното й име:

mvn groupId:artifactId:version:goal

В нашия случай изглежда така:

mvn com.baeldung:counter-maven-plugin:0.0.1-SNAPSHOT:dependency-counter

Ако обаче сме спазили конвенцията за именуване на приставки, която споменахме в началото на този урок, Maven ще разреши префикса на нашата приставка и можем да съкратим командата:

mvn counter:dependency-counter

Забележете, че тази команда използва най-новата версия на приставката. Също така, имайте предвид, че трябва да добавим нашия groupId към pluginGroups на нашите settings.xml, така че Maven също търси в тази група:

 com.baeldung 

Ако проверим изхода на командата, можем да видим, че приставката отчита броя на зависимостите в pom.xml на нашия плъгин:

[INFO] Scanning for projects... [INFO] [INFO] ----------------------------------- [INFO] Building counter-maven-plugin Maven Mojo 0.0.1-SNAPSHOT [INFO] ----------------------------[ maven-plugin ]---------------------------- [INFO] [INFO] --- counter-maven-plugin:0.0.1-SNAPSHOT:dependency-counter (default-cli) @ counter-maven-plugin --- [INFO] Number of dependencies: 3 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 0.529 s [INFO] Finished at: 2019-11-30T20:43:41+01:00 [INFO] ------------------------------------------------------------------------

Можем също да зададем параметъра на обхвата чрез свойства на командния ред:

mvn counter:dependency-counter -Dscope=test

Забележете, че името на обхвата е това, което дефинирахме в атрибута свойство на нашия параметър в mojo.

4.2. Използване на нашия плъгин в проект

Нека тестваме сега нашия плъгин, като го използваме в проект!

Ще създадем много прост проект на Maven с някои зависимости, които нашият плъгин ще отчита:

 4.0.0 com.baeldung example pom 0.0.1-SNAPSHOT   org.apache.commons commons-lang3 3.9   junit junit 4.12 test   

Последното нещо е да добавим нашия плъгин към компилацията. Трябва изрично да зададем, че искаме да изпълним целта на брояча на зависимости :

   com.baeldung counter-maven-plugin 0.0.1-SNAPSHOT    dependency-counter     test    

Забележете, че сме посочили параметъра на обхвата в конфигурационния възел. Също така не сме посочили нито една фаза, защото нашето mojo е прикрепено към фазата на компилиране по подразбиране.

Сега просто трябва да стартираме фазата на компилация, за да изпълним нашия плъгин:

mvn clean compile

И нашата приставка ще отпечата броя на тестовите зависимости:

[INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------ [INFO] Building example 0.0.1-SNAPSHOT [INFO] --------------------------------[ pom ]--------------------------------- [INFO] [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ example --- [INFO] [INFO] --- counter-maven-plugin:0.0.1-SNAPSHOT:dependency-counter (default) @ example --- [INFO] Number of dependencies: 1 [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 0.627 s [INFO] Finished at: 2019-11-25T18:57:22+01:00 [INFO] ------------------------------------------------------------------------

В този урок ние не разглеждаме как да напишем модулни или интеграционни тестове за нашия плъгин, но Maven предоставя някои механизми за това.

5. Добавяне на документация

Когато създаваме приставка Maven, е важно да генерираме документация, за да улесним използването на други хора от нея .

Ще разгледаме накратко как да генерираме тази документация с maven-plugin-plugin .

maven-plugin-plugin вече е включен в проекта, но ще го актуализираме, за да използва най-новата версия.

Също така, ние ще направим същото за maven-site-plugin :

    org.apache.maven.plugins maven-plugin-plugin 3.6.0   org.apache.maven.plugins maven-site-plugin 3.8.2    

След това трябва да се уверим, че сме добавили javadoc към нашия Mojo и също така да добавим някои метаданни в pom.xml на приставката:

 Baeldung //www.baeldung.com/ 

След това трябва да добавим раздел за отчитане в нашия pom.xml :

   org.apache.maven.plugins maven-plugin-plugin    report      

Finally, we'll generate the documentation with the maven site command:

mvn site

Inside the target folder, we can find a site directory with all the HTML files generated. The plugin-info.html is the one containing the plugin documentation:

More options to add to our documentation can be found on the Maven plugin documentation guide.

6. Conclusion

In this tutorial, we've shown how to create a Maven plugin. We first implemented a simple plugin, which helped us see a typical Maven plugin project structure. Then, we covered some of the tools that Maven provides to help us develop plugins.

We've kept it simple to make things clearer, but at the same time, we've provided some useful links with the necessary information on how to create a more powerful plugin.

Както винаги, пълният изходен код за примерите е достъпен в GitHub.