JDK 24 Class File API 介绍

概述

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 类文件。以下是一些流行的库列表：

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

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

JDK API核心类关系图

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

核心类介绍

1. ClassModel

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 提供了丰富的字节码指令生成方法，包括：

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

这些方法使得生成字节码变得更加简单和直观，不需要直接处理底层的字节码指令。每个方法都返回 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_();
    });
});

API 优点

1. 类型安全：提供了类型安全的类文件操作，减少了运行时错误
2. 功能完整：支持类文件的读取、修改和创建
3. 字节码操作：可以方便地操作字节码
4. 结构完整：提供了完整的类文件结构模型
5. 注解支持：支持注解和属性的处理

应用场景

1. 类文件分析工具：用于分析类文件的结构和内容
2. 字节码增强：在运行时修改类的行为
3. 动态类生成：在运行时创建新的类
4. 类文件转换：将类文件转换为其他格式
5. 代码注入：向现有类中注入新的代码

注意事项

1. 使用 Class File API 时需要确保对类文件的操作符合 Java 虚拟机规范
2. 修改类文件时要注意保持类文件结构的完整性
3. 在处理字节码时要确保生成的字节码是有效的
4. 注意处理类文件版本兼容性问题

预告

下一期小子给各位看官详细介绍API的使用…