开发工具后端【免费下载链接】byte-buddyRuntime code generation for the Java virtual machine.项目地址https://gitcode.com/gh_mirrors/by/byte-buddy点击查看免费下载Byte Buddy Maven 插件让你在 Maven 构建过程中对编译产物class 文件执行字节码增强从而将运行时织入如返回值缓存、方法拦截、字段注入提前到构建期完成。本文以官方 READMEbyte-buddy-maven-plugin/README.md为核心骨架结合仓库源码与测试用例完整讲解插件的激活方式、transform系列 goal 的适用场景、官方内置CachedReturnPlugin的用法、自定义Plugin的编写与定位、构造器注入、插件自动发现、增量构建以及全部配置项。读完本文你将能够在自己的 Maven 项目中稳定地接入构建期字节码增强并理解其底层执行原理。1. 插件激活在 POM 中声明 byte-buddy-maven-plugin要激活构建期字节码增强只需要在项目的pom.xml中声明该插件并配置transformations。以下是官方 README 给出的最小完整配置build plugins plugin groupIdnet.bytebuddy/groupId artifactIdbyte-buddy-maven-plugin/artifactId versionLATEST/version executions execution goals goaltransform/goal /goals /execution /executions configuration transformations transformation groupIdnet.bytebuddy/groupId artifactIdbyte-buddy/artifactId versionLATEST/version pluginnet.bytebuddy.build.CachedReturnPlugin/plugin /transformation /transformations /configuration /plugin /plugins /build配置要点goaltransform/goal将插件绑定到 Maven 生命周期默认阶段为process-classes对应源码 ByteBuddyMojo.java 中ForProductionTypes.WithoutRuntimeDependencies的Mojo(name transform, defaultPhase LifecyclePhase.PROCESS_CLASSES, ...)声明。transformations是插件的核心配置每一个transformation指定一个要应用的字节码增强插件类plugin是必填项其余 Maven 坐标可省略省略时回退到当前项目自身的坐标见下文第 4 节。示例中groupIdnet.bytebuddy/groupId、artifactIdbyte-buddy/artifactId、versionLATEST/version表明CachedReturnPlugin类来自net.bytebuddy:byte-buddy这个构件。官方推荐的LATEST写法在发布构建中建议替换为具体的版本号。需要说明的是version若省略会取当前项目的版本而CachedReturnPlugin位于net.bytebuddy:byte-buddy构件内源码见 CachedReturnPlugin.java因此这里必须显式给出坐标。2. 四个核心 goaltransform 家族与它们的差异官方 README 指出transform作用于主源码集main source set而transform-test可转换测试类此外还有transform-runtime与transform-extended。这四个 goal 的差异在于处理对象与依赖解析范围ResolutionScope全部定义在 ByteBuddyMojo.java 的ForLifecycleTypes内部类中goal默认绑定阶段处理对象依赖解析范围源码依据transformprocess-classes生产类主输出目录target/classesCOMPILE编译期 classpathWithoutRuntimeDependenciestransform-runtimeprocess-classes生产类COMPILE_PLUS_RUNTIME含运行时依赖WithRuntimeDependenciestransform-extendedprocess-classes生产类除test、import作用域之外的所有依赖WithExtendedDependenciestransform-testprocess-test-classes测试类target/test-classesTEST完整测试 classpathForTestTypes选择依据transform最常用适用于插件只需编译期依赖即可完成增强的场景。transform-runtime当插件在应用时还需要读取运行时依赖中的类例如对运行时库中的类型进行匹配或委托时使用。其requiresDependencyResolution ResolutionScope.COMPILE_PLUS_RUNTIMEclasspath 取自project.getRuntimeClasspathElements()。transform-extended把除test与import之外的所有构件project.getArtifacts()加入 classpath并额外加入输出目录自身适合依赖面较宽的增强场景。transform-test在process-test-classes阶段处理测试类classpath 取自project.getTestClasspathElements()Mojo声明见 ByteBuddyMojo.java。多个 goal 可以在同一个插件的executions中分别声明例如同时增强主类与测试类executions execution goals goaltransform/goal goaltransform-test/goal /goals /execution /executions3. 官方内置插件CachedReturnPlugin 与 Enhance 注解README 示例中的net.bytebuddy.build.CachedReturnPlugin是随 Byte Buddy 分发的标准构建期插件其完整实现在 CachedReturnPlugin.java。它的作用是把被Enhance注解标记的方法的返回值缓存到一个合成字段synthetic field中从而避免重复计算。使用方式在目标方法上添加注解public class Sample { CachedReturnPlugin.Enhance public String expensive() { // 只会在第一次调用时执行 return computeExpensiveValue(); } }其实现原理从源码 CachedReturnPlugin.java 可以确认匹配所有声明了Enhance的非 bridge 方法生成一个private synthetic字段字段名默认取方法名 _ 随机串也可通过Enhance(fieldName)显式指定通过Advice在该方法上织入“先读字段非默认值则直接返回否则执行原方法体并写回字段”的逻辑。官方文档与源码注释明确给出以下限制务必注意该缓存非线程安全仅当缓存值“冻结”对象只含final字段时可用于并发场景——这样设计是为了避免声明volatile字段。对于基本类型返回值用该类型的默认值如0、false表示“尚未缓存”对于引用类型用null表示“尚未缓存”。因此如果方法本身可能返回默认值或null缓存机制不会生效。不能缓存抽象方法、带参数的方法以及void方法源码中分别抛出IllegalStateException。默认构造器CachedReturnPlugin()在字段名冲突时会抛出异常若希望遇到已存在的字段名时跳过可使用new CachedReturnPlugin(true)并通过arguments传入见第 5 节。该插件实现的是Plugin与Plugin.Factory两个接口close()为空实现无需关闭。4. 编写自定义 Plugin实现 net.bytebuddy.build.Plugin 接口当内置插件不满足需求时自定义插件必须实现 Byte Buddy 的Plugin接口。该接口包含三个方法boolean matches(TypeDescription target)判断是否处理某个类型DynamicType.Builder? apply(DynamicType.Builder? builder, TypeDescription typeDescription, ClassFileLocator classFileLocator)执行字节码增强并返回新的 buildervoid close()在插件使用完毕后释放资源。仓库测试模块中的 SimplePlugin.java 是教科书式的例子——它把名为foo的方法的返回值固定为quxpublic class SimplePlugin implements Plugin { public boolean matches(TypeDescription target) { return target.getName().equals(foo.Bar); } public DynamicType.Builder? apply(DynamicType.Builder? builder, TypeDescription typeDescription, ClassFileLocator classFileLocator) { return builder.method(named(foo)).intercept(FixedValue.value(qux)); } public void close() { /* do nothing */ } }在pom.xml中按第 1 节的transformation结构注册即可。坐标回退规则源码见 CoordinateConfiguration.javatransformation中的groupId、artifactId、version、packaging任一省略时都回退到当前项目自身的对应值。因此如果插件类就在当前项目自身或其依赖树内编译产物中可以只写plugin一项如测试资源 simple.pom.xml 所示如果插件类位于另一个构件例如独立的增强库则需要像 README 示例那样给出完整坐标插件会通过ClassLoaderResolver解析并加载该构件ClassLoaderResolver.java。5. 构造器注入File、Log、BuildLogger 与显式 arguments官方 README 说明插件可以声明一个构造器接收File、BuildLogger或 Gradle 特定的Logger类型参数此时插件会获得 class 文件根目录或合适的日志器。结合源码 ByteBuddyMojo.java插件实例通过Plugin.Factory.UsingReflection创建并按构造器参数类型自动注入以下值参数类型注入内容File被转换的 class 文件根目录或 jar 文件File[]完整的 classpath 元素列表org.apache.maven.plugin.logging.LogMaven 日志器net.bytebuddy.build.BuildLogger包装为MavenBuildLogger的构建日志器除自动注入外还可以在transformation中通过arguments显式传参。参数按索引 字符串值配对配置结构定义在 PluginArgument.java值为index与value字段解析为ArgumentResolver.ForIndex.WithDynamicType。测试资源 argument.pom.xml 展示了向构造器ArgumentPlugin(int value)传参42的写法transformation pluginnet.bytebuddy.test.ArgumentPlugin/plugin arguments argument index0/index value42/value /argument /arguments /transformation对应的插件类 ArgumentPlugin.java 接收该参数并注入到方法返回值中测试 ByteBuddyMojoTest.java 验证了转换后调用foo方法返回的是42而非原始值。需要留意自动注入与显式arguments同时存在时索引参数会与类型注入解析器组合使用因此不要把显式参数放在会被类型注入占用的索引上以避免冲突。6. 插件自动发现META-INF/net.bytebuddy/build.plugins 与 Discovery 策略README 指出如果插件 jar 文件在META-INF/net.bytebuddy/build.plugins文件中声明了插件类名每行一个全限定类名且该 jar 被声明为byte-buddy-maven-plugin的依赖那么插件会被自动发现并应用无需在transformations中显式注册。自动发现由Discovery枚举控制其四个取值与语义定义在 Discovery.javaDiscovery 值行为EMPTY默认仅当没有任何显式注册的 transformation 时才执行发现UNIQUE始终尝试发现但跳过已被显式注册的同名插件ALL始终尝试发现会记录显式配置以便去重NONE从不发现通过discoveryUNIQUE/discovery等配置启用。扫描入口是Plugin.Engine.Default.scan(ClassLoader)在 ByteBuddyMojo.java 中分别对插件自身的类加载器以及当classPathDiscoverytrue/classPathDiscovery时当前项目 classpath 构造的URLClassLoader执行扫描。classPathDiscovery默认false官方文档建议慎用因为它可能误触发 classpath 上偶然出现的插件但在依赖较少、想借用 Maven 依赖版本管理的项目中可作为便利手段。7. 其余配置项一览含默认值除transformations、discovery外ByteBuddyMojo.java 还暴露了以下配置项配置项默认值作用initialization默认REBASE入口点指定EntryPoint见第 8 节suffix空随机后缀重新基线化rebase时追加到原方法名后的固定后缀failOnLiveInitializertrue转换过程产生“存活初始化器”live initializer时是否抛异常skipfalse设为true时跳过当前模块的转换warnOnMissingOutputDirectorytrue输出目录不存在时是否告警warnOnEmptyTypeSettrue未转换任何类型时是否告警failFasttrue某个插件无法应用时是否立即失败false则最后汇总失败extendedParsingfalse是否解析 class 文件调试信息以提取参数名对应PoolStrategy.EXTENDEDthreads0并行转换线程数0表示串行staleMilliseconds0与上次构建时间戳之间允许的“陈旧”容差毫秒数-1禁用陈旧检测multiReleaseVersion未设置解析多版本 jarmulti-release jar时使用的 Java 版本其中staleMilliseconds与每次执行后写入target/maven-status/artifactId/goal/executionId/staleness的时间戳配合ByteBuddyMojo.java用于过滤上次构建之后未修改过的 class 文件避免重复转换。8. 自定义初始化器initialization 与 EntryPoint每次转换都始于一个ByteBuddy实例和对类型的初始处理方式rebase、redefine 等这由EntryPoint决定。默认值为REBASE对类型重新基线化保留原有方法实现。initialization的entryPoint属性可以是EntryPoint.Default中的枚举名常量如REBASE、REDEFINE、DECORATE等或一个自定义EntryPoint实现类的全限定名此时同样支持用 Maven 坐标指定其所在构件缺省回退到当前项目坐标。自定义入口点的解析逻辑在 Initialization.java先匹配EntryPoint.Default常量否则通过反射实例化自定义类。测试中的 SimpleEntryPoint.java 展示了实现EntryPoint并委托给byteBuddy.rebase(...)的写法对应的配置见测试资源 entry.pom.xmlinitialization entryPointnet.bytebuddy.test.SimpleEntryPoint/entryPoint /initialization此外initialization还支持validated布尔属性默认true设为false时入口点被EntryPoint.Unvalidated包装跳过类型校验。suffix配置则对应底层MethodNameTransformer.Suffixing未设置时使用withRandomSuffix()随机后缀设置后使用固定后缀。测试 ByteBuddyMojoTest.java 验证了suffixqux时 rebase 出的原方法名为foo$qux配置样例见 suffix.pom.xml。9. 增量构建incremental 与 Maven BuildContextREADME 指出插件支持 Maven 的BuildContext与增量构建特性目前由 Eclipse IDE 支持需要显式设置incremental为true启用。其实现位于 ByteBuddyMojo.java 的ForLifecycleTypes.apply当incrementaltrue且存在可用的BuildContext时若context.isIncremental()为真则用context.newScanner(sourceDirectory)扫描变更的.java源文件将其转换为类名前缀并通过Plugin.Engine.Source.Filtering只处理这些类含其内部类见FilePrefixMatcher转换完成后对每个被转换的类型调用context.refresh(...)通知 IDE 刷新若构建上下文不可用或无法增量则退化为处理全部 class 文件。增量场景下源目录取project.getBuild().getSourceDirectory()主代码或getTestSourceDirectory()测试代码输出目录对应getOutputDirectory()/getTestOutputDirectory()。10. 进阶 goaltransform-location* 与 transform-dependencies除生命周期绑定的四个 goal 外源码还提供了面向“任意位置”的转换目标定义在ForExplicitLocations与ForDependencyFolder中goal作用transform-location-empty把指定的源目录或 jar 文件转换到目标目录或 jar 文件不自动引入项目 classpathtransform-location同左但额外引入编译期 classpathtransform-location-runtime同左额外引入运行时 classpathtransform-location-extended同左引入除 test/import 外的全部依赖transform-location-test同左引入完整测试 classpathtransform-dependencies转换一个目录下的全部 jar通常用于项目依赖可选target输出目录这类 goal 需要配置source必填与target以及可选的dependencies以坐标方式额外解析依赖并加入 classpath。transform-dependencies的target缺省时原地覆盖source目录中的 jar见 ByteBuddyMojo.java。11. 底层执行流程从 execute 到 Plugin.Engine理解插件的内部流水线有助于排查问题。以transform为例核心调用链如下全部位于 ByteBuddyMojo.javaexecute()L249-L319校验初始化状态与skip标记将transformations包装为Transformer.ForConfiguredPlugin按discovery策略扫描并注册自动发现的插件若最终 transformer 为空则打印警告并跳过resolveClassPathElements()按 goal 的依赖作用域解析 classpath 元素同时结合dependencyManagement中的坐标版本transform()L358-L475加载/创建ClassLoaderResolver与仓库会话RepositorySystemSession通过Plugin.Factory.UsingReflection实例化每个插件并附加类型注入的参数解析器File、Log、BuildLogger、File[]与显式参数解析EntryPoint探测 Java 版本优先读取maven.compiler.release其次maven.compiler.target再查maven-compiler-plugin的release/target配置都找不到时回退到当前 JVM 版本并给出“构建受 JDK 影响”的警告构造ClassFileLocator平台类加载器 每个 classpath 元素的ForJarFile/ForFolder支持multiReleaseVersion以Plugin.Engine.Default.of(entryPoint, classFileVersion, methodNameTransformer)构建引擎按extendedParsing选择PoolStrategy.EXTENDED或FAST按failOnLiveInitializer/failFast配置错误处理按threads选择串行或并行调度器apply(source, target, factories)执行转换并返回Summary依据Summary处理结果有失败类型则抛MojoExecutionException未转换任何类型且warnOnEmptyTypeSettrue时告警最后写入 staleness 文件。这些步骤在 ByteBuddyMojoTest.java 中有完整的端到端验证testSimpleTransformation、testSimpleTransformationWithArgument、testLiveInitializer/testLiveInitializerAllowed、testIllegalTransformer等分别覆盖了正常转换、显式参数、live initializer 失败与放行、非法插件等场景可作为理解各配置项行为的权威参考。12. 常见问题与排查建议1. 构建日志出现 “No transformations are specified or discovered. Skipping plugin application.”说明transformations为空且未发现任何插件。检查transformations配置是否存在、plugin类名是否拼写正确、坐标能否被 Maven 解析。2. 转换产生 live initializer 导致构建失败构建期转换的对象是尚未加载的 class 文件若插件要求“存活初始化器”如把类型静态字段设置为用户拦截器则无法在构建期完成。若确需放行可设置failOnLiveInitializerfalse/failOnLiveInitializer对应测试资源 live.allowed.pom.xml但需自行承担运行时行为风险——测试testLiveInitializerAllowed即展示了放行后运行期可能抛出NullPointerException的情况。3. 报 “Cannot resolve plugin: ...”MojoExecutionException插件坐标不可达或类无法加载。确认构件坐标存在、版本可解析若插件类位于当前项目自身应省略坐标只保留plugin。4. 报 “Cannot cache the value of ...”使用CachedReturnPlugin时违反了其约束方法带参数、返回void或为抽象方法。请参见第 3 节的限制清单。5. 增量构建未生效确认已设置incrementaltrue/incremental且构建运行于支持BuildContext的环境如 Eclipse IDE 的增量编译否则插件会退化为全量处理并打印 debug 日志 “Cannot build incrementally - all class files are processed”。13. 小结Byte Buddy Maven 插件把字节码增强从运行期前置到构建期通过transform系列 goal 覆盖主类、测试类与依赖转换通过CachedReturnPlugin提供开箱即用的返回值缓存并借助Plugin接口、构造器注入、自动发现与增量构建机制为 Maven 项目提供了一条完整、可扩展的构建期字节码处理链路。如需深入研读实现细节建议依次阅读 ByteBuddyMojo.java、Discovery.java、Initialization.java并结合 CachedReturnPlugin.java 与 ByteBuddyMojoTest.java 中的用例验证行为。赞分享开发工具后端【免费下载链接】byte-buddyRuntime code generation for the Java virtual machine.项目地址https://gitcode.com/gh_mirrors/by/byte-buddy点击查看免费下载相关推荐Byte Buddy构建插件终极指南Maven与Gradle集成完全教程Byte Buddy构建插件终极指南Maven与Gradle集成完全教程 Byte Buddy是Java虚拟机的运行时代码生成工具它提供了强大的字节码增强能开发工具后端Java字节码增强终极指南使用Byte Buddy重构遗留代码的完整流程Java字节码增强终极指南使用Byte Buddy重构遗留代码的完整流程 在Java开发中我们经常会遇到需要修改或增强现有类功能的情况特别是在处理遗留代码开发工具后端Java字节码增强终极指南Byte Buddy如何实现从Java 5到Java 25的完美兼容Java字节码增强终极指南Byte Buddy如何实现从Java 5到Java 25的完美兼容 在当今快速迭代的Java生态系统中多版本兼容性已成为开发工具开发工具后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
开发工具后端【免费下载链接】byte-buddyRuntime code generation for the Java virtual machine.项目地址https://gitcode.com/gh_mirrors/by/byte-buddy点击查看免费下载Byte Buddy Maven 插件让你在 Maven 构建过程中对编译产物class 文件执行字节码增强从而将运行时织入如返回值缓存、方法拦截、字段注入提前到构建期完成。本文以官方 READMEbyte-buddy-maven-plugin/README.md为核心骨架结合仓库源码与测试用例完整讲解插件的激活方式、transform系列 goal 的适用场景、官方内置CachedReturnPlugin的用法、自定义Plugin的编写与定位、构造器注入、插件自动发现、增量构建以及全部配置项。读完本文你将能够在自己的 Maven 项目中稳定地接入构建期字节码增强并理解其底层执行原理。1. 插件激活在 POM 中声明 byte-buddy-maven-plugin要激活构建期字节码增强只需要在项目的pom.xml中声明该插件并配置transformations。以下是官方 README 给出的最小完整配置build plugins plugin groupIdnet.bytebuddy/groupId artifactIdbyte-buddy-maven-plugin/artifactId versionLATEST/version executions execution goals goaltransform/goal /goals /execution /executions configuration transformations transformation groupIdnet.bytebuddy/groupId artifactIdbyte-buddy/artifactId versionLATEST/version pluginnet.bytebuddy.build.CachedReturnPlugin/plugin /transformation /transformations /configuration /plugin /plugins /build配置要点goaltransform/goal将插件绑定到 Maven 生命周期默认阶段为process-classes对应源码 ByteBuddyMojo.java 中ForProductionTypes.WithoutRuntimeDependencies的Mojo(name transform, defaultPhase LifecyclePhase.PROCESS_CLASSES, ...)声明。transformations是插件的核心配置每一个transformation指定一个要应用的字节码增强插件类plugin是必填项其余 Maven 坐标可省略省略时回退到当前项目自身的坐标见下文第 4 节。示例中groupIdnet.bytebuddy/groupId、artifactIdbyte-buddy/artifactId、versionLATEST/version表明CachedReturnPlugin类来自net.bytebuddy:byte-buddy这个构件。官方推荐的LATEST写法在发布构建中建议替换为具体的版本号。需要说明的是version若省略会取当前项目的版本而CachedReturnPlugin位于net.bytebuddy:byte-buddy构件内源码见 CachedReturnPlugin.java因此这里必须显式给出坐标。2. 四个核心 goaltransform 家族与它们的差异官方 README 指出transform作用于主源码集main source set而transform-test可转换测试类此外还有transform-runtime与transform-extended。这四个 goal 的差异在于处理对象与依赖解析范围ResolutionScope全部定义在 ByteBuddyMojo.java 的ForLifecycleTypes内部类中goal默认绑定阶段处理对象依赖解析范围源码依据transformprocess-classes生产类主输出目录target/classesCOMPILE编译期 classpathWithoutRuntimeDependenciestransform-runtimeprocess-classes生产类COMPILE_PLUS_RUNTIME含运行时依赖WithRuntimeDependenciestransform-extendedprocess-classes生产类除test、import作用域之外的所有依赖WithExtendedDependenciestransform-testprocess-test-classes测试类target/test-classesTEST完整测试 classpathForTestTypes选择依据transform最常用适用于插件只需编译期依赖即可完成增强的场景。transform-runtime当插件在应用时还需要读取运行时依赖中的类例如对运行时库中的类型进行匹配或委托时使用。其requiresDependencyResolution ResolutionScope.COMPILE_PLUS_RUNTIMEclasspath 取自project.getRuntimeClasspathElements()。transform-extended把除test与import之外的所有构件project.getArtifacts()加入 classpath并额外加入输出目录自身适合依赖面较宽的增强场景。transform-test在process-test-classes阶段处理测试类classpath 取自project.getTestClasspathElements()Mojo声明见 ByteBuddyMojo.java。多个 goal 可以在同一个插件的executions中分别声明例如同时增强主类与测试类executions execution goals goaltransform/goal goaltransform-test/goal /goals /execution /executions3. 官方内置插件CachedReturnPlugin 与 Enhance 注解README 示例中的net.bytebuddy.build.CachedReturnPlugin是随 Byte Buddy 分发的标准构建期插件其完整实现在 CachedReturnPlugin.java。它的作用是把被Enhance注解标记的方法的返回值缓存到一个合成字段synthetic field中从而避免重复计算。使用方式在目标方法上添加注解public class Sample { CachedReturnPlugin.Enhance public String expensive() { // 只会在第一次调用时执行 return computeExpensiveValue(); } }其实现原理从源码 CachedReturnPlugin.java 可以确认匹配所有声明了Enhance的非 bridge 方法生成一个private synthetic字段字段名默认取方法名 _ 随机串也可通过Enhance(fieldName)显式指定通过Advice在该方法上织入“先读字段非默认值则直接返回否则执行原方法体并写回字段”的逻辑。官方文档与源码注释明确给出以下限制务必注意该缓存非线程安全仅当缓存值“冻结”对象只含final字段时可用于并发场景——这样设计是为了避免声明volatile字段。对于基本类型返回值用该类型的默认值如0、false表示“尚未缓存”对于引用类型用null表示“尚未缓存”。因此如果方法本身可能返回默认值或null缓存机制不会生效。不能缓存抽象方法、带参数的方法以及void方法源码中分别抛出IllegalStateException。默认构造器CachedReturnPlugin()在字段名冲突时会抛出异常若希望遇到已存在的字段名时跳过可使用new CachedReturnPlugin(true)并通过arguments传入见第 5 节。该插件实现的是Plugin与Plugin.Factory两个接口close()为空实现无需关闭。4. 编写自定义 Plugin实现 net.bytebuddy.build.Plugin 接口当内置插件不满足需求时自定义插件必须实现 Byte Buddy 的Plugin接口。该接口包含三个方法boolean matches(TypeDescription target)判断是否处理某个类型DynamicType.Builder? apply(DynamicType.Builder? builder, TypeDescription typeDescription, ClassFileLocator classFileLocator)执行字节码增强并返回新的 buildervoid close()在插件使用完毕后释放资源。仓库测试模块中的 SimplePlugin.java 是教科书式的例子——它把名为foo的方法的返回值固定为quxpublic class SimplePlugin implements Plugin { public boolean matches(TypeDescription target) { return target.getName().equals(foo.Bar); } public DynamicType.Builder? apply(DynamicType.Builder? builder, TypeDescription typeDescription, ClassFileLocator classFileLocator) { return builder.method(named(foo)).intercept(FixedValue.value(qux)); } public void close() { /* do nothing */ } }在pom.xml中按第 1 节的transformation结构注册即可。坐标回退规则源码见 CoordinateConfiguration.javatransformation中的groupId、artifactId、version、packaging任一省略时都回退到当前项目自身的对应值。因此如果插件类就在当前项目自身或其依赖树内编译产物中可以只写plugin一项如测试资源 simple.pom.xml 所示如果插件类位于另一个构件例如独立的增强库则需要像 README 示例那样给出完整坐标插件会通过ClassLoaderResolver解析并加载该构件ClassLoaderResolver.java。5. 构造器注入File、Log、BuildLogger 与显式 arguments官方 README 说明插件可以声明一个构造器接收File、BuildLogger或 Gradle 特定的Logger类型参数此时插件会获得 class 文件根目录或合适的日志器。结合源码 ByteBuddyMojo.java插件实例通过Plugin.Factory.UsingReflection创建并按构造器参数类型自动注入以下值参数类型注入内容File被转换的 class 文件根目录或 jar 文件File[]完整的 classpath 元素列表org.apache.maven.plugin.logging.LogMaven 日志器net.bytebuddy.build.BuildLogger包装为MavenBuildLogger的构建日志器除自动注入外还可以在transformation中通过arguments显式传参。参数按索引 字符串值配对配置结构定义在 PluginArgument.java值为index与value字段解析为ArgumentResolver.ForIndex.WithDynamicType。测试资源 argument.pom.xml 展示了向构造器ArgumentPlugin(int value)传参42的写法transformation pluginnet.bytebuddy.test.ArgumentPlugin/plugin arguments argument index0/index value42/value /argument /arguments /transformation对应的插件类 ArgumentPlugin.java 接收该参数并注入到方法返回值中测试 ByteBuddyMojoTest.java 验证了转换后调用foo方法返回的是42而非原始值。需要留意自动注入与显式arguments同时存在时索引参数会与类型注入解析器组合使用因此不要把显式参数放在会被类型注入占用的索引上以避免冲突。6. 插件自动发现META-INF/net.bytebuddy/build.plugins 与 Discovery 策略README 指出如果插件 jar 文件在META-INF/net.bytebuddy/build.plugins文件中声明了插件类名每行一个全限定类名且该 jar 被声明为byte-buddy-maven-plugin的依赖那么插件会被自动发现并应用无需在transformations中显式注册。自动发现由Discovery枚举控制其四个取值与语义定义在 Discovery.javaDiscovery 值行为EMPTY默认仅当没有任何显式注册的 transformation 时才执行发现UNIQUE始终尝试发现但跳过已被显式注册的同名插件ALL始终尝试发现会记录显式配置以便去重NONE从不发现通过discoveryUNIQUE/discovery等配置启用。扫描入口是Plugin.Engine.Default.scan(ClassLoader)在 ByteBuddyMojo.java 中分别对插件自身的类加载器以及当classPathDiscoverytrue/classPathDiscovery时当前项目 classpath 构造的URLClassLoader执行扫描。classPathDiscovery默认false官方文档建议慎用因为它可能误触发 classpath 上偶然出现的插件但在依赖较少、想借用 Maven 依赖版本管理的项目中可作为便利手段。7. 其余配置项一览含默认值除transformations、discovery外ByteBuddyMojo.java 还暴露了以下配置项配置项默认值作用initialization默认REBASE入口点指定EntryPoint见第 8 节suffix空随机后缀重新基线化rebase时追加到原方法名后的固定后缀failOnLiveInitializertrue转换过程产生“存活初始化器”live initializer时是否抛异常skipfalse设为true时跳过当前模块的转换warnOnMissingOutputDirectorytrue输出目录不存在时是否告警warnOnEmptyTypeSettrue未转换任何类型时是否告警failFasttrue某个插件无法应用时是否立即失败false则最后汇总失败extendedParsingfalse是否解析 class 文件调试信息以提取参数名对应PoolStrategy.EXTENDEDthreads0并行转换线程数0表示串行staleMilliseconds0与上次构建时间戳之间允许的“陈旧”容差毫秒数-1禁用陈旧检测multiReleaseVersion未设置解析多版本 jarmulti-release jar时使用的 Java 版本其中staleMilliseconds与每次执行后写入target/maven-status/artifactId/goal/executionId/staleness的时间戳配合ByteBuddyMojo.java用于过滤上次构建之后未修改过的 class 文件避免重复转换。8. 自定义初始化器initialization 与 EntryPoint每次转换都始于一个ByteBuddy实例和对类型的初始处理方式rebase、redefine 等这由EntryPoint决定。默认值为REBASE对类型重新基线化保留原有方法实现。initialization的entryPoint属性可以是EntryPoint.Default中的枚举名常量如REBASE、REDEFINE、DECORATE等或一个自定义EntryPoint实现类的全限定名此时同样支持用 Maven 坐标指定其所在构件缺省回退到当前项目坐标。自定义入口点的解析逻辑在 Initialization.java先匹配EntryPoint.Default常量否则通过反射实例化自定义类。测试中的 SimpleEntryPoint.java 展示了实现EntryPoint并委托给byteBuddy.rebase(...)的写法对应的配置见测试资源 entry.pom.xmlinitialization entryPointnet.bytebuddy.test.SimpleEntryPoint/entryPoint /initialization此外initialization还支持validated布尔属性默认true设为false时入口点被EntryPoint.Unvalidated包装跳过类型校验。suffix配置则对应底层MethodNameTransformer.Suffixing未设置时使用withRandomSuffix()随机后缀设置后使用固定后缀。测试 ByteBuddyMojoTest.java 验证了suffixqux时 rebase 出的原方法名为foo$qux配置样例见 suffix.pom.xml。9. 增量构建incremental 与 Maven BuildContextREADME 指出插件支持 Maven 的BuildContext与增量构建特性目前由 Eclipse IDE 支持需要显式设置incremental为true启用。其实现位于 ByteBuddyMojo.java 的ForLifecycleTypes.apply当incrementaltrue且存在可用的BuildContext时若context.isIncremental()为真则用context.newScanner(sourceDirectory)扫描变更的.java源文件将其转换为类名前缀并通过Plugin.Engine.Source.Filtering只处理这些类含其内部类见FilePrefixMatcher转换完成后对每个被转换的类型调用context.refresh(...)通知 IDE 刷新若构建上下文不可用或无法增量则退化为处理全部 class 文件。增量场景下源目录取project.getBuild().getSourceDirectory()主代码或getTestSourceDirectory()测试代码输出目录对应getOutputDirectory()/getTestOutputDirectory()。10. 进阶 goaltransform-location* 与 transform-dependencies除生命周期绑定的四个 goal 外源码还提供了面向“任意位置”的转换目标定义在ForExplicitLocations与ForDependencyFolder中goal作用transform-location-empty把指定的源目录或 jar 文件转换到目标目录或 jar 文件不自动引入项目 classpathtransform-location同左但额外引入编译期 classpathtransform-location-runtime同左额外引入运行时 classpathtransform-location-extended同左引入除 test/import 外的全部依赖transform-location-test同左引入完整测试 classpathtransform-dependencies转换一个目录下的全部 jar通常用于项目依赖可选target输出目录这类 goal 需要配置source必填与target以及可选的dependencies以坐标方式额外解析依赖并加入 classpath。transform-dependencies的target缺省时原地覆盖source目录中的 jar见 ByteBuddyMojo.java。11. 底层执行流程从 execute 到 Plugin.Engine理解插件的内部流水线有助于排查问题。以transform为例核心调用链如下全部位于 ByteBuddyMojo.javaexecute()L249-L319校验初始化状态与skip标记将transformations包装为Transformer.ForConfiguredPlugin按discovery策略扫描并注册自动发现的插件若最终 transformer 为空则打印警告并跳过resolveClassPathElements()按 goal 的依赖作用域解析 classpath 元素同时结合dependencyManagement中的坐标版本transform()L358-L475加载/创建ClassLoaderResolver与仓库会话RepositorySystemSession通过Plugin.Factory.UsingReflection实例化每个插件并附加类型注入的参数解析器File、Log、BuildLogger、File[]与显式参数解析EntryPoint探测 Java 版本优先读取maven.compiler.release其次maven.compiler.target再查maven-compiler-plugin的release/target配置都找不到时回退到当前 JVM 版本并给出“构建受 JDK 影响”的警告构造ClassFileLocator平台类加载器 每个 classpath 元素的ForJarFile/ForFolder支持multiReleaseVersion以Plugin.Engine.Default.of(entryPoint, classFileVersion, methodNameTransformer)构建引擎按extendedParsing选择PoolStrategy.EXTENDED或FAST按failOnLiveInitializer/failFast配置错误处理按threads选择串行或并行调度器apply(source, target, factories)执行转换并返回Summary依据Summary处理结果有失败类型则抛MojoExecutionException未转换任何类型且warnOnEmptyTypeSettrue时告警最后写入 staleness 文件。这些步骤在 ByteBuddyMojoTest.java 中有完整的端到端验证testSimpleTransformation、testSimpleTransformationWithArgument、testLiveInitializer/testLiveInitializerAllowed、testIllegalTransformer等分别覆盖了正常转换、显式参数、live initializer 失败与放行、非法插件等场景可作为理解各配置项行为的权威参考。12. 常见问题与排查建议1. 构建日志出现 “No transformations are specified or discovered. Skipping plugin application.”说明transformations为空且未发现任何插件。检查transformations配置是否存在、plugin类名是否拼写正确、坐标能否被 Maven 解析。2. 转换产生 live initializer 导致构建失败构建期转换的对象是尚未加载的 class 文件若插件要求“存活初始化器”如把类型静态字段设置为用户拦截器则无法在构建期完成。若确需放行可设置failOnLiveInitializerfalse/failOnLiveInitializer对应测试资源 live.allowed.pom.xml但需自行承担运行时行为风险——测试testLiveInitializerAllowed即展示了放行后运行期可能抛出NullPointerException的情况。3. 报 “Cannot resolve plugin: ...”MojoExecutionException插件坐标不可达或类无法加载。确认构件坐标存在、版本可解析若插件类位于当前项目自身应省略坐标只保留plugin。4. 报 “Cannot cache the value of ...”使用CachedReturnPlugin时违反了其约束方法带参数、返回void或为抽象方法。请参见第 3 节的限制清单。5. 增量构建未生效确认已设置incrementaltrue/incremental且构建运行于支持BuildContext的环境如 Eclipse IDE 的增量编译否则插件会退化为全量处理并打印 debug 日志 “Cannot build incrementally - all class files are processed”。13. 小结Byte Buddy Maven 插件把字节码增强从运行期前置到构建期通过transform系列 goal 覆盖主类、测试类与依赖转换通过CachedReturnPlugin提供开箱即用的返回值缓存并借助Plugin接口、构造器注入、自动发现与增量构建机制为 Maven 项目提供了一条完整、可扩展的构建期字节码处理链路。如需深入研读实现细节建议依次阅读 ByteBuddyMojo.java、Discovery.java、Initialization.java并结合 CachedReturnPlugin.java 与 ByteBuddyMojoTest.java 中的用例验证行为。赞分享开发工具后端【免费下载链接】byte-buddyRuntime code generation for the Java virtual machine.项目地址https://gitcode.com/gh_mirrors/by/byte-buddy点击查看免费下载相关推荐Byte Buddy构建插件终极指南Maven与Gradle集成完全教程Byte Buddy构建插件终极指南Maven与Gradle集成完全教程 Byte Buddy是Java虚拟机的运行时代码生成工具它提供了强大的字节码增强能开发工具后端Java字节码增强终极指南使用Byte Buddy重构遗留代码的完整流程Java字节码增强终极指南使用Byte Buddy重构遗留代码的完整流程 在Java开发中我们经常会遇到需要修改或增强现有类功能的情况特别是在处理遗留代码开发工具后端Java字节码增强终极指南Byte Buddy如何实现从Java 5到Java 25的完美兼容Java字节码增强终极指南Byte Buddy如何实现从Java 5到Java 25的完美兼容 在当今快速迭代的Java生态系统中多版本兼容性已成为开发工具开发工具后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
