一、起源:重复样板代码的成本

1.1 样板代码的几种形态

样板代码的共同特征是结构固定、由其他信息(字段列表、接口签名、注解)完全决定,却需要人工维护并与源定义保持同步:

形态 典型内容 维护方式 同步遗漏的后果
对象映射 实体与视图对象之间的逐字段复制 每新增一个字段需在两处各改一次 字段静默丢失,接口返回缺字段且无告警
构造器与访问器 getter、setter、构造器、equals、hashCode、toString 每个字段对应多个方法 equals 与 hashCode 不同步会导致集合去重与查找行为异常
常量与元数据 枚举、字符串常量、字段名清单、取值表 取值分散在多个类中 改名遗漏,运行期按名称匹配失败
配置类与绑定 配置项到对象的绑定、默认值、校验规则 新增配置项需改动绑定类与默认值 默认值与配置文件不一致,行为难以判断
接口与实现绑定 工厂、注册表、路由表、组件清单 新增实现需在注册处手工登记 实现未被登记,编译通过但功能不生效

这些内容的重复程度可以用"重复次数乘以变更频率"衡量。重复次数少或几乎不变更的样板,手工维护的成本低于引入生成机制的固定成本;只有当重复次数与变更频率同时较高时,代码生成才具备明确的收益。

1.2 运行期反射方案的代价

在不生成代码的前提下处理这类样板,常见做法是运行期反射:框架在启动或首次调用时读取注解与类型信息,动态完成字段复制、实例创建与方法调用。该方案省去构建期配置,代价集中在四处:

维度 表现 影响面
启动时间 扫描类路径、解析注解、构建元数据缓存 应用规模越大越明显,容器化与弹性扩容场景下反复支付
调用性能 方法查找、参数装箱、访问检查,难以被内联优化 热点路径需额外的缓存与优化手段
错误发现时机 字段名与类型不匹配、缺少构造器只在运行期抛出 首次执行路径才暴露,测试未覆盖的分支可能在生产触发
可调试性 堆栈停在框架内部的通用调用点 定位到具体业务行为需要额外的诊断输出

反射读取注解的能力与其保留策略直接相关,相关机制见 反射。

1.3 编译期生成把错误提前

编译期生成的做法是:在编译过程中读取注解与其他静态信息,产出普通的 Java 源文件或字节码,再交由编译器正常编译。样板代码从"人工维护的源码"变为"构建产物",由此产生的变化是:

  • 字段增删只需在源定义处发生一次,生成逻辑按同一规则产出对应实现
  • 字段名与类型不匹配、缺少必要的构造器、实现类命名冲突在编译阶段以普通编译错误的形式报出,位置指向被注解的元素
  • 生成产物是普通类,运行期没有反射与元数据构建成本
对比项 手工维护样板 运行期反射 编译期生成
错误的发现阶段 编码或评审阶段(但依赖人工核对) 运行期首次执行 编译或构建阶段
运行期成本 无 元数据构建与反射调用 与手写代码一致
与源定义的一致性 依赖人工同步 由框架在运行期按名称匹配 由生成规则保证
引入的固定成本 无 无(框架内建) 处理器开发或引入、构建配置、IDE 配置

编译期生成并非消除成本,而是把成本从运行期与排障阶段转移到构建阶段与工具维护上。是否值得,取决于样板规模与上述固定成本的比较。

二、原理

2.1 注解的保留策略与生命周期

注解处理器能否读到某个注解,首先取决于注解的保留策略。@Retention 的三个取值定义了注解在编译与运行两个阶段的存在范围:

保留策略 写入 class 文件 运行期可反射读取 可用的读取时机 典型用途
RetentionPolicy.SOURCE 否 否 编译期读取当前编译单元的元素模型 @Override、生成器的输入注解、仅用于驱动代码生成的注解
RetentionPolicy.CLASS 是 否 编译期(含从类路径读取的已编译类)、字节码工具 默认策略,供字节码分析与运行期增强识别
RetentionPolicy.RUNTIME 是 是 编译期与运行期 运行期框架的配置注解、序列化与校验注解

三类读取方式的差别需要区分清楚:

  1. 编译期读取源码元素。注解处理器读取的是编译器提供的元素模型,当前编译单元中的 SOURCE 级注解在这一阶段仍然可见。处理器可以看到注解的全部元素值,包括类型为 Class 与枚举的元素。
  2. 编译期读取已编译类。处理器从类路径上读取的 .class 文件只能看到 CLASS 与 RUNTIME 级注解,SOURCE 级注解在生成 class 文件时已被丢弃。这决定了一个常见约束:只保留在源码中的注解无法作用于已发布的依赖包。
  3. 运行期反射读取。只有 RUNTIME 级注解会被虚拟机保留并可通过反射读取,SOURCE 与 CLASS 级注解在运行期一律不可见。

选择依据是"该注解由谁读取":仅由编译期工具读取的注解使用 SOURCE,避免污染字节码;需要被字节码工具或运行期增强识别的注解使用 CLASS;需要被运行期框架反射读取的注解使用 RUNTIME。注解的元注解语法与自定义注解的写法见 java 完整手册 注解章节。

2.2 注解处理器的机制

编译轮次与处理循环

注解处理器不是独立进程,而是编译器在一次编译任务中按轮次调用的插件。javac 的处理顺序如下:

  1. 第一次编译由源码文件构成,解析后得到元素模型
  2. 每个轮次中,编译器把所有声明的处理器按顺序调用一次,传入本轮产生的元素集合
  3. 处理器在本轮中生成的新源文件进入下一轮,成为下一轮的输入
  4. 当某个轮次没有任何新文件生成时,处理结束;RoundEnvironment.processingOver() 返回 true 的那一轮是最后一个轮次,此轮不应再生成新文件
  5. 全部轮次结束后,编译器编译所有源码(包括生成的文件),产出 class 文件

由此产生三条实践规则:生成的文件会再次经过处理器,处理器必须能处理自己产出的类型,否则会出现重复生成或无限循环;同一限定名的文件在一个编译任务中只能创建一次;最后一轮是校验与报告整体约束的时机,而不是继续生成的时机。

元素与类型镜象 API

处理器通过 javax.lang.model 包下的接口访问被编译代码的结构,这一套接口称为镜象(mirror)API,访问对象是类型信息本身而非运行时反射对象:

接口或类型 作用 常用方法
ProcessingEnvironment 工具对象的入口 getFiler、getMessager、getElementUtils、getTypeUtils、getOptions
Elements 元素查询 getPackageElement、getTypeElement、getAllMembers、getPackageOf
Types 类型操作 isAssignable、isSameType、isSubtype、erasure、asElement
Filer 创建文件 createSourceFile、createResource、createClassFile
Messager 报告诊断 printMessage(Kind, 消息, 元素),Kind 取 ERROR、WARNING、NOTE
RoundEnvironment 当前轮次的输入 getElementsAnnotatedWith、getRootElements、processingOver

元素(Element)描述程序结构:PackageElement、TypeElement、VariableElement、ExecutableElement 分别对应包、类型、字段或变量、方法或构造器,层级关系通过 getEnclosedElements 与 getEnclosingElement 遍历。类型镜象(TypeMirror)描述类型本身:DeclaredType、PrimitiveType、ArrayType、TypeVariable、WildcardType 对应声明类型、基本类型、数组、类型变量与通配符。判断两个类型是否兼容应当使用 Types.isAssignable 等方法,而不是比较名称字符串,否则泛型、数组与基本类型包装的差异会被忽略。

生成源文件与资源文件

Filer 提供三种产出方式:

方式 产物 是否进入下一轮处理 说明
createSourceFile .java 源文件 是 最常用的方式,生成内容可读、可调试
createResource 资源文件 否 用于生成 META-INF/services、索引文件、元数据文件
createClassFile .class 文件 否 直接写字节码,失去源码可读性,仅在生成量极大或需要精确控制字节码时使用

生成源文件时只需给出类型的限定名,包目录结构由 Filer 计算,处理器不应自行拼接以包名命名的目录路径。生成资源文件时给出相对资源路径,产物在模块输出目录中与源码资源合并。

处理器的注册与发现

处理器通过服务加载机制被发现,标准做法是在处理器所在模块中提供一个服务说明文件:

# 路径:src/main/resources/META-INF/services/javax.annotation.processing.Processor
# 内容为处理器类的全限定名,每行一个
com.example.gen.MapperProcessor

其他注册途径包括:编译命令使用 -processor 显式指定处理器类名,使用 -processorpath 指定处理器所在的类路径,使用 -proc:only 只运行处理而不编译、使用 -proc:none 关闭处理。构建工具侧,Maven 通过 maven-compiler-plugin 的 annotationProcessorPaths 声明处理器坐标,使其存在于处理器路径而不进入运行期类路径:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>com.example</groupId>
                <artifactId>codegen-processor</artifactId>
                <version>${codegen.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

需要留意编译器版本带来的行为变化:较新的 JDK 不再默认从类路径隐式搜索注解处理器,处理器必须通过处理器路径显式声明,JDK 升级后原本"能工作但未显式配置"的工程会在升级时暴露配置缺失。构建配置的组织方式与插件版本管理见 Maven-build 配置实践 与 Maven 常用插件。

增量编译下的行为

编译器单次调用内部没有跨调用的增量能力,是否重新运行处理器由构建工具与 IDE 的增量策略决定:

  • 输出只依赖被处理元素的处理器(每个被注解元素独立产出一个文件)可以增量执行,只对变化的元素重跑
  • 需要汇总多个元素信息的处理器(例如生成全局索引或注册表)在任一相关元素变化时必须整体重跑,否则生成物与输入不一致
  • 构建工具需要知道生成物与哪些源文件相关,处理器应把被处理的元素作为来源参数传给 Filer 的创建方法,供构建工具建立依赖关系
  • Maven 在模块内检测到源文件变化时通常退回整体编译该模块,配置化的增量开关关闭时会失去所有增量收益;IDE 的增量编译则可能只处理变化的文件,出现生成物未更新的情况

2.3 生成代码的形态

生成源文件与生成字节码的差别

形态 可读性 调试体验 适用场景
生成源文件 高,可像普通代码一样查看 堆栈行号对应生成源码,可在生成代码中查看变量 绝大多数场景
生成字节码 无源码,需反汇编或反编译查看 堆栈停在无源码的类中,定位依赖反编译 生成规模极大、需要精确控制字节码
生成资源文件 取决于格式 不涉及调试 服务注册、索引、配置元数据

可见性与调试体验

生成类的可见性应按使用范围选择:仅被同包代码使用时声明为包级可见,避免进入对外 API。生成代码出现在异常堆栈中时,行号指向生成源码文件;如果生成目录被清理而调试器仍持有旧的类,源文件无法显示。生成代码中抛出的异常也会把生成实现的内部结构暴露到使用方的堆栈中,选择生成结构时应避免在生成代码中抛出使用方无法理解的异常类型。

生成物与手写代码的边界

  • 生成目录属于构建产物,不对其手工修改:改动会在下一次构建被覆盖,且覆盖后的差异难以察觉
  • 手写代码不应继承生成类或持有生成类的内部结构,否则生成逻辑调整会造成使用方编译失败
  • 生成代码可以依赖手写代码的对外接口,不应依赖手写代码的内部实现,避免生成器与业务实现相互耦合

2.4 典型用途

用途 生成内容 收益 代价
对象映射 字段复制实现类 无反射开销,字段名与类型不匹配在编译期报错 需为每对模型声明映射接口,含业务规则的转换仍需手写
构造器与访问器 getter、setter、构造器、equals、hashCode 消除样板,规则在全项目一致 生成规则不显式可见,字段增删会改变这两个方法的行为
常量与元数据 常量类、字段名清单、元数据文件 取值集中,改名后可在编译期发现引用 需与源定义保持同步,元数据格式变更影响使用方
接口与实现绑定 工厂、注册表、装配代码 新增实现无需手工登记,依赖关系在编译期可见 装配关系隐式,需通过生成物确认实际绑定
序列化适配 序列化与反序列化实现 避免运行期反射与首次使用的元数据构建 生成物数量随模型增长,字段访问方式需与框架约定一致
校验元数据 约束描述与规则清单 规则集中,注解使用是否合规可在编译期检查 生成物只是元数据,实际校验仍需在运行期执行

各类用途的收益都可以折算为"被消除的人工维护量"与"被前移的错误发现阶段",代价则是生成器的引入成本与长期维护责任。只出现一两次的样板通常不值得专门的生成器。

2.5 错误处理与诊断

处理器报告诊断的方式决定其可用性。诊断通过 Messager 发出并关联到具体元素,编译器会把消息定位到该元素的源码位置,在 IDE 中以标记提示,在命令行输出中带文件名与行号。

在生成阶段可以校验的典型约束:

约束类型 校验内容 违反时的处置
必填元素缺失 注解的必要元素未提供,或引用的类型不存在 报错并指出缺少的元素名
类型不匹配 目标类型缺少可访问的无参构造器、字段类型不可赋值、泛型实参不满足边界 报错并给出满足条件的类型说明
修饰符冲突 目标类型或方法为 final、private,无法生成子类或访问成员 报错并指出冲突的修饰符
注解组合冲突 互斥的注解同时出现,或注解使用在不适用的元素上 报错并指出冲突的注解
命名冲突 生成的类型名与已存在的类型同名 报错并给出建议的命名或配置项

错误信息质量直接影响使用体验,判定的最低要求是:使用者仅凭编译输出即可定位需要修改的位置并知道如何修改,不需要阅读处理器源码。反面情形是处理器内部抛出空指针异常,编译输出中出现指向处理器自身的堆栈,使用者既无法判断触发条件也无法据此修正。处理器应对未预期的输入形态显式检查并给出诊断,而不是任其演化为内部异常。

ERROR 级诊断会阻断编译,WARNING 级只提示。对可以容忍的情形使用 WARNING 并说明原因与后续影响,避免用错误级诊断阻断构建后迫使使用方整体关闭处理。

2.6 与运行期方案的取舍

编译期生成、运行期反射、运行期字节码增强三种方案解决的是不同的约束,对照如下:

维度 编译期生成 运行期反射 运行期字节码增强
绑定确定时机 编译期 启动或首次调用 启动或首次加载
编译复杂度 需要处理器与构建配置 无 无(需要代理或代理程序配置)
启动成本 无额外解析 扫描类路径、构建元数据缓存 生成代理类或转换已加载类
运行性能 与手写代码一致 首次调用开销大,热点调用依赖缓存 接近直接调用,保留少量拦截开销
动态性 绑定在编译期固定,运行期不可替换 可按配置或外部输入决定绑定 可对既有类增强,无需修改源码
错误发现时机 编译或构建阶段 运行期首次执行 启动或首次调用
调试体验 可查看生成源码 堆栈停在框架通用调用点 代理类无源码,且内部调用不经过代理

三者并不互斥,典型组合是在编译期生成确定的骨架,运行期用反射处理无法静态判定的部分。运行期反射的代价来源与适用边界见 反射;运行期织入通过生成代理类实现增强,其代理方式与内部调用失效的约束见 Spring Framework 核心体系,增强手段本身(代理生成、类转换与字节码库)见 Java 字节码与动态代理。选择依据是"绑定关系是否在编译期完全确定":完全确定则编译期生成最经济;由配置或外部输入决定则只能运行期处理;需要在不改动源码的前提下增强既有类则只能运行期织入。

2.7 工程约束

约束 问题 处理方式
生成物入库策略 不入库则 IDE 需要正确配置才能解析生成类型;入库则产生合并冲突与陈旧产物 默认不入库并纳入忽略清单;确需入库时以独立提交执行并标注为生成物
IDE 支持与索引 IDE 未运行处理器时生成类型无法解析,误报大量编译错误 启用注解处理,把生成目录标记为生成源,统一 IDE 与构建使用的 JDK 及处理器版本
构建顺序与依赖方向 处理器与被处理代码相互依赖会导致无法构建 处理器放在独立模块,使用方通过处理器路径引用而非运行期依赖;处理器模块不依赖使用方模块
循环依赖 生成逻辑需要读取上一次生成的产物 处理器的输入是元素模型而非生成物;确需多阶段时拆分为两个处理器或两个构建阶段
版本升级 处理器与编译器、构建工具、JDK 的兼容组合变化 处理器与使用方版本一并升级,生成物差异纳入评审

三、实现

3.1 自研处理器实践

处理器的最小结构

一个处理器需要声明支持的注解类型与源码版本,并在处理轮次中遍历目标元素、产出文件:

@SupportedAnnotationTypes("com.example.gen.Mapper")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
public class MapperProcessor extends AbstractProcessor {

    private static final String SUFFIX = "Impl";

    private Filer filer;
    private Messager messager;
    private Elements elements;
    private Types types;

    @Override
    public synchronized void init(ProcessingEnvironment env) {
        super.init(env);
        this.filer = env.getFiler();
        this.messager = env.getMessager();
        this.elements = env.getElementUtils();
        this.types = env.getTypeUtils();
    }

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        if (roundEnv.processingOver()) {
            // 最后一轮用于整体校验,不再生成文件
            return false;
        }
        for (Element element : roundEnv.getElementsAnnotatedWith(Mapper.class)) {
            if (element.getKind() != ElementKind.INTERFACE) {
                messager.printMessage(Diagnostic.Kind.ERROR, "@Mapper 只能用于接口", element);
                continue;
            }
            TypeElement mapperInterface = (TypeElement) element;
            validate(mapperInterface);
            generate(mapperInterface);
        }
        // 声明该注解已由本处理器处理,避免其他处理器重复处理
        return true;
    }

    private void generate(TypeElement mapperInterface) {
        String packageName = elements.getPackageOf(mapperInterface).getQualifiedName().toString();
        String implName = mapperInterface.getSimpleName() + SUFFIX;
        String qualifiedName = packageName.isEmpty() ? implName : packageName + "." + implName;
        try (Writer writer = filer.createSourceFile(qualifiedName, mapperInterface).openWriter()) {
            writer.write(buildSource(packageName, implName, mapperInterface));
        } catch (IOException e) {
            messager.printMessage(Diagnostic.Kind.ERROR, "生成源文件失败:" + e.getMessage(), mapperInterface);
        }
    }
}

结构要点:

  • 支持的注解类型以全限定名声明,字符串写错会导致处理器始终不被触发且没有任何提示
  • init 中一次性获取工具对象,避免在每轮处理中重复查找
  • process 的返回值表示是否认领这些注解;返回 true 后其他处理器不再收到该注解
  • processingOver 为 true 的轮次用于最终校验,此时生成文件通常是无效的
  • 对不符合预期的元素先报诊断再跳过,而不是直接转型并让异常抛出

生成源文件的写法要点

  • 生成的类型名必须与文件中的 public 类型名一致,限定名交给 Filer 计算,不自行拼接包目录
  • 写入完成后关闭 Writer,否则下一轮读取到空内容
  • 创建源文件时传入来源元素,构建工具据此建立生成物与源文件的依赖关系
  • 同一限定名的文件在一次编译任务中不能创建两次,重复创建会抛出异常,生成逻辑需要保证每个输入元素最多产出一个同名文件
  • 生成的内容必须能被再次解析,处理器自身会在下一轮见到这些类型
  • 诊断统一走 Messager,不使用标准输出,否则消息不进入构建日志且无法定位到源码位置

注册与构建配置

服务说明文件与构建配置的组合方式见 2.2 节。构建侧的配置原则是把处理器的版本在父级构建配置中集中声明,使用方模块只引用而不单独声明版本,配置的组织方式见 Maven-build 配置实践。

3.2 生成内容设计

命名与包组织

设计项 做法 原因
类名后缀 实现类以固定后缀结尾,如 XxxImpl、XxxMapperImpl 与手写类区分,便于检索与排除规则匹配
包位置 与所实现接口同包的 impl 子包,或独立的生成包 同包可访问包级成员;独立包便于统一排除
可见性 仅被同包使用时声明为包级可见 避免生成物进入对外 API
生成目录 使用构建工具约定的生成源目录 便于 IDE 识别与统一清理

幂等生成

生成逻辑必须保证同一输入产生逐字节一致的输出,否则构建缓存永远无法命中,产物比较也无法用于评审。破坏幂等的常见来源:

  • 写入当前时间、随机标识、主机名、环境变量或文件系统信息
  • 遍历 HashMap、HashSet 等无序容器的结果,元素顺序随运行而变化
  • 依赖外部服务或网络获取信息

处理方式是使用有序容器或在输出前排序,把需要的外部信息通过处理器选项(-A 选项,读取自 ProcessingEnvironment.getOptions)显式传入并纳入构建配置。

避免与手写物冲突

生成前通过元素模型查找目标限定名是否已被占用(Elements.getTypeElement),存在同名类型时报告错误并提示命名调整,而不是依赖文件系统覆盖。生成产物与手写产物同名或同包冲突时,运行期加载到哪一个取决于编译顺序,属于不可控状态。

生成物头部的来源说明

生成文件应在头部写明来源与禁止手工修改:

// 由 com.example.gen.MapperProcessor 生成,请勿手工修改。
// 源类型:com.example.order.OrderEntity
// 生成规则版本:codegen 1.4.0
package com.example.order.impl;

来源说明的作用是在排障时能够反向定位到生成器与生成规则版本,避免把生成代码当作手写代码阅读与修改。

3.3 校验型处理器实践

除了生成代码,处理器也可以在编译期执行约束校验,把架构规则前移到编译阶段。适合放入处理器的规则具备两个特征:以注解为触发点,且判定依据完全来自元素模型。

@SupportedAnnotationTypes("com.example.arch.TransactionalRequired")
@SupportedSourceVersion(SourceVersion.RELEASE_17)
public class TransactionRuleProcessor extends AbstractProcessor {

    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        Messager messager = processingEnv.getMessager();
        for (Element element : roundEnv.getElementsAnnotatedWith(TransactionalRequired.class)) {
            Element owner = element.getEnclosingElement();
            String methodName = element.getSimpleName().toString();
            if (element.getModifiers().contains(Modifier.PUBLIC) == false) {
                messager.printMessage(Diagnostic.Kind.ERROR,
                        "被 @TransactionalRequired 标记的方法必须是 public:" + methodName, element);
            }
            if (owner.getKind() != ElementKind.CLASS) {
                messager.printMessage(Diagnostic.Kind.ERROR,
                        "@TransactionalRequired 只能用于类中声明的实例方法", element);
                continue;
            }
            String packageName = processingEnv.getElementUtils()
                    .getPackageOf(owner).getQualifiedName().toString();
            if (packageName.contains(".repository")) {
                messager.printMessage(Diagnostic.Kind.WARNING,
                        "数据访问层方法不应声明事务:" + owner.getSimpleName() + "#" + methodName, element);
            }
        }
        return false;
    }
}

校验型处理器的实践要点:

  • 规则以元素模型可判定的形式表述。需要运行期数据才能判断的规则(实际调用路径、并发时序、外部依赖可用性)不应放入处理器
  • 与静态分析规则分工:以注解为触发点、需要在被注解元素粒度报告的规则适合处理器;跨文件的依赖方向与循环依赖更适合以架构测试或静态分析规则表达,二者的能力边界见 Java 代码质量与静态分析
  • 报错信息给出修正建议,而不是只陈述违规
  • 为规则提供豁免手段(专用的豁免注解或处理器选项),豁免需注明原因与失效条件,避免使用方通过整体关闭处理器来绕过
  • 规则自身的误报需要在历史代码上试运行统计后再启用,与静态分析规则的引入方式一致

3.4 常见工具机制

Lombok 的编译期介入方式与风险

Lombok 不使用"生成新源文件再编译"的路径,而是通过编译器的内部实现接口访问并修改语法树,在解析完成之后直接向类型中追加成员。因此它在编译产物中产生的成员与手写成员没有区别,也不产生额外的源文件。这一方式的收益与代价同时来自同一个事实——它依赖非公开的编译器内部行为:

风险项 表现 应对
工具链耦合 使用非公开 API,JDK 或编译器实现升级后可能编译失败 与 JDK 版本同步升级,纳入版本管理,升级前在分支验证
IDE 插件依赖 IDE 使用自己的编译器,需要专用插件解析生成成员,插件缺失或版本不匹配时表现为 IDE 报错而命令行编译通过 统一 IDE 插件版本与 Lombok 版本,统一团队的 IDE 配置
调试与断点 生成成员无对应源文件,断点落在生成方法上无法单步 通过重写方法或显式声明所需方法替代生成
隐性语义 equals 与 hashCode 的生成规则不可见,字段增删会改变行为;构造函数组合不显式 用于序列化的类型显式声明所需构造器
与生成器协同 与其他注解处理器同时使用时存在处理顺序问题 按工具文档引入协同配置模块,避免依赖默认顺序

Lombok 与映射工具在项目中的取舍要点见 Java 日志与常用类库规范 2.7 节,本节说明的是其介入机制差异导致的工程影响。

映射工具的两条实现路径

实现路径 时机 错误发现 运行性能 适用
编译期生成实现类 构建阶段生成映射实现 字段名与类型不匹配在编译期报错 与手写代码一致 模型结构稳定、调用频次高
运行期反射复制 每次调用时逐字段读写 运行期首次执行才暴露 有反射开销,依赖元数据缓存 映射关系统一由配置决定、类型动态

同名的"映射工具"可能属于不同路径,选型时需要明确其实现机制而非仅看 API 形式,因为二者在启动时间、热点性能与错误发现阶段上的差异是结构性的。

JSON 与配置绑定的生成方式

  • 运行期方式:序列化框架在首次使用时反射读取注解与字段,构建序列化描述信息并缓存,之后复用
  • 编译期方式:注解处理器或独立编译器为模型生成序列化与反序列化实现,运行期不依赖反射,代价是生成物随模型数量增长
  • 配置绑定:部分框架在编译期生成配置元数据文件供 IDE 补全与校验,运行期的绑定过程仍可能使用反射,两者是不同环节的产物

模型映射的边界(实体与视图对象的职责划分、字段类型与数据库类型的对应、逻辑删除与时间戳字段的处理)见 Java 持久层 3.2 节,本节不重复。

3.5 构建与流水线配合

注解处理在构建阶段中的位置

注解处理由编译器在 compile 阶段内部执行,不是一个独立的插件目标;generate-sources 阶段用于其他形式的代码生成插件(由外部程序按模式定义产出源码)。两者产出的内容都属于生成源,需要正确声明为源目录才能参与编译。插件绑定阶段与生成源码的配置方式见 Maven 生命周期与插件绑定。

增量编译与清理策略

生成目录与编译输出目录的状态必须一致:只删除生成源码而保留旧的 class 文件时,编译期可能因旧类型仍然存在而不报错,运行期加载到与当前源码不符的实现,表现为行为与代码不一致且难以定位。可行策略有两种:

  1. 每次构建前执行完整清理(清理生成目录与输出目录),代价是构建时间上升
  2. 启用增量构建但确保生成目录与输出目录同进同退,并在处理器逻辑变更后强制执行一次完整清理

与格式化、静态分析的执行顺序

格式化与静态检查应作用于手写代码,生成目录从格式化、静态分析与覆盖率统计的范围中排除。顺序上,注解处理先于上述检查执行,否则生成物尚未产生,排除规则也无从生效。排除范围与检查规则的组织方式见 Java 代码质量与静态分析 3.1 节。

构建缓存命中

生成内容不确定会使构建缓存无法命中,表现为每次构建都重新编译且缓存收益为零。判定方式是连续执行两次构建并比较生成目录的内容:内容不一致即存在不确定来源。除 3.2 节列出的时间与无序遍历外,处理器读取构建环境之外的状态(文件系统、网络、当前用户)同样会破坏可复现性。

依赖与版本组织

处理器属于构建期依赖,版本在父级构建配置中集中声明,使用方模块通过处理器路径引用,避免处理器及其传递依赖进入运行期类路径。依赖版本统一与冲突排查的方式见 Maven 依赖管理机制。构建环境使用的 JDK 与处理器版本需与本地一致,否则出现本地通过而流水线失败。

3.6 常见问题与排查

现象 常见原因 定位方式 处置
处理器未被触发 服务说明文件缺失或路径错误;处理器未加入处理器路径;支持的注解类型字符串与实际注解不一致;注解保留策略与读取方式不匹配 以详细构建日志运行编译,查看处理器的加载与调用记录;确认是否使用处理器路径而非普通依赖 补齐服务说明文件与处理器路径配置;核对注解全限定名;确认注解保留策略满足读取要求
生成物未参与编译 生成目录未加入源目录;生成位置与构建配置不一致;多模块中生成模块未被使用方依赖 检查构建输出中生成目录是否存在目标文件;查看工程配置的源目录清单 正确声明生成源目录;不自定义输出位置;模块之间补充依赖
IDE 与命令行结果不一致 IDE 未启用注解处理;IDE 与构建使用不同 JDK 或处理器版本;IDE 未把生成目录标记为生成源;IDE 未委托构建工具编译 比较 IDE 编译输出与命令行构建输出;核对 IDE 编译器配置的 JDK 与处理器 启用注解处理并统一版本;标记生成源;改为委托构建工具执行编译
增量编译残留 删除注解或重命名类型后旧生成类未清理;生成目录未纳入清理范围 在生成目录或输出目录中发现已无对应源元素的类 清理生成目录与输出目录后执行完整构建;在增量方案中声明处理器的输入与输出关系
生成代码触发格式与静态分析告警 生成目录被纳入格式化与检查范围 告警集中在生成目录或生成包名下 从格式化、静态分析、覆盖率统计范围中排除生成目录
Lombok 与新版 JDK 或工具链不兼容 Lombok 依赖编译器内部 API;IDE 插件版本滞后于 Lombok 编译错误指向 Lombok 内部类;出现 IDE 报错而命令行通过 同步升级 Lombok、IDE 插件与 JDK;确认三者兼容组合;无法满足时回退 JDK 或改用标准处理器实现
处理器自身抛出异常 处理器对未预期的元素形态未做检查 编译输出中的堆栈指向处理器类 补全输入形态检查,对不满足条件的元素以诊断代替异常
生成物与手写类冲突 生成逻辑的命名约定与手写命名重合 编译期出现重复类或行为与手写实现不符 调整命名约定或包位置;在生成前检查目标类型是否已存在并报错

3.7 规范建议

何时值得自研生成器

判定项 值得自研 不值得自研
重复程度 同类样板在项目内高频重复,且随字段或实现数量线性增长 仅出现少量几次
规则可判定性 规则完全由元素模型决定,可在编译期判定 规则依赖运行期信息或外部状态
维护能力 有明确责任人,能跟进 JDK 与构建工具版本演进 无人持续维护
既有方案 通用场景无成熟工具覆盖,约束具有领域特殊性 通用工具已覆盖,自研只是重复实现

维护责任与文档要求

  • 生成器指定责任人,处理器的版本与使用方版本一并升级,升级需回归验证生成物
  • 生成物的命名与输出目录约定写入文档,纳入新成员的环境配置说明
  • 诊断信息与生成物格式的变更视为对外契约变更,需评审并评估对使用方的影响
  • 为处理器建立回归验证:对固定的输入元素断言生成的输出内容,防止规则被误改

禁止事项

禁止项 原因
手工修改生成物 下一次构建即被覆盖,改动丢失且差异难以察觉
生成逻辑依赖运行环境 构建不可复现,缓存失效,不同环境产出不一致
在生成阶段实现只能运行期判定的规则 编译器无法提供所需信息,只能以假设代替判断,错误延后暴露
生成物与手写类型同名或同包冲突 加载到哪一个取决于编译顺序,行为不可控
把业务规则写入生成器而不记录 规则隐式存在,变更影响无法评估
生成器依赖具体 JDK 版本的内部实现 升级即失效,Lombok 的工具链耦合即为该类问题

高危:在存量工程中引入编译期代码生成器并使其作用于既有代码(为已有模型批量添加映射接口并生成实现、或替换既有的运行期映射实现)。影响:生成实现与既有实现在空值处理、字段访问方式、默认值、时间与数值转换上的差异只在特定数据下暴露,且替换后使用方源码不变、差异不体现在变更记录中;引入同时需要修改构建配置(处理器路径、生成源目录)与 IDE 配置,任一环节缺失表现为编译失败或生成物未生效;处理器与项目 JDK、构建工具版本不匹配时构建整体失败,故障点在编译期,影响所有模块。要求:先在一个模块或一组新增模型上验证,确认行为与既有实现一致后再扩大范围;以对照测试或契约测试覆盖新旧实现的差异,重点覆盖空值、时间与数值转换;处理器的版本在父级构建配置中集中声明,避免各模块各自声明;保留旧实现与回退路径直到差异验证完成。回滚方式是移除处理器依赖与生成源目录配置,恢复手写实现类;若已替换既有实现,按模块回退至保留的实现版本。

高危:清理生成物(删除生成源目录或输出目录中的生成类)。影响:生成源码与编译输出必须一致清理,只删除生成源码而保留旧 class 时,编译期可能因旧类型仍存在而不报错,运行期加载到与当前源码不符的实现,表现为行为与代码不一致且难以定位;在多模块构建中只清理部分模块会破坏增量状态,需要整体重建;若生成目录曾被纳入版本控制,清理会同时产生大量删除记录并与既存分支冲突。要求:清理范围同时包含生成源目录与编译输出目录;清理在无其他构建或调试会话进行时执行;清理后执行一次完整构建并确认生成物重新产生且与输入一致;确认生成目录未被纳入版本控制。回滚方式是重新执行完整构建以重新生成(生成逻辑无副作用时结果等价);若生成目录中曾存在手工修改的内容,需要从版本控制或备份恢复。

高危:升级注解处理工具或其版本(包括 Lombok、映射工具处理器、构建插件中声明的处理器依赖)。影响:处理器输出变化会改变生成代码,进而改变运行行为(equals 与 hashCode 规则、映射的空值与类型转换、构造器选择),而使用方源码没有对应变更记录,评审中容易遗漏;升级后与 JDK、IDE 插件版本不匹配时出现本地通过而流水线失败,或 IDE 报错而命令行通过;部分升级要求调整构建配置(坐标或选项名称变化),配置遗漏时处理器静默不生效且无提示。要求:升级前留存当前生成物作为对比基线;在同一批次内同步升级处理器、构建插件、IDE 插件与 JDK 到已验证的兼容组合;升级后在完整构建与测试上先行验证,重点比较生成物差异与涉及序列化、映射的行为;把升级前后的生成物差异纳入变更评审。回滚方式是按版本记录回退处理器与构建配置,清理生成目录后重新完整构建;涉及生成物行为变化且已影响已发布产物时,按发布回滚流程处理,相关约束见 linux: 变更与发布管理。

四、总结

  1. 编译期生成解决的是样板代码的维护成本与运行期反射的错误延后问题,其代价从运行期转移到构建阶段与工具维护,是否引入取决于"重复次数乘以变更频率"与固定成本的比较
  2. 注解能否被读取由保留策略决定:SOURCE 只在当前编译单元的元素模型中可见,CLASS 可被编译期从类路径读取与字节码工具读取,RUNTIME 才可被反射读取,运行期不可见的注解无法支撑运行期框架
  3. 注解处理器是编译器按轮次调用的插件,生成的文件进入下一轮,无新文件产生的轮次结束后由编译器统一编译;处理器必须能处理自己产出的类型,同名文件在同一编译任务中只能创建一次
  4. 元素与类型镜象 API 描述的是编译期类型信息而非运行期反射对象,类型兼容判断应使用 Types 提供的方法而非名称比较;诊断通过 Messager 关联到元素,质量要求是使用者仅凭编译输出即可完成修正
  5. 生成源文件保留可读性与调试体验,生成字节码失去源码对应关系;生成物属于构建产物,不可手工修改,手写代码也不应继承生成类或依赖其内部结构
  6. 典型用途集中在对象映射、构造器与访问器、常量与元数据、接口与实现绑定、序列化适配与校验元数据,收益是消除人工同步与提前错误发现,代价是生成器的引入成本与长期维护责任
  7. 编译期生成、运行期反射与运行期字节码增强的差异在于绑定确定时机与动态性:绑定关系在编译期完全确定时编译期生成最经济,由配置或外部输入决定时只能运行期处理,需要增强不可修改的既有类时只能运行期织入
  8. 生成逻辑必须幂等且不依赖运行环境,否则构建缓存失效且产物无法用于差异评审;生成前应检查命名冲突,生成物头部应写明来源与生成规则版本
  9. 校验型处理器把命名规范、依赖方向与注解使用约束前移到编译阶段,适合以注解为触发点且完全由元素模型判定的规则,跨文件的结构约束仍由静态分析与架构测试承担
  10. Lombok 通过编译器内部 API 修改语法树而非生成源文件,收益是消除样板,代价是与编译器实现、JDK 与 IDE 插件的耦合,升级时需同步验证
  11. 注解处理位于 compile 阶段,生成目录需要正确声明为源目录;生成目录与编译输出必须一致清理,格式化、静态分析与覆盖率统计需排除生成目录
  12. 处理器未被触发、生成物未参与编译、IDE 与命令行不一致、增量残留与生成物引起的检查告警是高频问题,定位时先确认处理器的加载与生成目录的存在性,再区分配置问题与工具版本问题
  13. 自研生成器适用于高频重复且规则可静态判定的场景,需要明确责任人、文档与回归验证;禁止手工修改生成物、生成逻辑依赖运行环境、以及依赖具体 JDK 版本的内部实现
  14. 引入生成器到存量工程、清理生成物、升级注解处理工具三类操作属于高风险变更,应先在局部验证、保留可回退的基线,并在清理后执行完整构建确认产物一致