Apache Commons BCEL 快速入门与集成示例

目标：用三个可独立复现的示例快速上手 BCEL——解析 javac 编译产物、动态生成一个可运行的 HelloWorld 类、遍历方法字节码指令序列，并给出把 BCEL 集成进现有工程的关键要点。已在 Ubuntu 22.04.5 LTS + OpenJDK 17.0.20.1 + Apache Maven 3.6.3 环境实测通过。

一、环境信息

BCEL 是 Apache 官方的字节码操作库，读取 class 文件走 ClassParser，生成与改写走 ClassGen 系列类，指令级操作走 InstructionList。本章示例工程为 Maven 工程 bcel-demo，目录 /opt/lab/bcel-demo，三个示例类都在 src/main/java/demo 包下，共用下面这份 pom.xml。

项目	实测值
操作系统	Ubuntu 22.04.5 LTS（x86_64）
JDK	OpenJDK 17.0.20.1（编译目标 Java 8，产物 major=52）
Maven	3.6.3
BCEL	6.13.0（org.apache.bcel:bcel）
传递依赖	commons-lang3 3.20.0、commons-io 2.22.0

<dependency>
  <groupId>org.apache.bcel</groupId>
  <artifactId>bcel</artifactId>
  <version>6.13.0</version>
</dependency>

坐标注意：BCEL 在 Maven 中央仓库的 groupId 是 org.apache.bcel，写成 commons-bcel:commons-bcel 会解析失败（该坐标实测 404）。

cd /opt/lab/bcel-demo && mvn dependency:tree

输出节选（实测首尾）：

[INFO] --- maven-dependency-plugin:2.8:tree (default-cli) @ bcel-demo ---
[INFO] demo:bcel-demo:jar:1.0.0
[INFO] \- org.apache.bcel:bcel:jar:6.13.0:compile
[INFO]    +- org.apache.commons:commons-lang3:jar:3.20.0:compile
[INFO]    \- commons-io:commons-io:jar:2.22.0:compile

💡 技术拓展：ASM 与 Javassist 是与 BCEL 定位相近的另两个字节码操作库，三者都通过依赖引入、都无自带 CLI，差异在抽象层级与场景。本文使用 BCEL。

库	抽象层级	上手难度	典型场景
BCEL	常量池/指令完整对象模型	中	class 文件解析、审计、结构级修改与生成
ASM	事件访问器 + 树 API	较高	高性能字节码织入，框架底层（Spring/CGLIB）
Javassist	源码风格 API	低	运行时插桩、AOP 简单增强

二、三步跑通第一个示例

第一步建工程。pom.xml 见第一节，源码目录为 src/main/java/demo：

mkdir -p /opt/lab/bcel-demo/src/main/java/demo

实测回显（命令无输出，退出码 0）。

第二步写两个类。HelloWorld.java 是最普通的被解析对象：

package demo;

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

ParseHello.java 是第一个 BCEL 程序，解析上面的编译产物并打印类结构：

package demo;

import org.apache.bcel.classfile.ClassParser;
import org.apache.bcel.classfile.JavaClass;
import java.io.IOException;

public class ParseHello {
    public static void main(String[] args) throws IOException {
        ClassParser parser = new ClassParser(args[0]);
        JavaClass jc = parser.parse();
        System.out.println("完整类名   : " + jc.getClassName());
        System.out.println("父类       : " + jc.getSuperclassName());
        System.out.println("字节码版本 : major=" + jc.getMajor() + ", minor=" + jc.getMinor());
        System.out.println("常量池长度 : " + jc.getConstantPool().getLength());
        System.out.println("访问标志   : 0x" + Integer.toHexString(jc.getAccessFlags()));
        System.out.println("方法数     : " + jc.getMethods().length);
        System.out.println("源文件名   : " + jc.getSourceFileName());
    }
}

逐项说明：BCEL 的解析入口类是 ClassParser（不存在名为 Parser 的类）；parse() 返回只读的 JavaClass 对象；getMajor()/getMinor() 是 class 文件版本号对；getConstantPool().getLength() 含 JVM 规范保留的 0 号条目；getAccessFlags() 的 0x21 即 ACC_PUBLIC|ACC_SUPER。

第三步编译运行：

cd /opt/lab/bcel-demo && mvn -q compile

实测回显（构建成功无输出，验证产物）：

ls target/classes/demo/

实测回显：

DumpCode.class
GenHello.class
HelloWorld.class
ParseHello.class

export LANG=C.UTF-8 LC_ALL=C.UTF-8
mvn -q exec:java -Dexec.mainClass=demo.ParseHello -Dexec.args="target/classes/demo/HelloWorld.class"

实测回显：

完整类名   : demo.HelloWorld
父类       : java.lang.Object
字节码版本 : major=52, minor=0
常量池长度 : 34
访问标志   : 0x21
方法数     : 2
源文件名   : HelloWorld.java

pom 里 maven.compiler.target=8 使产物版本为 major=52，BCEL 读出的值与之吻合，第一个示例跑通。

三、解析已有类文件并与 javap 对照

解析真实产物时最有价值的是版本号与常量池：版本号决定最低运行 JDK，常量池则反映字符串、类引用与方法引用的全貌。用 javap 做对照，验证 BCEL 读到的信息与 JDK 官方工具一致：

javap -v -cp target/classes demo.HelloWorld

输出节选（实测首尾）：

public class demo.HelloWorld
  minor version: 0
  major version: 52
  flags: (0x0021) ACC_PUBLIC, ACC_SUPER
Constant pool:
   #1 = Methodref          #2.#3          // java/lang/Object."<init>":()V
   #2 = Class              #4             // java/lang/Object

javap 显示 major version: 52、flags 0x21，与第二节 ParseHello 回显完全一致；常量池方面 javap 列出的最大序号加保留 0 号条目即 34，也与 getLength() 对应。ClassParser 还有两种构造形态可选：new ClassParser(InputStream, "文件名") 用于内存或网络流，new ClassParser("demo.jar", "demo/HelloWorld") 直接解析 jar 包内的类条目，参数中的文件名仅用于异常信息标注。

四、动态生成一个可运行的类

第二个示例用 ClassGen 从零生成一个含 main 方法的类，写盘后直接用 java 运行。完整源码 GenHello.java：

package demo;

import org.apache.bcel.Const;
import org.apache.bcel.classfile.JavaClass;
import org.apache.bcel.generic.ArrayType;
import org.apache.bcel.generic.ClassGen;
import org.apache.bcel.generic.ConstantPoolGen;
import org.apache.bcel.generic.GETSTATIC;
import org.apache.bcel.generic.INVOKEVIRTUAL;
import org.apache.bcel.generic.InstructionList;
import org.apache.bcel.generic.LDC;
import org.apache.bcel.generic.MethodGen;
import org.apache.bcel.generic.RETURN;
import org.apache.bcel.generic.Type;
import java.io.FileOutputStream;

public class GenHello {
    public static void main(String[] args) throws Exception {
        ClassGen cg = new ClassGen("GenHello", "java.lang.Object",
                "GenHello.java", Const.ACC_PUBLIC | Const.ACC_SUPER, null);
        ConstantPoolGen cp = cg.getConstantPool();
        cg.setMajor(52);
        cg.setMinor(0);
        cg.addEmptyConstructor(Const.ACC_PUBLIC);

        InstructionList il = new InstructionList();
        MethodGen mg = new MethodGen(Const.ACC_PUBLIC | Const.ACC_STATIC, Type.VOID,
                new Type[] { new ArrayType(Type.STRING, 1) },
                new String[] { "args" }, "main", "GenHello", il, cp);
        il.append(new GETSTATIC(cp.addFieldref("java.lang.System", "out", "Ljava/io/PrintStream;")));
        il.append(new LDC(cp.addString("Hello, BCEL! 类已由 ClassGen 动态生成")));
        il.append(new INVOKEVIRTUAL(cp.addMethodref("java.io.PrintStream", "println", "(Ljava/lang/String;)V")));
        il.append(new RETURN());
        mg.setMaxStack();
        mg.setMaxLocals();
        cg.addMethod(mg.getMethod());
        il.dispose();

        JavaClass jc = cg.getJavaClass();
        try (FileOutputStream fos = new FileOutputStream("GenHello.class")) {
            jc.dump(fos);
        }
        System.out.println("动态生成类 : " + jc.getClassName());
        System.out.println("字节码版本 : major=" + jc.getMajor() + ", minor=" + jc.getMinor());
        System.out.println("常量池长度 : " + jc.getConstantPool().getLength());
        System.out.println("已写出文件 : GenHello.class");
    }
}

逐段说明：

ClassGen(类名, 父类, 源文件名, 访问标志, 接口数组) 建类骨架，访问标志用现行 org.apache.bcel.Const 常量（旧的 Constants 类已废弃）。
ConstantPoolGen cp = cg.getConstantPool()：必须取 ClassGen 内部的池。实测若另建 new ConstantPoolGen() 传给 MethodGen，写盘常量池与指令索引错位，JVM 加载时报 Illegal constant pool index，这是 BCEL 生成路径最常见的坑。
setMajor(52)/setMinor(0)：ClassGen 默认版本是 major=45/minor=3，实测不设置时生成类版本为 45.3，显式设为 52（Java 8）更稳妥。
指令序列等价于源码 System.out.println("...")：GETSTATIC 取 System.out，LDC 加载字符串，INVOKEVIRTUAL 调用 println，RETURN 结束；三条引用都通过 cp.add* 拿常量池索引。
setMaxStack()/setMaxLocals() 让 BCEL 自动计算栈帧参数，缺了它们生成的类无法通过校验。

运行生成程序，再运行生成出来的类：

mvn -q exec:java -Dexec.mainClass=demo.GenHello

实测回显：

动态生成类 : GenHello
字节码版本 : major=52, minor=0
常量池长度 : 33
已写出文件 : GenHello.class

java -cp .:target/classes GenHello

实测回显：

Hello, BCEL! 类已由 ClassGen 动态生成

生成类直接被 JVM 加载并正确执行，说明常量池、方法表与栈帧信息全部合法。用 javap 复核版本：

javap -v /opt/lab/bcel-demo/GenHello.class

输出节选（实测首尾）：

  minor version: 0
  major version: 52
  flags: (0x0021) ACC_PUBLIC, ACC_SUPER

五、遍历方法字节码指令

第三个示例把 main 方法的 Code 属性还原成指令序列，这是做字节码插桩与审计的基础。完整源码 DumpCode.java：

package demo;

import org.apache.bcel.classfile.ClassParser;
import org.apache.bcel.classfile.JavaClass;
import org.apache.bcel.classfile.Method;
import org.apache.bcel.generic.ConstantPoolGen;
import org.apache.bcel.generic.InstructionHandle;
import org.apache.bcel.generic.InstructionList;
import org.apache.bcel.generic.MethodGen;
import java.io.IOException;

public class DumpCode {
    public static void main(String[] args) throws IOException {
        JavaClass jc = new ClassParser(args[0]).parse();
        ConstantPoolGen cp = new ConstantPoolGen(jc.getConstantPool());
        for (Method m : jc.getMethods()) {
            if (m.isAbstract() || m.isNative()) {
                continue;
            }
            System.out.println("== 方法 " + m.getName() + m.getSignature());
            MethodGen mg = new MethodGen(m, jc.getClassName(), cp);
            InstructionList il = mg.getInstructionList();
            for (InstructionHandle ih : il) {
                System.out.printf("%4d: %s%n", ih.getPosition(), ih.getInstruction());
            }
            il.dispose();
        }
    }
}

逐项说明：这里从只读的 JavaClass 出发，把原常量池包成 ConstantPoolGen 供 MethodGen 复用（解析场景下新建包装是合法的，与第四节生成场景的坑不同）；mg.getInstructionList() 产出可遍历的指令链表；ih.getPosition() 为方法内字节偏移；il.dispose() 释放句柄链表，遍历后不再需要时建议调用。

mvn -q exec:java -Dexec.mainClass=demo.DumpCode -Dexec.args="target/classes/demo/HelloWorld.class"

输出节选（实测首尾）：

== 方法 <init>()V
   0: aload_0[42](1)
   1: invokespecial[183](3) 1
   4: return[177](1)
== 方法 main([Ljava/lang/String;)V
   0: getstatic[178](3) 7
   3: ldc[18](2) 13
   5: invokevirtual[182](3) 15
   8: return[177](1)

输出格式为偏移: 助记符操作码编号常量池索引，与 javap -c 的反汇编逐指令一致（getstatic/ldc/invokevirtual/return，偏移 0、3、5、8 相同），两条工具链互为印证。

六、与现有工程集成要点

把 BCEL 集成进现有 Maven/Gradle 工程时，以下四点实测教训值得前置确认：

依赖不只有 BCEL 一个 jar。6.13.0 会传递引入 commons-lang3 3.20.0 与 commons-io 2.22.0（第一节依赖树实测），工程内若已有这两个库，注意版本仲裁结果；手动部署时则必须三个 jar 齐备，缺 commons-io 时实测报 NoClassDefFoundError: org/apache/commons/io/IOUtils。
编译目标要与解析对象对齐。BCEL 本体运行基线是 Java 8（major=52），但它能解析更高版本的 class 文件；生成类时用 setMajor/setMinor 显式定版本，避免默认 45.3。
字节码分析任务是一次性的，无常驻服务，JVM 参数按短生命周期任务给即可，实测 -Xmx256m 运行解析示例无压力：

java -Xmx256m -Dfile.encoding=UTF-8 -cp "target/classes:$HOME/.m2/repository/org/apache/bcel/bcel/6.13.0/bcel-6.13.0.jar:$HOME/.m2/repository/commons-io/commons-io/2.22.0/commons-io-2.22.0.jar:$HOME/.m2/repository/org/apache/commons/commons-lang3/3.20.0/commons-lang3-3.20.0.jar" demo.ParseHello target/classes/demo/HelloWorld.class

输出节选（实测首尾）：

完整类名   : demo.HelloWorld
父类       : java.lang.Object
字节码版本 : major=52, minor=0

中文输出环境。locale 非 UTF-8 的服务器上，先 export LANG=C.UTF-8 LC_ALL=C.UTF-8 再给 java 追加 -Dfile.encoding=UTF-8，二者实测缺一不可，否则示例里的中文字符串打印为问号。

七、参考链接

BCEL 官方主页：https://commons.apache.org/proper/commons-bcel/
BCEL 官方 API 文档：https://commons.apache.org/proper/commons-bcel/apidocs/
BCEL 官方示例源码（发行包 src 目录）：https://downloads.apache.org/commons/bcel/source/
Maven 中央仓库 BCEL 构件：https://repo1.maven.org/maven2/org/apache/bcel/bcel/6.13.0/
BCEL 发行目录：https://downloads.apache.org/commons/bcel/