必须用apt在编译期强制校验注解属性——通过@retention(retentionpolicy.source)声明注解,于process()中遍历标注元素、提取annotationmirror/value并校验数值范围、字符串非空、枚举合法性、字段类型等,错误时调用messager报错中断编译。

自定义注解属性的强约束检查,不能靠运行时反射或手动校验实现——那会漏掉错误、增加开销、无法阻止非法代码进入生产环境。真正“强制”的方式,是让检查发生在编译期,由APT(Annotation Processing Tool)在javac阶段就拦截不合法的用法,并直接报错中断编译。
为什么必须用APT做编译期强制校验
运行时注解(@Retention(RetentionPolicy.RUNTIME))只能在程序启动后通过反射读取,此时错误已打包进APK/JAR,用户运行才暴露;而编译期校验要求注解本身声明为 @Retention(RetentionPolicy.SOURCE),且校验逻辑嵌入处理器中。只要开发者写了不合规的属性值(如负数长度、空字符串必填字段、类型不匹配等),APT就会在IDE里实时标红、命令行编译直接失败。
关键:在process()中解析并校验注解属性值
注解处理器的 process() 方法不仅是生成代码的入口,更是执行强约束检查的唯一可控时机。你需要:
- 遍历 roundEnv.getElementsAnnotatedWith(YourAnnotation.class) 获取所有被标注的元素
- 对每个元素调用 element.getAnnotationMirrors() 或使用 AnnotationMirror/AnnotationValue API 提取实际传入的属性值(注意:不能用
element.getAnnotation(),那是运行时API,APT中不可用) - 逐项检查:比如
@MyLimit(maxLength = -5)就应触发 processingEnv.getMessager().printMessage(Diagnostic.Kind.ERROR, "maxLength must be >= 0", element) - 校验失败不生成代码,但必须返回 false 或确保错误被报告,否则编译可能静默通过
典型强约束场景与检查写法
以下检查都应在APT处理器内完成,而非留到运行时:
-
数值越界:如
minLength() > maxLength(),或minNum() > maxNum(),直接报错 -
字符串合法性:如
description()为空但业务要求非空,用value.getValue().toString().trim().isEmpty()判断 -
枚举/常量匹配:若注解含
@interface MyRule { Level level() default Level.HIGH; },需校验传入的Level是否为已知枚举实例(通过value.toString()解析后比对) -
字段类型约束:例如注解只允许标注
String字段,但用户加在int上 —— 用element.asType().toString().equals("java.lang.String")检查
配合注解声明增强语义约束
单靠处理器还不够,注解自身的元信息也要配合:
- 使用 @Target({ElementType.FIELD, ElementType.PARAMETER}) 明确限定可用位置,超出即编译报错
- 用 @Repeatable(MyAnnotations.class) 控制是否允许多次使用
- 避免定义冗余或矛盾属性(如同时提供
required=true和defaultValue=""),这类设计缺陷应在文档和处理器中一并拦截










