Android编译时动态插入代码原理与实践

本文同步发布于公众号：移动开发那些事:Android编译时动态插入代码原理与实践

Android开发中，编译时动态插入代码是一种高效，并且对业务逻辑是低侵入性的方案，常用于增加通用的埋点能力，或者插入关键日志，本文以编译时动态插入日志为例来说明如何在Android实现编译时动态插入代码。

1 常见的编译时插入代码方案

• APT
• Transform + ASM
• AspectJ(AOP)

1.1 APT(Annotation Processing Tool)

通过自定义注解标记目标方法/类，然后利用APT在编译期解析注解并生成包含代码逻辑的代码,其核心原理为：

• 注解标记与解析：
  • 开发者通过自定义注解（如 @DebugLog）标记需要插入日志的方法或类；
  • 编译时，APT 的注解处理器（如继承 AbstractProcessor 的类）会扫描所有被标记的代码元素（如方法、字段)；
• 代码生成与织入
  • 生成辅助类：注解处理器使用代码生成工具（如 JavaPoet）创建新的 Java 类，这些类包含日志逻辑;
  • 逻辑注入：生成的代码会通过静态方法调用或代理模式，在目标方法的前后插入日志语句

优点：

• 代码解耦;
• 灵活性强：支持复杂的逻辑，如参数获取，耗时统计

更适用于需要生成新类的场景，如ButterKnife,Dagger2,Arouter ，

1.2 Transform + ASM

基于Gradle Transform ,在编译流程的.class -> dex的阶段，通过ASM或javassit直接修改字节码，插入日志指令；其实现的核心原理为

• 编译流程拦截：通过Transform API 拦截编译流程
  • 每个Transform是独立的Task,多个Task按注册顺序形成链式的处理
  • 通过getScopes 控制处理范围
  • 通过getInputTypes 指定数据类型，如只处理类文件；
• ASM字节码操作
  • ClassReader：读取 .class 文件并触发访问事件;
  • ClassWriter：生成修改后的字节码。
  • ClassVisitor/MethodVisitor：在访问类或方法时插入自定义逻辑

优点：

• 兼容性强，支持第三方库和系统类修改；
• 灵活性高，要可针对特定包，类或方法进行过滤；

适用于需要修改现有代码逻辑（如插入埋点），典型应用场景为：

• 实现全局埋点
• 性能监控
• 权限校验

1.3 AspectJ(AOP)

通过切点Pointcut定义目标方法，在编译期加入（Weaving）日志逻辑，其核心原理为：

• 编译时织入：在 Java 源码编译为字节码阶段，解析开发者定义的切面（Aspect）和切点（Pointcut），将通知（Advice）代码直接插入目标方法的前后或内部。这种织入方式无需运行时反射，性能损耗低；
• 切点表达式： 切点表达式决定了哪些方法会被注入代码，通过语法（如 execution(* android.app.Activity.onCreate(..))）定义需要拦截的连接点（Join Point）
• 通知类型（Advice Types）
  • @Before: 在目标方法执行前插入日志（如记录方法调用时间）
  • @After : 在方法正常返回或抛出异常后插入日志
  • @Around : 完全控制方法执行，可自定义前后逻辑

优点与适用场景

• 无侵入性：无需修改业务代码，通过声明式切面实现日志逻辑与业务解耦，适用于埋点、性能监控等场景；
• 灵活性与高覆盖率：支持通过复杂表达式匹配任意方法（包括第三方库）
• 性能高效：编译期静态织入避免运行时反射或动态代理开销
  适用于简单的应用场景，如方法级的日志插入，如果有更复杂的场景，需要使用Transform + ASM来实现更细粒度的控制

2 实战

2.1 APT(Annotation Processing Tool)

使用APT的步骤：

• 定义注解，用于标记需要插入日志的方法，如DebugLog
• 自定义注解处理器：继承于AbstractProcessor,并使用JavaPoet生成新类或增加现有类；
• 注入代码，在生成类中播入日志调用，例如在方法前后添加Log.e语句

2.1.1 定义注解

package com.example.annotation;  import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target;  // 模块名：annotation @Retention(RetentionPolicy.CLASS)  // 保留到编译期 @Target(ElementType.METHOD)        // 标记在方法上 public @interface DebugLog { } 

2.1.2 自定义注解处理器

有使用到两个依赖库,需要在项目的build.gradle文件中添加这两个依赖

 implementation 'com.google.auto.service:auto-service:1.0.1'  implementation 'com.squareup:javapoet:1.13.0' } 

注解处理器

// 模块名：compiler @AutoService(Processor.class)  // 自动注册处理器 public class DebugLogProcessor extends AbstractProcessor {     private Filer filer;       // 文件生成器     private Messager messager; // 日志输出工具      @Override     public synchronized void init(ProcessingEnvironment env) {         super.init(env);         filer = env.getFiler();         messager = env.getMessager();     }      @Override     public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment env) {         // 遍历所有被 @DebugLog 标记的方法         for (Element element : env.getElementsAnnotatedWith(DebugLog.class)) {             if (element.getKind() != ElementKind.METHOD) {                 continue;             }             ExecutableElement method = (ExecutableElement) element;             // 获取方法所在类信息             TypeElement classElement = (TypeElement) method.getEnclosingElement();             String className = classElement.getSimpleName().toString();             String packageName = elements.getPackageOf(classElement).toString();              // 生成代码             generateLogCode(className, packageName, method);         }         return true;     }      private void generateLogCode(String className, String packageName, ExecutableElement method) {         // 生成类名：原类名 + "$$Logger"         String generatedClassName = className + "$$Logger";                  // 使用 JavaPoet 构建代码（生成新类）         MethodSpec logMethod = MethodSpec.methodBuilder(method.getSimpleName().toString())                 .addModifiers(Modifier.PUBLIC, Modifier.STATIC)                 .returns(void.class)                 .addStatement("$T.d("APT", "Method called: $L")",                      ClassName.get("android.util", "Log"), method.getSimpleName())                 .build();          TypeSpec loggerClass = TypeSpec.classBuilder(generatedClassName)                 .addModifiers(Modifier.PUBLIC, Modifier.FINAL)                 .addMethod(logMethod)                 .build();          // 写入文件         try {             JavaFile.builder(packageName, loggerClass)                     .build()                     .writeTo(filer);         } catch (IOException e) {             messager.printMessage(Diagnostic.Kind.ERROR, "代码生成失败: " + e);         }     } }   

2.1.3 使用

在某个需要插入日志的方法中使用DebugLog的注解标记

public final class MainActivity { @DebugLog public void loadData(){ 	// 其他业务逻辑 }}  // 编译后，会在build/generated/source/apt 目录下，看到对应的代码 public final class MainActivity$$Logger {     public static void loadData() {         Log.d("APT", "Method called: loadData");     } } 

2.2 Transform + ASM

使用Transform的步骤：

• 添加依赖；
• 注册Transform: 创建gradle插件，注册自定义的Transform实现
• 使用ASM;通过ClassVisitor和MethodVisitor在目标方法中插入日志调用；
• 优化：可通过isIncremental 方法减少重复处理(是否启动增量编译)；

2.2.1 添加依赖

这里需要新建一个Gradle插件项目，在项目的build.gradle文件里添加必要的依赖

plugins {     id 'groovy'     id 'maven-publish' }  group 'com.example' version '1.0.0'  repositories {     google()     mavenCentral()     // 如果要发布到自定义的仓库，需要增加自定义仓库地址 }  dependencies { 	// 与gradle构建系统交互     implementation gradleApi()     // 本地的groovy库     implementation localGroovy()     implementation 'org.ow2.asm:asm:9.3'     implementation 'com.android.tools.build:gradle:7.4.2' }  publishing {     // 这里涉及到如何将插件发布于maven仓库的逻辑，可参考公众号的另一篇文章     // 这里只是发布的本地的配置介绍    <!--  publications {         // 定义 Maven 发布的配置         maven(MavenPublication) {             // 发布的组 ID             groupId 'com.example'             // 发布的工件 ID             artifactId 'log-insert-plugin'             // 发布的版本号             version '1.0.0'              // 从 Java 组件获取要发布的内容             from components.java         }     }     repositories {         // 配置本地 Maven 仓库的路径，用于发布插件         maven {             url "$buildDir/repo"         }     } --> }  

关于如何将插件发布于maven仓库的介绍，可参考前面的文章如何高效发布Android AAR包到远程Maven仓库

2.2.2 创建插件

首先在工程在工程src/main/groovy目录下创建一个LogInsertPlugin.groovy

package com.example  import org.gradle.api.Plugin import org.gradle.api.Project  class LogInsertPlugin implements Plugin<Project> {     @Override     void apply(Project project) {         def android = project.extensions.getByName('android')         // 注册自定义的Transform类（后面会说明这个类的实现）         android.registerTransform(new LogInsertTransform())     } } 

在工程src/main/groovy目录下创建一个LogInsertTransform.groovy

package com.example  import com.android.build.api.transform.* import com.android.build.gradle.internal.pipeline.TransformManager import org.apache.commons.io.FileUtils import org.objectweb.asm.*  import java.util.jar.JarEntry import java.util.jar.JarFile import java.util.jar.JarOutputStream import java.util.zip.ZipEntry  class LogInsertTransform extends Transform {      @Override     String getName() {     	// 标识这个transform         return "LogInsertTransform"     }      @Override     Set<QualifiedContent.ContentType> getInputTypes() {     	// 指定Transform处理的输入类型，这里是类文件         return TransformManager.CONTENT_CLASS     }      @Override     Set<? super QualifiedContent.Scope> getScopes() {     	// 指定Transform处理的范围，这里是整个项目         return TransformManager.SCOPE_FULL_PROJECT     }      @Override     boolean isIncremental() {     	// 是否支持增量编译         return true     }      // 处理输入文件并进行转换     @Override     void transform(TransformInvocation transformInvocation) throws TransformException, InterruptedException, IOException {         // 遍历 所有的输入文件         transformInvocation.inputs.each { TransformInput input ->             // 目录             input.directoryInputs.each { DirectoryInput directoryInput ->                 // 拿到输出的目录                 def dest = transformInvocation.outputProvider.getContentLocation(                         directoryInput.name,                         directoryInput.contentTypes,                         directoryInput.scopes,                         Format.DIRECTORY                 )                 FileUtils.copyDirectory(directoryInput.file, dest)                 // 处理输出目录中的类文件                 processDirectory(dest)             }             // 处理jar             input.jarInputs.each { JarInput jarInput ->                 def jarName = jarInput.name                 if (jarName.endsWith(".jar")) {                     jarName = jarName.substring(0, jarName.length() - 4)                 }                 def dest = transformInvocation.outputProvider.getContentLocation(                         jarName,                         jarInput.contentTypes,                         jarInput.scopes,                         Format.JAR                 )                 processJar(jarInput.file, dest)             }         }     }      private void processDirectory(File directory) {         if (directory.isDirectory()) {             directory.eachFileRecurse { File file ->                 if (file.name.endsWith('.class')) {                 	// 处理类文件                     processClassFile(file)                 }             }         }     }      // 处理jar 文件     private void processJar(File inputJar, File outputJar) {         def jarFile = new JarFile(inputJar)         def enumeration = jarFile.entries()         def tempFile = File.createTempFile("temp", ".jar")         def jarOutputStream = new JarOutputStream(new FileOutputStream(tempFile))         while (enumeration.hasMoreElements()) {             def jarEntry = enumeration.nextElement()             def inputStream = jarFile.getInputStream(jarEntry)             def zipEntry = new ZipEntry(jarEntry.name)             jarOutputStream.putNextEntry(zipEntry)             // 处理类文件             if (jarEntry.name.endsWith('.class')) {                 def classBytes = processClass(inputStream)                 // 写到输出流                 jarOutputStream.write(classBytes)             } else {                 jarOutputStream.write(inputStream.bytes)             }             jarOutputStream.closeEntry()         }         jarOutputStream.close()         jarFile.close()         FileUtils.copyFile(tempFile, outputJar)         tempFile.delete()     }      // 处理类文件的输入流     private byte[] processClass(InputStream inputStream) {     	// 类读取器         def classReader = new ClassReader(inputStream)         // 类写入器         def classWriter = new ClassWriter(classReader, ClassWriter.COMPUTE_MAXS)         // 创建自定义的类访问器         def logClassVisitor = new LogClassVisitor(Opcodes.ASM9, classWriter)         // 让类读取器接受访问器的处理         classReader.accept(logClassVisitor, ClassReader.EXPAND_FRAMES)         // 返回处理后的字节码         return classWriter.toByteArray()     }      // 处理类文件     private void processClassFile(File classFile) {         def fis = new FileInputStream(classFile)         def classBytes = processClass(fis)         fis.close()         def fos = new FileOutputStream(classFile)         fos.write(classBytes)         fos.close()     } }  // 自定义类访问器，用于访问类的各个部分 class LogClassVisitor extends ClassVisitor {      LogClassVisitor(int api, ClassVisitor classVisitor) {         super(api, classVisitor)     }      // 访问方法时调用     @Override     MethodVisitor visitMethod(int access, String name, String descriptor, String signature, String[] exceptions) {         def methodVisitor = super.visitMethod(access, name, descriptor, signature, exceptions)         // 创建自定义的方法访问器         return new LogMethodVisitor(Opcodes.ASM9, methodVisitor, name)     } } // 自定义方法访问器，有两种方式： // 1 是继承于MethodVisitor // 2 继承于AdviceAdapter(更简单)  // 方法1 ：自定义方法访问器，用于访问方法的各个部分 class LogMethodVisitor extends MethodVisitor {      private String methodName      LogMethodVisitor(int api, MethodVisitor methodVisitor, String methodName) {         super(api, methodVisitor)         this.methodName = methodName     }      // 访问方法代码开始时调用，     @Override     void visitCode() {         super.visitCode()         // 将日志标签压入栈（TAG）         mv.visitLdcInsn("LogInsertPlugin")         // 将日志信息压入栈 (Info)         mv.visitLdcInsn("Entering method: $methodName")         // 调用Log.d 方法         mv.visitMethodInsn(Opcodes.INVOKESTATIC, "android/util/Log", "d", "(Ljava/lang/String;Ljava/lang/String;)I", false)         // 弹出栈项元素         mv.visitInsn(Opcodes.POP)     }      // 访问指令时调用     @Override     void visitInsn(int opcode) {         // 判断是否是返回指令或异常指令         if ((opcode >= Opcodes.IRETURN && opcode <= Opcodes.RETURN) || opcode == Opcodes.ATHROW) {             mv.visitLdcInsn("LogInsertPlugin")             mv.visitLdcInsn("Exiting method: $methodName")             mv.visitMethodInsn(Opcodes.INVOKESTATIC, "android/util/Log", "d", "(Ljava/lang/String;Ljava/lang/String;)I", false)             mv.visitInsn(Opcodes.POP)         }         super.visitInsn(opcode)     } }  // 方法2 ：继承自AdviceAdapter，更简洁 public class LogMethodVisitor extends AdviceAdapter {     private String methodName;      protected LogMethodVisitor(int api, MethodVisitor mv, int access, String name, String desc) {         super(api, mv, access, name, desc);         this.methodName = name;     }      @Override     protected void onMethodEnter() {         // 在方法入口插入日志：Log.d("LogInsertPlugin", "Enter method: " + methodName)         visitLdcInsn("LogInsertPlugin");         visitLdcInsn("Enter method: " + methodName);         visitMethodInsn(INVOKESTATIC, "android/util/Log", "d", "(Ljava/lang/String;Ljava/lang/String;)I", false);         visitInsn(POP); // 丢弃返回值（Log.d返回int）         super.onMethodEnter();     }      @Override     protected void onMethodExit(int opcode) {         // 在方法出口插入日志：Log.d("LogInsertPlugin", "Exit method: " + methodName)         visitLdcInsn("LogInsertPlugin");         visitLdcInsn("Exit method: " + methodName);         visitMethodInsn(INVOKESTATIC, "android/util/Log", "d", "(Ljava/lang/String;Ljava/lang/String;)I", false);         visitInsn(POP);         super.onMethodExit(opcode);     } 

然后就可以把这个插件发布到远程仓库了

2.2.3 使用插件

在需要使用的工程的build.gradle目录下，添加对应的依赖

buildscript {     repositories {         maven {             //前面插件的发布地址         }     }     dependencies {     	//          classpath 'com.example:log-insert-plugin:1.0.0'     } }  // 应用前面做好的插件 apply plugin: 'com.example.LogInsertPlugin' 

2.3 AspectJ(AOP)

使用Transform的步骤：

• 添加依赖
• 定义切面：使用Aspect注解标记切面类，通过Pointcut 指定目标方法
• 织入逻辑：在Before或Around 通知中插入日志代码
• 集成：通过AspectJ插件实现编译期织入；

2.3.1 添加依赖

在工程的build.gradle添加AspectJ插件和依赖

buildscript {     dependencies {         classpath 'org.aspectj:aspectjtools:1.9.7'     } } // 插件 apply plugin: 'aspectj'  dependencies {     implementation 'org.aspectj:aspectjrt:1.9.7'     aspectpath 'org.aspectj:aspectjweaver:1.9.7' } 

2.3.2 定义切面

创建一个Aspect类，用于拦截方法调用并插入日志

import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.annotation.Before; import org.aspectj.lang.annotation.Pointcut; import org.aspectj.lang.JoinPoint;  @Aspect public class LogAspect { 	private static final String TAG = "LogAspect"; 	// ("execution(* com.demo..*(..))" ,匹配在com.demo包下的所有类的所有方法     // 定义一个切入点，这里表示匹配所有方法     @Pointcut("execution(* *.*(..))")     public void logMethods() {}     // 在方法执行前插入日志     @Before("logMethods()")     public void beforeMethod(JoinPoint joinPoint) {         String methodName = joinPoint.getSignature().getName();         Log.d(TAG, "Before method: " + methodName);     }      // 在方法执行后插入日志     @After("logMethods()")     public void afterMethod(JoinPoint joinPoint) {         String methodName = joinPoint.getSignature().getName();         Log.d(TAG, "After method: " + methodName);     } } 

3 参考

• Android里面的编译器注解APT的使用及其原理
• Transform+ASM牛刀小试
• 看AspectJ在Android中的强势插入