Maven 4 API 插件描述符模型Plugin Descriptor Model完全指南从 plugin.mdo 到不可变 Java 模型【免费下载链接】mavenApache Maven core项目地址: https://gitcode.com/GitHub_Trending/ma/maven导读本篇指南聚焦于 Apache Maven 4 新增的插件描述符不可变模型Immutable Plugin Descriptor Model——它是 Maven 4 API 中定义插件元数据、配置与执行参数的核心数据模型最终以META-INF/maven/plugin.xml的形式驻留在每个插件 JAR 中。文章以 api/maven-api-plugin/src/site/markdown/index.md 文档为骨架结合仓库中 plugin.mdo 与 lifecycle.mdo 的完整字段定义、代码生成流程与测试用例带你掌握描述符模型如何由 Modello 从.mdo声明式生成、PluginDescriptor/MojoDescriptor/Parameter等核心类承载哪些语义以及如何用生成的Builder以不可变方式构造插件描述符。一、插件描述符模型Maven 4 插件元数据的新家1.1 文档定位与包结构在 Maven 4 的模块化 API 架构中插件描述符模型位于org.apache.maven.api.plugin.descriptor包其包级注释明确说明Provides classes for Maven plugin descriptors that define plugin metadata, configuration, and execution parameters. These descriptors are typically stored in plugin.xml files within the META-INF/maven directory of plugin JARs.见 package-info.java该包由 api/maven-api-plugin 模块提供模块描述为 Maven 4 API - Immutable Plugin model.其依赖仅包括maven-api-annotations与maven-api-xml不依赖任何运行时容器——这是一个纯粹的、可独立复用的数据模型 API。1.2 描述符的物理载体plugin.xmlplugin.mdo的模型级注释给出了描述符的物理位置与语义Maven 4 Plugin descriptor, stored inMETA-INF/maven/plugin.xmlin a plugins jar artifact. This descriptor is generally using the information contained in the annotations of the plugin api.也就是说Maven 4 中一个插件 JAR 内的META-INF/maven/plugin.xml就是本模型的实例化产物其内容通常由插件 API 上的注解如Mojo、Parameter等推导而来。这一约定在实现层同样被引用解析插件元数据时PluginsMetadataGenerator.java 中常量PLUGIN_DESCRIPTOR_LOCATION META-INF/maven/plugin.xml直接确认了读取位置。二、模型从何而来Modello 声明式生成与手写 Java 类不同Maven 4 的插件描述符模型采用ModelloMODELLO 2.0声明式建模 代码生成的方式。模型的唯一事实来源是两个.mdo文件plugin.mdo678 行定义插件描述符本体PluginDescriptor、MojoDescriptor、Parameter 等类lifecycle.mdo162 行定义自定义生命周期映射模型LifecycleConfiguration、Lifecycle、Phase、Execution。生成行为在 pom.xml 中通过modello-maven-plugin的两个 execution 配置完成plugin groupIdorg.codehaus.modello/groupId artifactIdmodello-maven-plugin/artifactId executions execution idmodello-plugin/id goalsgoalvelocity/goalgoalxdoc/goalgoalxsd/goal/goals phasegenerate-sources/phase configuration velocityBasedir${project.basedir}/../../src/mdo/velocityBasedir version2.0.0/version models modelsrc/main/mdo/plugin.mdo/model /models templates templatemodel.vm/template /templates params parampackageModelV4org.apache.maven.api.plugin.descriptor/param /params /configuration /execution !-- 第二个 executionidmodello-lifecycle以同样方式处理 lifecycle.mdo 目标包为 org.apache.maven.api.plugin.descriptor.lifecycle -- /executions /plugin要点解读velocity 模板model.vm是共享的代码生成模板位于仓库 src/mdo/model.vm与ImmutableCollections.java、InputLocation.java等手写辅助类共同构成生成器的骨架两个模型两个包plugin.mdo生成到org.apache.maven.api.plugin.descriptorlifecycle.mdo生成到其子包org.apache.maven.api.plugin.descriptor.lifecycle产物除 Java 源码外还生成xdoc站点文档与xsdXML Schema。plugin.mdo头部声明的 schema 位置为https://maven.apache.org/xsd/plugin-${version}.xsd命名空间为http://maven.apache.org/PLUGIN/${version}。从源码结构看生成出来的 Java 类本身并不提交在仓库中src/main/java下只有package-info.java而是在generate-sources阶段由 Modello 生成——这正是模型即源码的声明式开发方式。三、PluginDescriptor根元素模型PluginDescriptor是plugin.xml的根元素类rootElement在.mdo中对应class rootElementtrue xml.tagNameplugin。它描述的是插件整体的元信息。3.1 字段清单与语义字段版本类型必填默认值说明name1.0.0String否—插件名称description1.0.0String否—插件描述groupId1.0.0String是—插件 groupIdartifactId1.0.0String否—插件 artifactIdversion1.0.0String是—插件版本goalPrefix1.0.0String否—命令行前缀如mvn compiler:compile中的compilerisolatedRealm1.0.0boolean否false是否使用隔离的 class realminheritedByDefault1.0.0boolean否true插件配置默认是否被继承requiredJavaVersion1.1.0String否—支持的 Java 版本范围见下文requiredMavenVersion1.1.0String否—支持的 Maven 版本范围优先级高于 POM 的 prerequisitesmojos1.0.0MojoDescriptor[]否—插件提供的每个 Mojo 的描述dependencies1.0.0/1.1.0Dependency[]否—插件运行所需的依赖集合其中两个新增字段值得特别说明版本范围语法requiredJavaVersion/requiredMavenVersion自 Maven 4.0.0-alpha-3 起既支持数学区间语法如[2.0.10,2.1.0),[3.0,)也支持单版本短形式2.2.1等价于[2.2.1,)即最低版本。requiredMavenVersion的描述特别强调此值优先于 POM 中的 Maven prerequisites是 Maven 4 声明插件运行环境约束的首选方式。便捷方法模型中还以 codeSegment 方式为生成的类注入了两个派生方法版本 2.0.0public String getPluginLookupKey() { return groupId : artifactId; } public String getId() { return groupId : artifactId : version; }getPluginLookupKey()用于插件查找/解析键getId()则给出完整的插件坐标标识。四、MojoDescriptor单个目标的完整语义MojoDescriptorxdoc anchormojo描述插件提供的每一个 Mojo目标。理解它就理解了 Maven 插件执行的绝大部分行为约定。其字段可分为若干组。4.1 身份与执行定位字段版本类型必填默认值说明goal1.0.0String是—目标名用户从命令行或 POM 中引用implementation1.0.0String否—Mojo 的全限定类名非 Java Mojo 可为脚本路径language1.0.0String否java实现语言java、beanshell 等phase1.0.0String否—默认绑定的生命周期阶段executePhase/executeGoal/executeLifecycle1.0.0String否—执行前需要触发的阶段/目标/生命周期instantiationStrategy1.0.0/1.1.0String否per-lookup实例化策略executionStrategy1.0.0/1.1.0String否once-per-session执行策略once-per-session、always关于phase.mdo中有一段重要的澄清性说明引用自模型注释它并不会让插件声明一加入 POM 就神奇地自动运行其作用仅仅是允许用户在execution中省略phase元素——绑定的执行仍然必须通过executions显式声明。4.2 依赖解析与收集要求这是 Maven 插件行为契约中最关键的一组字段值得注意的是它在 2.0.0 版本经历了字段改名1.0.0/1.1.0 旧字段2.0.0 新字段说明requiresDependencyResolutiondependencyResolution要求指定 classpath 的依赖在执行前完成解析取值compile、runtime、test、compileruntime、runtimesystemrequiresDependencyCollectiondependencyCollection只要求收集依赖信息、不解析文件适用于早期生命周期阶段此时部分项目尚未构建完整解析可能失败requiresDirectInvocationdirectInvocationOnly只能被直接调用requiresProjectprojectRequired必须在项目中运行默认truerequiresOnlineonlineRequired需要在线模式threadSafe1.0.0/1.1.0—2.0.0 移除线程安全标记标记线程安全可避免并行构建警告dependencyCollection的注释还特别提醒不解析文件意味着项目关联的 artifact 可以缺少文件这类注解适合只想分析传递依赖集合的 Mojo——典型场景就是早期生命周期阶段。4.3 其他行为标记字段类型默认值说明aggregatorbooleanfalse多模块聚合运行inheritedByDefaultbooleantrueMojo 是否被继承v4Api1.1.0booleanfalse标记使用 Maven 4 API隐式与早期 Maven 不兼容仅在 Maven 4 中被评估sinceString—加入 API 的版本类似 Javadoc sincedeprecatedString—弃用原因描述用户使用时会触发警告configuratorString—注入参数时使用的 configurator 类型通常由实现语言推导可指定自定义 ComponentConfiguratorcomposer1.0.0/1.1.0String—组合器已由后续版本演进4.4 派生字段与新版关联自 2.0.0 起模型新增了两个由 Modello 的xml.format表达式自动计算的字段field xml.format((PluginDescriptor.Builder) context.peekLast()).build().getId() quot;:quot; mojoDescriptor.build().getGoal() nameid/name !-- 形如 groupId:artifactId:version:goal -- /field field xml.format((PluginDescriptor.Builder) context.peekLast()).build().getGoalPrefix() quot;:quot; mojoDescriptor.build().getGoal() namefullGoalName/name !-- 形如 prefix:goal -- /field同时 2.0.0 还引入两个新的关联集合resolutionsResolution[]依赖收集/解析注入声明Resolution包含field注入字段名、pathScope扁平化依赖的路径作用域、requestTypecollect、flatten、resolve之一afterLinksAfterLink[]来自 Mojo 类上After注解的生命周期排序约束since 4.0.0。AfterLink是 Maven 4 精细化控制跨项目执行顺序的新机制三个字段字段必填说明phase是本 Mojo 应在其后执行的目标阶段名type是指针类型PROJECT同项目阶段排序、DEPENDENCIES跨项目依赖排序、CHILDREN父子模块排序scope否依赖作用域仅在typeDEPENDENCIES时有意义如compile、runtime、test五、Parameter 与 Requirement配置注入契约5.1 ParameterMojo 参数描述Parameter描述单个可配置参数字段如下字段类型必填默认值说明nameString是—参数名用于 POM 配置与默认值引用aliasString否—配置别名当 Mojo 字段名对用户不友好时提供更友好的配置名typeString是—参数 Java 类型用于校验注入表达式结果requiredboolean否—是否必填注入前用于校验配置避免 Mojo 在半成品状态执行editableboolean否true是否允许用户直接配置设为false可强制用户使用通用 POM 元素如finalName而非插件配置也可防止 List 类型参数被注入成字符串列表descriptionString否—参数用途说明sinceString否—加入版本deprecatedString否—弃用说明配置时触发警告expression2.0.0String否—参数表达式允许用户用 user property / system property / project property 覆盖默认值defaultValue2.0.0String否—默认值作为在注入或运行时求值的表达式editablefalse的典型场景在模型注释中给出了两个具体例子强制用户修改buildfinalName/而不是在插件配置里直接指定 finalName以及确保期望元素类型为 Artifact 的 List 参数不会被注入一串 String。5.2 Requirement已废弃的组件注入Requirement1.0.0/1.1.0描述 Plexus 风格的组件需求对应旧Component注解字段包括必填的rolePlexus 组件角色、role-hintrole 提示、field-name被注入的字段名。模型注释明确将其标记为Deprecated并建议改用 JSR 330 注解注入组件而无需此描述符。MojoDescriptor.requirements字段同样带有 Deprecated 说明。这是 Maven 4 推动标准 DI 的明确信号。5.3 Dependency插件自身运行依赖Dependency描述插件运行所需依赖1.0.0/1.1.0字段groupId必填、artifactId必填、version、type默认jar。其用途是让插件独立于其 POM 声明运行所需类库。六、Lifecycle 模型自定义生命周期映射除插件描述符外本模块还生成自定义生命周期映射模型org.apache.maven.api.plugin.descriptor.lifecycle包物理载体为插件 JAR 内的META-INF/maven/lifecycle.xml见 lifecycle.mdo 模型注释。层级结构为LifecycleConfiguration (根元素 lifecycles) └── Lifecycle (id phases) └── Phase (id executionPoint priority executions configuration) └── Execution (configuration goals)Phase的两个 2.0.0 新属性值得关注executionPoint若指定如before、after将本阶段标识为动态阶段用于装饰指定的阶段priorityint默认0阶段内执行次序的优先级。Phase内嵌的 codeSegment 给出了**有效 IDeffectiveId**的计算逻辑这正是动态阶段在生命周期执行时被识别的关键public String getEffectiveId() { if (executionPoint null) { if (priority 0) { return id; } return id [ priority ]; } if (priority 0) { return executionPoint : id; } return executionPoint : id [ priority ]; }即有效 ID 形如generate-sources、integration-test[1000]或after:integration-test[1000]把装饰点 阶段 优先级编码进一个可排序的字符串。七、不可变性与 Builder 实践7.1 生成类的不可变构造方式原文档明确指出模型生成物中包括带Builder内部类的 Java 源码用于创建不可变实例。生成的不可变模型类是final风格、字段在构造时固定必须通过内部Builder完成实例构建。仓库中的测试 ExtendedPluginDescriptorTest.java 同时验证了两件事模型类可被继承扩展以及Builder 链式 API 的使用顺序约束static class ExtendedPluginDescriptor extends PluginDescriptor { private final String additionalField; ExtendedPluginDescriptor(Builder builder) { super(builder); this.additionalField builder.additionalField; } static class Builder extends PluginDescriptor.Builder { protected String additionalField; Builder() { super(false); } public Builder additionalField(String additionalField) { this.additionalField additionalField; return this; } Override public ExtendedPluginDescriptor build() { return new ExtendedPluginDescriptor(this); } } } Test void testExtendedPluginDescriptor() { ExtendedPluginDescriptor.Builder builder new ExtendedPluginDescriptor.Builder(); // 必须先调用子类 Builder 的方法否则流式 API 无法工作 builder.additionalField(additional) .groupId(org.apache.maven) .artifactId(maven-plugin-api) .version(1.0.0); ExtendedPluginDescriptor descriptor builder.build(); assertEquals(additional, descriptor.getAdditionalField()); assertEquals(org.apache.maven, descriptor.getGroupId()); }这个测试蕴含两个重要的实践结论扩展模式要扩展生成的模型类需要同时继承模型类和它的Builder调用super(false)并重写build()返回子类型子类字段必须在调用父类链式方法之前设置否则流式 API 会因类型转换而失效测试注释明确指出了这一点不可变语义实例创建后字段不可再变groupId/artifactId/version直接通过 Builder 方法注入这正是 Maven 4 描述符模型与旧org.apache.maven.plugin.descriptor.PluginDescriptor可变 POJO在编程模型上的根本差异。7.2 与 Maven 3 时代模型的差异从源码结构看旧模型compat/maven-plugin-api等兼容模块是可变、可继承的传统 POJO新模型强调不可变与 Builder 构造属于api/maven-api-plugin的新一代 API新模型采用 Modello 声明式生成 maven-api-annotations注解协同模块依赖见 pom.xml.mdo文件是唯一事实来源plugin.mdo中字段的1.0.0 / 1.1.0 / 2.0.0版本标注反映了模型演进历史如requiresDependencyResolution→dependencyResolution的改名、v4Api的引入、afterLinks/resolutions的加入均为 Maven 4 特性since 4.0.0、since Maven 4.0.0-alpha-3。八、结语一份模型三层价值围绕 api/maven-api-plugin/src/site/markdown/index.md 所指向的 Plugin Descriptor Model本仓库给出了完整的可研读路径声明层plugin.mdo 与 lifecycle.mdo 定义了全部类、字段、默认值与派生逻辑生成层pom.xml 中的modello-maven-plugin配置驱动 model.vm 模板在generate-sources阶段产出不可变 Java 类、XSD 与文档消费层生成的plugin.xml/lifecycle.xml由实现模块读取如 PluginsMetadataGenerator.java 中的META-INF/maven/plugin.xml定位常量测试 ExtendedPluginDescriptorTest.java 则示范了面向扩展的 Builder 使用范式。无论你是 Maven 插件开发者、希望理解 Maven 4 内部插件元数据流转的贡献者还是想复用它来构建自有描述符体系的架构师都可以从这三个层次切入把模型即文档的声明式设计思路应用到自己的项目中去。【免费下载链接】mavenApache Maven core项目地址: https://gitcode.com/GitHub_Trending/ma/maven创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考