JDK 24 Class File API 介绍

原创已于 2025-03-29 16:59:39 修改 · 1.4k 阅读

21 ·

CC 4.0 BY-SA版权

文章标签：

#java #开发语言

于 2025-03-29 16:53:42 首次发布

Java 专栏收录该内容

60 篇文章

订阅专栏

概述

JDK 24 引入的 Class File API 提供了一套类型安全的 API 用于操作 Java 类文件。这套 API 允许我们以编程方式读取、修改和创建 Java 类文件，而不需要直接处理底层的字节码。

注1：JDK 24 已于2025年3月18日正式发布，Release信息参见官方介绍。

注2：Class File API的前世今生，参见小子前作《JDK 24正式支持Class-File API》

三方库回顾

在 JDK 24 的 Class File API 之前，社区已经存在一些成熟且广泛使用的库来操作 Java 类文件。以下是一些流行的库列表：

ASM: 一个非常流行且高性能的底层 Java 字节码操作和分析框架。它被许多其他库（如 cglib、Byte Buddy）和框架（如 Spring、Hibernate）广泛使用。
Byte Buddy: 一个现代化的、类型安全的库，用于在运行时创建和修改 Java 类，无需了解字节码。它以其易于使用的流式 API 而闻名，并被 Mockito 等项目使用。
Javassist (Java Programming Assistant): 提供两种级别的 API：源代码级别和字节码级别。源代码级别的 API 允许开发者像编辑 Java 源代码一样编辑类文件，而无需关心字节码细节。
cglib (Code Generation Library): 主要用于通过生成字节码在运行时扩展 Java 类和实现接口。它是许多 AOP 和代理框架的基础，通常基于 ASM 构建。
BCEL (Apache Commons Byte Code Engineering Library): Apache Commons 项目的一部分，旨在提供一种简单的方式来分析、创建和操作（二进制）Java 类文件。虽然相对较老，但在某些项目中仍有使用。

这些库各有优缺点，适用于不同的场景和复杂度需求。JDK 24 的 Class File API 提供了一个标准化的、内置于 JDK 的替代方案。下面介绍一下相关核心类及使用方法。

JDK API核心类关系图

先看一下API框架的核心类间的关系图。

ClassModel 是类文件的主要模型，代表一个完整的类文件结构。它是一个不可变的类文件描述，提供了访问类元数据(如类名、访问标志等)和子结构(如字段、方法、属性等)的方法。ClassModel 是延迟加载的，大多数类文件部分在实际需要之前不会被解析。由于延迟加载的特性，这些模型可能不是线程安全的。此外，由于解析是延迟进行的，访问器方法的调用可能会因为类文件格式错误而抛出 IllegalArgumentException。

ClassModel 可以被视为一个树形结构，其中包含字段、方法和属性等子结构。每个子结构(如 MethodModel)又可以有它自己的子结构(如属性、CodeModel 等)。除了通过显式导航方法(如 ClassModel.methods())访问特定部分外，ClassModel 还提供了一个类元素流视图，允许我们以线性方式遍历所有类元素。

public interface ClassModel {
    // 获取类名
    ClassDesc thisClass();
    
    // 获取父类
    Optional<ClassDesc> superclass();
    
    // 获取实现的接口列表
    List<ClassDesc> interfaces();
    
    // 获取类的访问标志
    AccessFlags flags();
    
    // 获取类的字段列表
    List<FieldModel> fields();
    
    // 获取类的方法列表
    List<MethodModel> methods();
    
    // 获取类的属性列表
    List<Attribute<?>> attributes();
    
    // 获取常量池
    ConstantPool constantPool();
    
    // 获取类元素流
    Stream<ClassElement> elementStream();
}

2. FieldModel

FieldModel 代表类中的一个字段。它是一个不可变的字段描述，提供了访问字段元数据(如字段名、类型、访问标志等)和属性列表的方法。FieldModel 是延迟加载的，字段的详细信息在实际需要之前不会被解析。

public interface FieldModel {
    // 获取字段名
    Utf8Entry fieldName();
    
    // 获取字段类型
    Utf8Entry fieldType();
    
    // 获取字段的访问标志
    AccessFlags flags();
    
    // 获取字段的属性列表
    List<Attribute<?>> attributes();
    
    // 获取字段元素流
    Stream<FieldElement> elementStream();
}

3. MethodModel

MethodModel 代表类中的一个方法。它是一个不可变的方法描述，提供了访问方法元数据(如方法名、描述符、访问标志等)和属性列表的方法。MethodModel 是延迟加载的，方法的详细信息(包括方法体)在实际需要之前不会被解析。

public interface MethodModel {
    // 获取方法名
    Utf8Entry methodName();
    
    // 获取方法描述符
    Utf8Entry methodType();
    
    // 获取方法的访问标志
    AccessFlags flags();
    
    // 获取方法的属性列表
    List<Attribute<?>> attributes();
    
    // 获取方法元素流
    Stream<MethodElement> elementStream();
}

4. ClassFile

ClassFile 是一个提供解析、转换和生成类文件能力的接口。它作为一个上下文，包含一组选项，这些选项会影响解析和生成的方式。主要通过 ClassFile.of() 静态方法获取实例。

public interface ClassFile {
    // 解析类文件字节数组
    ClassModel parse(byte[] bytes);
    
    // 创建新的类文件
    byte[] build(ClassDesc thisClass, Consumer<? super ClassBuilder> handler);
    
    // 创建新的类文件并写入到文件系统
    void buildTo(Path path, ClassDesc thisClass, Consumer<? super ClassBuilder> handler) 
        throws IOException;
    
    // 获取 ClassFile 实例
    static ClassFile of(Option... options) {
        // ...
    }
}

5. ClassBuilder

ClassBuilder 是一个用于构建类文件的接口。它提供了设置类版本、访问标志、父类、接口、字段和方法的能力。主要通过 ClassFile.build() 方法获取实例。

public interface ClassBuilder {
    // 设置类版本
    ClassBuilder withVersion(int major, int minor);
    
    // 设置类访问标志
    ClassBuilder withFlags(AccessFlag... flags);
    
    // 设置父类
    ClassBuilder withSuperclass(ClassDesc desc);
    
    // 设置接口列表
    ClassBuilder withInterfaces(ClassDesc... interfaces);
    
    // 添加字段
    ClassBuilder withField(String name, ClassDesc descriptor,
                         Consumer<? super FieldBuilder> handler);
    
    // 添加方法
    ClassBuilder withMethod(String name, MethodTypeDesc descriptor, int methodFlags,
                          Consumer<? super MethodBuilder> handler);
}

6. FieldBuilder

FieldBuilder 是一个用于构建字段的接口。主要通过 ClassBuilder.withField() 方法获取实例。如果不需要配置属性，可以使用 withFlags 重载方法来跳过处理器。

public interface FieldBuilder {
    // 设置字段访问标志(通过位掩码)
    FieldBuilder withFlags(int flags);
    
    // 设置字段访问标志(通过AccessFlag枚举)
    FieldBuilder withFlags(AccessFlag... flags);
}

7. MethodBuilder

MethodBuilder 是一个用于构建或修改方法的接口。它允许开发者设置方法的访问标志和添加字节码指令。主要通过 ClassBuilder.withMethod() 获取实例。

public interface MethodBuilder {
    // 设置方法访问标志
    MethodBuilder withFlags(AccessFlag... flags);
    
    // 添加方法体的字节码指令
    MethodBuilder withCode(Consumer<CodeBuilder> code);
}

8. CodeBuilder

CodeBuilder 是一个用于构建方法体的接口。它提供了大量的工厂方法来生成字节码指令。主要通过 MethodBuilder.withCode() 获取实例。

CodeBuilder 提供了丰富的字节码指令生成方法，包括：

标签和局部变量管理：创建标签、管理局部变量槽位等
控制流指令：如分支、条件判断、循环等
局部变量操作：如加载和存储局部变量
字段访问：如获取和设置字段值
方法调用：如调用各种类型的方法
数组操作：如数组元素的加载和存储
类型转换：如基本类型之间的转换
常量加载：如加载各种类型的常量
异常处理：如 try-catch 结构
调试信息：如行号和局部变量表

这些方法使得生成字节码变得更加简单和直观，不需要直接处理底层的字节码指令。每个方法都返回 CodeBuilder 实例，支持链式调用，使得代码更加简洁易读。

public interface CodeBuilder {
    // 标签和局部变量相关
    Label newLabel();                    // 创建新标签
    int allocateLocal(TypeKind type);    // 分配局部变量槽位
    
    // 控制流相关
    CodeBuilder branch(Opcode opcode, Label target);  // 分支指令
    CodeBuilder ifThen(Consumer<CodeBuilder> then);   // if-then 结构
    
    // 局部变量操作
    CodeBuilder loadLocal(TypeKind type, int slot);   // 加载局部变量
    CodeBuilder storeLocal(TypeKind type, int slot);  // 存储局部变量
    
    // 字段访问
    CodeBuilder fieldAccess(Opcode opcode, ClassDesc owner, String name, ClassDesc type);
    
    // 方法调用
    CodeBuilder invoke(Opcode opcode, ClassDesc owner, String name, MethodTypeDesc type, boolean isInterface);
    
    // 常量加载
    CodeBuilder loadConstant(ConstantDesc value);  // 加载常量
    
    // 异常处理
    CodeBuilder exceptionCatch(Label start, Label end, Label handler, ClassEntry catchType);  // 异常捕获
    
    // 调试信息
    CodeBuilder lineNumber(int line);  // 行号
    
    // 常用指令的便捷方法
    CodeBuilder getstatic(ClassDesc owner, String name, ClassDesc type);  // 获取静态字段
    CodeBuilder ldc(String value);  // 加载字符串常量
    CodeBuilder invokevirtual(ClassDesc owner, String name, MethodTypeDesc descriptor);  // 调用虚拟方法
    CodeBuilder return_();  // 返回
}

9. ConstantPool

ConstantPool 代表类文件的常量池。它提供了一个延迟加载的、只读的常量池视图。类文件中的许多重要内容都存储在常量池中，如类名、方法名、字段名、字符串字面量等。常量池项通常以各种 PoolEntry 子类型的形式暴露，如 ClassEntry 或 Utf8Entry。

常量池项也可以通过模型和元素暴露。例如，在遍历类文件时，InvokeInstruction 元素暴露的 owner() 方法对应常量池中的 Constant_Class_info 条目。

public interface ConstantPool {
    // 获取常量池大小
    int size();
    
    // 通过索引获取常量池项
    ConstantPoolEntry entryByIndex(int index);
}

使用示例

1. 类文件分析

// 读取并分析类文件
byte[] classBytes = Files.readAllBytes(classFilePath);
ClassModel classModel = ClassFile.of().parse(classBytes);

// 遍历字段和方法
for (FieldModel fm : classModel.fields()) {
    System.out.printf("Field %s%n", fm.fieldName().stringValue());
}
for (MethodModel mm : classModel.methods()) {
    System.out.printf("Method %s%n", mm.methodName().stringValue());
}

// 使用类元素流遍历
for (ClassElement ce : classModel) {
    switch (ce) {
        case MethodModel mm -> System.out.printf("Method %s%n", mm.methodName().stringValue());
        case FieldModel fm -> System.out.printf("Field %s%n", fm.fieldName().stringValue());
        default -> { }
    }
}

2. 分析类依赖

// 分析类文件中的依赖关系
ClassModel classModel = ClassFile.of().parse(classBytes);
Set<ClassDesc> dependencies = new HashSet<>();

// 使用显式遍历
for (ClassElement ce : classModel) {
    if (ce instanceof MethodModel mm) {
        for (MethodElement me : mm) {
            if (me instanceof CodeModel xm) {
                for (CodeElement e : xm) {
                    switch (e) {
                        case InvokeInstruction i -> dependencies.add(i.owner().asSymbol());
                        case FieldInstruction i -> dependencies.add(i.owner().asSymbol());
                        default -> { }
                    }
                }
            }
        }
    }
}

// 使用流式处理
Set<ClassDesc> dependencies2 = classModel.elementStream()
    .flatMap(ce -> ce instanceof MethodModel mm ? mm.elementStream() : Stream.empty())
    .flatMap(me -> me instanceof CodeModel com ? com.elementStream() : Stream.empty())
    .<ClassDesc>mapMulti((xe, c) -> {
        switch (xe) {
            case InvokeInstruction i -> c.accept(i.owner().asSymbol());
            case FieldInstruction i -> c.accept(i.owner().asSymbol());
            default -> { }
        }
    })
    .collect(toSet());

3. 类文件修改

// 修改现有类文件
ClassBuilder builder = ClassFile.of().transform(classModel);
builder.withField(...)
       .withMethod(...)
       .build();

4. 创建新类

// 创建新的类文件
ClassBuilder builder = ClassFile.of().build(ClassDesc.of("com/example/NewClass"));
builder.withSuperclass(ClassDesc.of("java/lang/Object"))
       .withMethod(...)
       .build();

5. 修改方法字节码

// 修改方法的字节码
builder.withMethod("methodName", "()V", methodBuilder -> {
    methodBuilder.withCode(codeBuilder -> {
        codeBuilder.getstatic(...)
                  .ldc(...)
                  .invokevirtual(...)
                  .return_();
    });
});