Java SE 26 Class-File API 怎样改写方法字节码

Java SE 26 的 Class-File API 适合处理“读入一个既有 class 文件，只改一小段方法字节码，再输出新文件”这类任务。我的经验是先把问题拆成三层：ClassModel 负责读，CodeTransform 负责定位和替换指令，ClassFile 负责把转换结果写回 class 文件。这样不用手动重建字段、方法和属性，也不容易把未改动的结构漏掉。

官方地址：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/lang/classfile/package-summary.html

如果目标是改写方法体中的某一类调用，优先写一个最小的 CodeTransform，再用 MethodTransform.transformingCode 和 ClassTransform.transformingMethods 把它提升到类级别；不需要改动的元素统一交给 builder.with(element) 原样传递。

先把四个对象的职责分清

ClassFile.of().parse(bytes) 得到的是惰性解析的 ClassModel，它可以访问类、字段、方法和属性。真正改写时，转换器接收“一个 builder 加一个 element”，可以选择丢弃、原样写回，或者写入替代元素。这个模型比直接操作字节偏移更适合做局部改写。

CodeTransform 处理方法体内的指令；MethodTransform 处理方法级元素；ClassTransform 处理类级元素。三者不是三套独立流程，而是从内向外提升的适配层。下图把正文中的对象和边界画在一起，便于先建立心智模型。

用 CodeTransform 替换方法体中的调用

下面的示例把方法体内对 Foo 的静态调用改写为同名、同描述符的 Bar 调用。关键点不是遍历每一种指令，而是命中目标指令时不调用 with，改为写入新指令；其他指令则原样传递。

import java.lang.classfile.ClassFile;
import java.lang.classfile.ClassTransform;
import java.lang.classfile.MethodTransform;
import java.lang.classfile.CodeTransform;
import java.lang.classfile.instruction.InvokeInstruction;
import java.lang.classfile.instruction.Opcode;
import java.nio.file.Files;
import java.nio.file.Path;

static byte[] rewriteCalls(Path input) throws Exception {
    byte[] original = Files.readAllBytes(input);
    var classFile = ClassFile.of();

    CodeTransform replaceFoo = (builder, element) -> {
        if (element instanceof InvokeInstruction invoke
                && invoke.owner().name().equalsString("Foo")
                && invoke.opcode() == Opcode.INVOKESTATIC) {
            // 命中目标调用时写入 Bar；不调用 with，旧指令就不会被保留。
            builder.invokestatic(
                    java.lang.constant.ClassDesc.of("Bar"),
                    invoke.name().stringValue(),
                    invoke.typeSymbol(),
                    invoke.isInterface());
        } else {
            // 其余指令沿原结构传递，避免无关字节码被丢弃。
            builder.with(element);
        }
    };

    var classTransform = ClassTransform.transformingMethods(
            MethodTransform.transformingCode(replaceFoo));
    // 先解析，再提升 CodeTransform，最后生成新的 class 文件字节。
    return classFile.transformClass(classFile.parse(original), classTransform);
}

实际项目中应把目标类名、方法名和描述符作为配置或明确常量，而不是只按类名匹配。替换调用还必须保持返回类型、参数类型和静态/实例调用语义一致，否则生成阶段可能抛出 IllegalArgumentException，或者把问题留到后续类加载阶段。

为什么要用提升后的转换器

直接手写 ClassBuilder、MethodBuilder 和 CodeBuilder 当然可以，但需要自己把字段、属性、方法元数据以及未改动指令逐层转发。提升转换器的好处是把“改哪里”集中在一处：transformingCode 只进入方法体，transformingMethods 再把它接回类级结构。

官方 API 把转换看成对元素序列的 flatMap：一个元素可以原样保留、被删除，也可以替换成一个或多个元素。对于只改少量调用的场景，原始常量池还可以参与共享，未改动部分不必全部重新解析和生成。

四个容易踩坑的边界

• 运行时版本：Java SE 26 的 class 文件主版本是 70。运行时不支持输入文件版本时，解析会失败；发布工具前应明确要求 JDK 26，并避免把示例误当作旧 JDK 的兼容代码。
• 惰性解析：模型不是一次性把所有结构都解析完。访问器可能在更深层结构被访问时才发现格式问题，因此异常处理要覆盖遍历和生成的完整范围。
• 未知元素：如果转换器要消费所有元素，遇到更高版本或未知 class 元素时应选择显式拒绝，或者保留元素而不做错误假设。未来 JDK 新增结构后，宽松的默认分支可能隐藏兼容风险。
• 一致性检查：builder 会检查可表示性，但不会替你完成全部 class 文件一致性验证。标签、控制流、描述符和常量池引用仍需由转换逻辑负责，生成失败不要简单归咎于 API。

落地时怎样选择改写方式

只替换某个调用时使用 CodeTransform；需要增删方法级元素时提升到 MethodTransform；需要修改类级元数据时再写 ClassTransform。每次只把一个稳定的技术目标交给转换器，并保留输入 class 文件和输出 class 文件的版本、目标类、方法描述符及异常日志，后续定位会比记录一串字节偏移更可靠。

简要判断可以记成三句话：读结构用 ClassModel，改指令用 CodeTransform，写结果交给 ClassFile。如果改写范围已经跨到完整的编译器优化或复杂控制流重构，就应重新评估是否需要更高层的字节码工具，而不是继续堆叠一个转换器。

常见问题

Class-File API 能不能只读取方法名而不改写？可以。解析成 ClassModel 后遍历 methods() 即可，访问方法体时才进一步触发代码结构解析。

为什么替换指令后生成阶段报错？优先检查目标调用的描述符、静态/实例属性、类文件版本和新指令涉及的常量池项，再检查是否遗漏了控制流元素或标签。