Apache Commons Weaver 2.0 介绍与选型指南

目标：基于 Apache 官方文档、Maven Central 与 GitHub 仓库联网溯源（查询日期 2026-10-18），介绍 Apache Commons Weaver 2.0 的定位、构建期织入架构、两个官方模块（Privilizer/Normalizer）与同类选型对比，帮助读者判断是否值得在构建链路中引入。

一、信息基准

本章为全文信息基准：所有版本号、发布时间、能力描述均来自下列官方来源，查询日期统一为 2026-10-18。

1.1 查询日期与版本依据

1.2 官方来源清单

• 项目主页：https://commons.apache.org/proper/commons-weaver/
• 下载页：https://commons.apache.org/proper/commons-weaver/download_weaver.cgi
• Javadoc 2.0：https://commons.apache.org/proper/commons-weaver/javadocs/2.0/index.html
• Maven 插件信息页：https://commons.apache.org/proper/commons-weaver/commons-weaver-parent/commons-weaver-maven-plugin/plugin-info.html
• Antlib 信息页：https://commons.apache.org/proper/commons-weaver/commons-weaver-parent/commons-weaver-antlib/index.html
• Maven Central 构件：https://repo1.maven.org/maven2/org/apache/commons/commons-weaver-normalizer/
• GitHub 只读副本：https://github.com/apache/commons-weaver

二、软件概述

Apache Commons Weaver 2.0（2018-09-01 官网发布页标注，Apache License 2.0，官方最新在架版本，项目处于休眠状态）是 Apache Commons 旗下的构建期字节码织入框架：它定义了一套可扩展的 Processor SPI，允许"织入处理器（Weaver Processor）"在编译完成后扫描目标工程的字节码，按注解或其他标记对类做自动化的字节码转换（来源：官网 Overview/Project Structure，2026-10-18）。

官方自带两个模块：Privilizer（自动生成 PrivilegedAction 相关代码，减少手写样板）与 Normalizer（在构建期把字符串常量归一化）。Weaver 本身不提供通用 AOP 能力，也不处理方法拦截语义，其目标是把"重复、机械、可由工具生成的代码变换"从源码中移走，交由构建期织入完成（来源：官网各模块页，2026-10-18）。

社区活跃度方面：GitHub 只读副本 apache/commons-weaver 仅 29 stars，最近推送为 2026-10-17（仓库维护性质），Maven Central 上 2.0 之后的近 8 年无任何新版本（来源：GitHub API / repo1.maven.org，2026-10-18 实查）。选型前应把它当作"休眠的专项工具"评估，而非活跃依赖。

三、核心架构

3.1 织入模型：构建期 + Processor SPI

Weaver 的织入发生在构建期（编译后、打包前），而非运行期：

1. 目标工程编译产生字节码；
2. 织入工具（Maven 插件或 Antlib）调用 Weaver 核心扫描 classpath 上的 Weaver Processor；
3. 每个 Processor 根据"织入标记"（如目标类上的注解）决定是否改写字节码；
4. 转换后的字节码回写，后续打包、测试均使用织入产物。

（来源：官网 Project Structure 中 commons-weaver-processor 与各模块说明，2026-10-18）

3.2 构成与集成方式

（来源：官网左侧导航与各构件页，2026-10-18）

3.3 官方模块说明

• Privilizer：面向"代码需要以特权方式访问受保护资源"的场景，自动生成 PrivilegedAction 包装类，提供 never/optional/always 等策略控制特权检查的生成方式（来源：官网 Privilizer 模块页）。> ⚠️ 注意：Privilizer 的目标场景依赖 Java SecurityManager 体系，而 SecurityManager 自 JDK 17 起被标记弃用（JEP 411）并在 JDK 24 起被永久禁用（JEP 486），该模块的现实适用面已明显收窄。
• Normalizer：在构建期对字符串字面量做 Unicode 归一化（如 NFC），用于降低"同一逻辑字符串存在多种字节表示"带来的安全隐患（来源：官网 Normalizer 模块页）。

四、功能特性

• 构建期自动化改写：织入产物进入最终构建件，运行期零额外开销、无代理对象；
• Processor 可插拔：业务方可按 SPI 自行编写织入处理器，处理自有注解；
• 双构建体系支持：同一套 Processor 可通过 Maven 插件或 Antlib 在不同构建体系中复用；
• 类路径级扫描：Processor 可处理工程内与依赖中的字节码；
• 模块化交付：Privilizer/Normalizer 互相独立，可按需引入。 （来源：官网 Overview 与各模块页综合，2026-10-18）

功能边界：Weaver 不提供切面语言（无 pointcut/advice DSL），不支持运行期动态织入，也没有官方 Spring 集成——这些分别是 AspectJ、Java Agent 体系与其他字节码库的领域。

五、快速上手

以下为按官方 plugin-info 与 Antlib 信息页转写的接入示例（未做本地运行；坐标与配置键以官网 2.0 文档为准）。

5.1 Maven 接入（官网 plugin-info 转写）

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.commons</groupId>
      <artifactId>commons-weaver-maven-plugin</artifactId>
      <version>2.0</version>
      <executions>
        <execution>
          <goals>
            <goal>weave</goal><!-- 织入当前工程编译产物 -->
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Privilizer/Normalizer 作为 Processor 依赖加入织入类路径（插件会在运行时通过 SPI 发现它们）：

<dependencies>
  <dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-weaver-privilizer</artifactId>
    <version>2.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

（来源：https://commons.apache.org/proper/commons-weaver/commons-weaver-parent/commons-weaver-maven-plugin/plugin-info.html，查询日期 2026-10-18）

5.2 Ant 接入（官网 Antlib 转写）

<project xmlns:weaver="antlib:org.apache.commons.weaver">
  <taskdef uri="antlib:org.apache.commons.weaver"
           resource="org/apache/commons/weaver/antlib.xml"
           classpath="commons-weaver-antlib-2.0.jar"/>
  <!-- 对编译输出目录执行织入 -->
  <weaver:weave/>
</project>

（来源：https://commons.apache.org/proper/commons-weaver/commons-weaver-parent/commons-weaver-antlib/index.html，查询日期 2026-10-18；任务名与属性以该页为准）

六、适用场景与限制

适用场景

• 存在大量机械性样板代码（如安全特权包装），希望构建期自动生成；
• 需要在构建期对全工程字符串常量统一归一化（安全加固类需求）；
• 构建体系以 Maven/Ant 为主，且接受 JDK 8 时代工具链的存量工程。

限制与风险（选型前必读）

• 休眠项目：2.0 后近 8 年无新版本（repo1.maven.org，2026-10-18 实查），缺陷修复与新 JDK 适配无保障；
• JDK 17+ 下 SecurityManager 弃用/禁用（JEP 411/486）直接削弱 Privilizer 的目标场景；
• 织入结果对调试不友好（字节码生成代码与源码不一致），排查成本高；
• 无 AOP DSL，能力范围远小于 AspectJ；社区规模小（29 stars），遇到问题基本依赖读源码。

七、同类选型对比

7.1 对比表

对比对象选取 AspectJ（织入/AOP 事实标准）、Spring AOP（运行期代理）与 Byte Buddy（字节码生成库，代表 Agent/自定义增强路线）；数据查询日期 2026-10-18。

（stars 与推送时间来源：GitHub API / shields.io，2026-10-18；版本来源：Maven Central metadata，2026-10-18 实查）

7.2 选型建议

一句话选型：通用 AOP 织入直接选 AspectJ；Spring 技术栈内做切面用 Spring AOP（代理语义够用）；自定义 Agent/字节码增强选 Byte Buddy；只有在"维护存量、且恰好命中 Privilizer/Normalizer 场景"时才引入休眠中的 Commons Weaver，新项目不建议。

八、参考链接

1. 项目主页：https://commons.apache.org/proper/commons-weaver/
2. Javadoc 2.0：https://commons.apache.org/proper/commons-weaver/javadocs/2.0/index.html
3. Maven 插件信息页：https://commons.apache.org/proper/commons-weaver/commons-weaver-parent/commons-weaver-maven-plugin/plugin-info.html
4. Antlib 信息页：https://commons.apache.org/proper/commons-weaver/commons-weaver-parent/commons-weaver-antlib/index.html
5. Maven Central 构件：https://repo1.maven.org/maven2/org/apache/commons/commons-weaver-normalizer/
6. GitHub 只读副本：https://github.com/apache/commons-weaver
7. AspectJ：https://eclipse.dev/aspectj/
8. JEP 411（SecurityManager 弃用）：https://openjdk.org/jeps/411 ；JEP 486（永久禁用）：https://openjdk.org/jeps/486