cglib 使用中的常见问题与排查方法

打开 cglib.sourceforge.net 会被自动跳转到 GitHub，是因为 cglib 已经迁移托管平台，SourceForge 上的页面只保留了一个跳转提示。这个现象本身不是故障，而是项目地址变更的结果。使用 cglib 时真正容易出问题的，是代理失败、依赖引入和 JDK 兼容性这几类情况，下面按现象逐项说明。

为什么访问 cglib.sourceforge.net 会跳转

该站点页面上的原文提示是：cglib is now hosted on github，并附带一句“如果没有自动跳转请点击这里”。也就是说，SourceForge 域名不再作为 cglib 的主托管地，继续访问会被引导到 GitHub。

需要下载或查看源码时，直接使用 GitHub 上的仓库，不要依赖 SourceForge 的旧链接。旧链接可能仍能跳转，但不适合作为长期引用地址。

无法代理 final 类或 final 方法

这是 cglib 最常见的失败场景，根源在于它的工作方式：cglib 通过生成目标类的子类来实现代理，而 Java 语言不允许继承 final 类、也不允许覆盖 final 方法。

典型表现：

• 对 final 类做代理时，抛出类似“Cannot subclass final class”的异常。
• 类本身可继承，但目标方法是 final，代理对象调用该方法时不会进入拦截逻辑，而是直接执行原方法。

排查思路：

1. 确认目标类是否被声明为 final。
2. 确认需要拦截的方法是否被声明为 final（包括 private 方法，它们同样无法被覆盖）。
3. 如果无法修改目标类，改用基于接口的 JDK 动态代理，或调整设计把需要增强的逻辑放到可覆盖的方法上。

选择条件很明确：目标类型是接口实现、且只关心接口方法时，JDK 动态代理更合适；需要代理普通类的方法时，才需要 cglib 这类子类化方案。

依赖没有正确引入

cglib 不是 JDK 自带库，缺少依赖时会在运行期报 NoClassDefFoundError 或 ClassNotFoundException，指向 net.sf.cglib 包下的类。

处理方式：

• 确认构建配置中声明了 cglib 依赖，并且版本与项目使用的 JDK 匹配。
• 如果项目通过 Spring 等框架间接使用 cglib，注意框架可能自带了一份重新打包的 cglib（包名通常不同），此时不要重复引入造成冲突。
• 出现类冲突时，用依赖树命令检查是否存在多个来源的 cglib 相关类。

不同 JDK 版本下的兼容性

cglib 依赖字节码生成，JDK 版本变化会影响它的可用性，尤其是模块化之后对底层 API 的访问限制变严。

需要注意的点：

• 较新的 JDK 上，cglib 访问 JDK 内部类可能被模块系统拒绝，表现为 IllegalAccessError 或反射相关的异常。
• 遇到这类问题时，通常需要升级 cglib 到支持当前 JDK 的版本，或改用框架自身维护的字节码方案。
• 具体哪个版本支持哪个 JDK，以 GitHub 仓库的发布说明为准，不要凭经验推断。

与框架集成时的类加载器问题

在应用服务器、OSGi 容器或自定义类加载器环境中，cglib 生成的代理类需要能访问目标类。如果两者由不同的类加载器加载，可能出现 ClassNotFoundException 或类型转换失败。

排查方向：

• 确认代理类和目标类处于同一个类加载器可见范围。
• 检查是否存在热部署导致的类加载器泄漏，旧代理类未被释放会持续占用内存。
• 框架集成场景下，优先使用框架提供的代理配置入口，而不是手动创建 Enhancer。

快速对照表

判断优先级时，先看异常信息指向的是“不能继承”还是“找不到类”，前者是设计约束，后者是环境配置，两者的修复路径完全不同。