ByteBuddy 是当下最流行的 Java 字节码增强库，配合 Java Agent 机制，可以在不修改业务源码的前提下，为任意方法注入埋点、监控与改造逻辑。本文从零带你写一个生产可用的 Agent，覆盖方法耗时统计、参数拦截、Spring 接口埋点与容器部署。
一、为什么需要字节码增强
很多横切需求——链路追踪、方法耗时统计、参数校验、灰度开关——如果写进业务代码，会和主逻辑纠缠在一起，后期难以维护。传统 AOP（如 Spring AOP）只能拦截 Spring 托管的 Bean，对第三方库、JDK 类、静态方法往往无能为力。
Java 在启动时通过 java -javaagent 加载一个 Agent，Agent 拿到 Instrumentation 句柄，就能在类加载的瞬间改写它的字节码。这就是 Java Agent + 字节码增强的核心能力：无侵入、全覆盖、可热插拔。
二、ByteBuddy 的三大核心概念
1. Instrumentation 与 Java Agent
Agent 必须实现 premain(String, Instrumentation) 方法，JVM 在 main 之前调用它。我们拿到 inst 后交给 ByteBuddy 的 AgentBuilder 安装。
2. AgentBuilder：声明式编排
比起直接用 ASM 手写字节码（繁琐且易错），ByteBuddy 用流式 API 描述”拦截哪些类、哪些方法、用什么逻辑替换”，可读性高得多。
3. ElementMatcher：精准匹配
匹配器决定增强范围，既能按包名、注解、父类过滤，也能组合 and/not 表达式，避免误伤无关类。
三、第一个 Agent：统计任意方法耗时
下面这个 Agent 会给 com.example.service 包下名为 createOrder 的实例方法，自动套上耗时统计逻辑，而业务代码一行都不用改。这种”零侵入”的改法，在已有系统想快速接入监控、又不敢大改代码时尤其好用——你甚至可以在不重新发版的情况下，仅仅换一个 -javaagent 就改变运行时行为，灰度与回滚都只发生在启动参数层面。
// TimingAgent.java
import net.bytebuddy.agent.builder.AgentBuilder;
import net.bytebuddy.asm.Advice;
import net.bytebuddy.matcher.ElementMatchers;
import java.lang.instrument.Instrumentation;
public class TimingAgent {
public static void premain(String args, Instrumentation inst) {
new AgentBuilder.Default()
.type(ElementMatchers.nameStartsWith("com.example.service"))
.transform((builder, type, cl, module, pd) ->
builder.visit(Advice.to(TimingAdvice.class)
.on(ElementMatchers.isMethod()
.and(ElementMatchers.not(ElementMatchers.isStatic()))
.and(ElementMatchers.named("createOrder")))))
.installOn(inst);
}
}四、拦截器 Advice 怎么写
真正的增强逻辑放在 Advice 类里。用 @OnMethodEnter 在方法入口记录时间戳，@OnMethodExit 在出口计算耗时。@Advice.Enter 负责把入口的返回值（这里是 start 时间戳）透传给出口方法，类型必须一致。
// TimingAdvice.java
import net.bytebuddy.asm.Advice;
public class TimingAdvice {
@Advice.OnMethodEnter
public static long enter() {
return System.nanoTime();
}
@Advice.OnMethodExit(onThrowable = Throwable.class, inline = false)
public static void exit(@Advice.Enter long start,
@Advice.Origin String method,
@Advice.Thrown Throwable t) {
long costMs = (System.nanoTime() - start) / 1_000_000;
String tag = (t == null) ? "OK" : "ERR:" + t.getClass().getSimpleName();
System.out.printf("[trace] %s cost=%dms %s%n", method, costMs, tag);
}
}注意 inline = false：当增强逻辑较复杂时，关闭内联能让 Advice 以独立类加载，调试更友好，也避免某些场景下常量折叠导致的行为差异。
五、ElementMatcher 速查表
| 匹配器 | 作用 | 典型用法 |
nameStartsWith | 按包名/类名前缀 | 只增强自家业务包 |
named / namedIgnoreCase | 精确方法名 | 拦截 createOrder |
isAnnotatedWith | 带某注解的类/方法 | 拦截 @GetMapping |
hasSuperType | 实现某接口/继承某类 | 增强所有 Repository |
not / and / or | 逻辑组合 | 排除静态与构造器 |
六、实战：无侵入给 Spring 接口埋点
结合注解匹配，我们可以给所有 @RestController 中被 @GetMapping 标注的方法统一加计时，无需触碰任何 Controller 代码。
new AgentBuilder.Default()
.type(ElementMatchers.hasAnnotation(
ElementMatchers.named("org.springframework.web.bind.annotation.RestController")))
.transform((b, t, cl, m, pd) -> b.visit(Advice.to(ApiTimer.class)
.on(ElementMatchers.isAnnotatedWith(
ElementMatchers.named("org.springframework.web.bind.annotation.GetMapping")))))
.installOn(inst);这种”按注解批量织入”的能力，正是 Arthas 线上诊断实战 里运行时诊断之外，另一种把可观测性做进字节码的常态化手段——前者适合临时排障，后者适合长期埋点。
七、ByteBuddy vs ASM vs 其他方案
| 方案 | 上手成本 | 可读性 | 适用场景 |
| ByteBuddy | 低 | 高（流式 API） | 绝大多数 Agent / 运行时代理 |
| ASM | 高 | 低（手写字节码） | 极致性能、框架底层 |
| Spring AOP | 低 | 高 | 仅 Spring Bean 内部调用 |
| Java Proxy | 低 | 中 | 仅接口，无法增强类 |
八、生产级注意事项
字节码增强威力大，但有几个坑必须提前规避：
- 类加载器隔离：Agent 与被增强类可能由不同 ClassLoader 加载，Advice 类若依赖业务类型，要用
Advice.WithCustomPipeline或显式指定辅助类的加载方式，否则会报NoClassDefFoundError。 - 性能开销：每个方法调用都多一层拦截，高频小方法要评估。统计类逻辑尽量轻量，必要时用 Java 21 虚拟线程 的思路把重活异步化，别在拦截器里做阻塞 IO。
- 重定义限制：已加载的类默认只能”重转换”（retransform），不能增删方法；增删结构需要在类”首次加载前”就介入（即 premain 阶段）。
- GraalVM native 不兼容：native image 是封闭世界，运行期字节码增强基本失效，需改用构建期插件或编译期织入。
九、打包与容器部署
Agent 本身是一个 jar，必须在 MANIFEST.MF 里声明 Premain-Class。Maven 可用 maven-jar-plugin 写入；依赖 ByteBuddy 时同时引入 byte-buddy 与 byte-buddy-agent。
<dependency>
<groupId>net.bytebuddy</groupId>
<artifactId>byte-buddy</artifactId>
<version>1.15.0</version>
</dependency>
<dependency>
<groupId>net.bytebuddy</groupId>
<artifactId>byte-buddy-agent</artifactId>
<version>1.15.0</version>
</dependency>在容器里通过 -javaagent 挂载，业务 jar 完全无感知。配合 Docker Compose 一键编排 或 GitHub Actions 流水线 把 Agent 一起打包进镜像，就能做到”部署即埋点”。
FROM eclipse-temurin:21-jdk
COPY target/app.jar /app/app.jar
COPY target/timing-agent.jar /agent/timing-agent.jar
ENTRYPOINT ["java", "-javaagent:/agent/timing-agent.jar", "-jar", "/app/app.jar"]十、用单元测试守护拦截器
Advice 类虽然运行时织入，但纯逻辑部分仍可用 JUnit 5 编写单测：把计时、异常标记等逻辑抽成可测的静态方法，保证埋点本身不出错。ByteBuddy 也提供 ByteBuddy().redefine 在测试中直接对一个普通类做增强，验证织入结果。
// 测试中对普通类做增强验证
new ByteBuddy()
.redefine(Target.class)
.visit(Advice.to(TimingAdvice.class).on(ElementMatchers.named("run")))
.make()
.load(Target.class.getClassLoader())
.getLoaded()
.getDeclaredConstructor()
.newInstance()
.run();十一、进阶：用 MethodDelegation 改写返回值
除了 Advice，ByteBuddy 还提供 MethodDelegation：把方法调用”委托”到一个普通拦截器类，拦截器可以拿到参数、返回值，甚至用 @SuperCall 决定是否调用原方法。它比 Advice 更适合需要”改写返回值”或”短路返回”的场景，比如给读接口加一层进程内缓存。
public class CacheInterceptor {
@RuntimeType
public static Object intercept(@SuperCall Callable<?> zuper,
@Origin Method method,
@AllArguments Object[] args) throws Exception {
String key = method.getName() + Arrays.toString(args);
Object cached = CacheHolder.get(key);
if (cached != null) return cached; // 命中则短路
Object result = zuper.call(); // 否则走原方法
CacheHolder.put(key, result);
return result;
}
}接入方式同样简单：.transform((b, t, cl, m, pd) -> b.method(ElementMatchers.any()).intercept(MethodDelegation.to(CacheInterceptor.class)))。配合 @Morph、@Pipe 等注解还能实现参数重写与链式委托。注意 @SuperCall 要求原方法可被调用，抽象方法或 final 方法会匹配失败，需要在 Matcher 里提前排除，否则 ByteBuddy 安装阶段就会抛 IllegalStateException。
十二、落地清单
- 明确增强范围：用 ElementMatcher 精准收敛，避免全量扫描拖慢启动。
- Advice 逻辑保持无状态、无阻塞，必要时异步上报。
- 声明 Premain-Class，本地用
-javaagent跑通再上容器。 - 在预发环境对比增强前后的启动耗时与 GC，确认无回归。
- 长期埋点用 Agent，临时排障用 Arthas，两者互补。
十三、小结
ByteBuddy 把”字节码增强”这件原本高门槛的事，变成了几行流式 API。配合 Java Agent，你可以在不动业务代码的前提下，把可观测性、限流、灰度等横切能力”织”进每一个方法。它和 Java 函数式编程 一样，都是现代 Java 工程师武器库里值得熟练掌握的工具——前者改运行时的行为，后者改写代码的方式。从今天这篇的最小 Agent 起步，逐步把监控做进字节码吧。
