1. 项目概述为什么我们需要自定义注解在Java开发中尤其是面对Spring Boot这类现代框架时注解Annotation几乎无处不在。从Controller、Autowired到Transactional它们像魔法标签一样简化了配置声明了意图。但很多时候框架提供的标准注解并不能完全满足我们千奇百怪的业务需求。比如你想优雅地实现一个日志切面只记录特定方法的入参和出参或者你需要一个统一的参数校验器对手机号、身份证、银行卡号进行不同规则的脱敏处理再或者你想在项目启动时自动扫描并注册某些特定接口的实现类。这些场景就是自定义注解大显身手的地方。简单来说自定义注解就是你自己定义的、带有特定语义的“标签”。你可以把它贴在类、方法、字段或参数上然后通过反射Reflection机制在运行时读取这些标签并执行相应的逻辑。这本质上是一种“声明式编程”的实践你声明要做什么通过注解而具体的执行逻辑通过处理器被分离出来使得代码更加清晰、解耦也更容易复用。理解了自定义注解你不仅能更好地使用Spring等框架还能自己设计出更灵活、更优雅的架构这也是面试中常被问到的“八股文”背后的实际价值。2. 核心原理与设计思路拆解要玩转自定义注解必须吃透两个核心支柱注解本身的定义与反射机制。它们是“声明”与“执行”的关系。2.1 注解的本质与元注解Java中的注解本质上是一个接口它继承自java.lang.annotation.Annotation。我们使用interface关键字来定义它。但光定义还不够我们需要用“元注解”来修饰它以指定这个自定义注解的“行为能力”。元注解是JDK内置的、用于修饰其他注解的注解主要有以下五个Target指定注解可以应用在哪些程序元素上。这是最重要的元注解之一决定了你的注解能贴在哪儿。ElementType.TYPE类、接口、枚举ElementType.FIELD字段包括枚举常量ElementType.METHOD方法ElementType.PARAMETER方法参数ElementType.CONSTRUCTOR构造器ElementType.LOCAL_VARIABLE局部变量ElementType.ANNOTATION_TYPE注解类型本身ElementType.PACKAGE包ElementType.TYPE_PARAMETER类型参数JDK 1.8ElementType.TYPE_USE类型使用JDK 1.8Retention指定注解的生命周期即注解信息保留到哪个阶段。RetentionPolicy.SOURCE仅存在于源代码中编译时被丢弃。例如Override、SuppressWarnings仅供编译器使用。RetentionPolicy.CLASS保存在class文件中但运行时JVM不会加载。这是默认值但实际开发中很少单独使用。RetentionPolicy.RUNTIME永久保存运行时可以通过反射读取。这是我们实现自定义功能必须使用的策略。Documented表明这个注解应该被Javadoc工具记录。如果你希望自定义注解出现在API文档中就加上它。Inherited表明该注解具有继承性。如果父类使用了被Inherited修饰的注解那么子类会自动继承该注解前提是子类没有被其他注解覆盖。这个在定义类级别的注解时可能会用到。RepeatableJDK 1.8表明该注解可以在同一个元素上重复使用。设计思路在定义注解前先想清楚这个注解是给谁用的类、方法、字段需要在运行时获取吗如果需要Retention(RetentionPolicy.RUNTIME)和相应的Target就是必选项。2.2 反射机制注解的“灵魂读取器”定义了注解就像贴好了标签。反射Reflection则是那个在运行时检查这些标签并做出反应的“读取器”。Java的反射API提供了丰富的接口来访问注解信息Class.getAnnotation(ClassT)/getAnnotations()获取类上的注解。Method.getAnnotation(ClassT)/getAnnotations()获取方法上的注解。Field.getAnnotation(ClassT)/getAnnotations()获取字段上的注解。Parameter.getAnnotation(ClassT)/getAnnotations()JDK 1.8获取参数上的注解。AnnotatedElement.isAnnotationPresent(Class)判断某个元素上是否存在指定注解。核心逻辑链我们通常会在一个“处理器”Handler或“切面”Aspect中通过反射获取被特定注解标记的元素然后执行我们预设的业务逻辑。例如一个Log注解的处理器会在方法执行前后通过反射获取该方法上的Log注解并根据注解的属性决定记录哪些信息。2.3 注解的属性定义与默认值注解可以包含属性看起来像方法用来传递配置信息。属性类型可以是基本类型、String、Class、枚举、注解以及这些类型的数组。public interface MyAnnotation { // 定义一个属性类型为String默认值为空字符串 String value() default ; // 定义一个int类型属性没有默认值使用时必须指定 int count(); // 定义一个Class类型属性 Class? clazz() default Object.class; // 定义一个枚举类型属性 Status status() default Status.ENABLED; // 定义一个注解类型属性 Deprecated deprecated() default Deprecated; // 定义一个数组属性 String[] tags() default {}; } enum Status { ENABLED, DISABLED }使用技巧value()是一个特殊属性。如果注解只有一个属性且名为value在使用时可以省略属性名直接写值如MyAnnotation(“test”)。定义合理的默认值default …可以大大提升注解的易用性。3. 实战从零构建一个自定义注解理论讲完了我们来动手实现一个完整的例子。场景是我们需要一个SensitiveData注解用来标记那些包含敏感信息如手机号、身份证号、银行卡号的字段或方法返回值并指定脱敏规则。然后我们结合Spring Boot在JSON序列化使用Jackson时自动对标记的字段进行脱敏。3.1 第一步定义脱敏规则枚举和注解首先定义我们支持的脱敏类型。// SensitiveType.java public enum SensitiveType { /** 中文名 */ CHINESE_NAME, /** 身份证号 */ ID_CARD, /** 手机号 */ MOBILE_PHONE, /** 银行卡号 */ BANK_CARD, /** 邮箱 */ EMAIL; }然后定义我们的核心注解Sensitive。我们希望它能用在字段上也能用在方法上用于标记返回对象中的敏感字段并且必须在运行时可用。// Sensitive.java import java.lang.annotation.*; Target({ElementType.FIELD, ElementType.METHOD}) // 可以标注在字段和方法上 Retention(RetentionPolicy.RUNTIME) // 运行时保留必须 Documented // 可选加入文档 public interface Sensitive { /** * 敏感信息类型 */ SensitiveType value(); /** * 自定义脱敏正则表达式可选如果指定则优先使用正则进行脱敏 */ String pattern() default ; /** * 自定义替换字符默认为“*” */ char maskChar() default *; }3.2 第二步实现脱敏工具类这个工具类将根据Sensitive注解的配置执行具体的脱敏逻辑。// SensitiveUtil.java import org.apache.commons.lang3.StringUtils; import java.util.regex.Pattern; public class SensitiveUtil { /** * 根据注解对原始字符串进行脱敏 * param source 原始字符串 * param sensitive 注解信息 * return 脱敏后的字符串 */ public static String desensitize(String source, Sensitive sensitive) { if (StringUtils.isBlank(source)) { return source; } // 1. 优先使用自定义正则表达式 if (StringUtils.isNotBlank(sensitive.pattern())) { return source.replaceAll(sensitive.pattern(), String.valueOf(sensitive.maskChar())); } // 2. 根据内置规则脱敏 SensitiveType type sensitive.value(); switch (type) { case CHINESE_NAME: return desensitizeChineseName(source, sensitive.maskChar()); case ID_CARD: return desensitizeIdCard(source, sensitive.maskChar()); case MOBILE_PHONE: return desensitizeMobilePhone(source, sensitive.maskChar()); case BANK_CARD: return desensitizeBankCard(source, sensitive.maskChar()); case EMAIL: return desensitizeEmail(source, sensitive.maskChar()); default: // 未知类型默认隐藏中间部分 return defaultDesensitize(source, sensitive.maskChar()); } } private static String desensitizeChineseName(String name, char maskChar) { if (name.length() 1) return name; if (name.length() 2) return name.charAt(0) String.valueOf(maskChar); // 张三丰 - 张*丰 return name.charAt(0) StringUtils.repeat(maskChar, name.length() - 2) name.charAt(name.length() - 1); } private static String desensitizeIdCard(String idCard, char maskChar) { // 保留前6位和后4位例如110101********1234 if (idCard.length() 10) return idCard; return idCard.substring(0, 6) StringUtils.repeat(maskChar, idCard.length() - 10) idCard.substring(idCard.length() - 4); } private static String desensitizeMobilePhone(String mobile, char maskChar) { // 保留前3位和后4位例如138****8888 if (mobile.length() ! 11) return mobile; return mobile.substring(0, 3) StringUtils.repeat(maskChar, 4) mobile.substring(7); } private static String desensitizeBankCard(String bankCard, char maskChar) { // 保留前6位和后4位 if (bankCard.length() 10) return bankCard; return bankCard.substring(0, 6) StringUtils.repeat(maskChar, bankCard.length() - 10) bankCard.substring(bankCard.length() - 4); } private static String desensitizeEmail(String email, char maskChar) { int atIndex email.indexOf(); if (atIndex 1) return email; // 隐藏符号前的第一个字符之后的部分例如z***example.com return email.charAt(0) StringUtils.repeat(maskChar, atIndex - 1) email.substring(atIndex); } private static String defaultDesensitize(String str, char maskChar) { if (str.length() 2) return str; int maskLength str.length() / 2; int start (str.length() - maskLength) / 2; char[] chars str.toCharArray(); for (int i start; i start maskLength; i) { chars[i] maskChar; } return new String(chars); } }注意这里使用了Apache Commons Lang3的StringUtils工具类需要在项目中引入依赖Maven:org.apache.commons:commons-lang3。你也可以用JDK原生方法实现但StringUtils.repeat等工具方法更简洁。3.3 第三步集成Jackson实现自动序列化脱敏这是最关键的一步。我们需要定制Jackson的序列化行为当它序列化一个对象时如果发现某个字段有Sensitive注解就调用我们的工具类进行脱敏。实现一个JsonSerializer// SensitiveSerializer.java import com.fasterxml.jackson.core.JsonGenerator; import com.fasterxml.jackson.databind.BeanProperty; import com.fasterxml.jackson.databind.JsonMappingException; import com.fasterxml.jackson.databind.JsonSerializer; import com.fasterxml.jackson.databind.SerializerProvider; import com.fasterxml.jackson.databind.ser.ContextualSerializer; import java.io.IOException; public class SensitiveSerializer extends JsonSerializerString implements ContextualSerializer { private Sensitive sensitive; public SensitiveSerializer() { } public SensitiveSerializer(Sensitive sensitive) { this.sensitive sensitive; } Override public void serialize(String value, JsonGenerator gen, SerializerProvider serializers) throws IOException { if (sensitive ! null value ! null) { // 调用脱敏工具 String desensitizedValue SensitiveUtil.desensitize(value, sensitive); gen.writeString(desensitizedValue); } else { gen.writeString(value); } } Override public JsonSerializer? createContextual(SerializerProvider prov, BeanProperty property) throws JsonMappingException { // 关键从字段上获取Sensitive注解 if (property ! null) { Sensitive ann property.getAnnotation(Sensitive.class); if (ann ! null) { return new SensitiveSerializer(ann); } } return this; } }现在在实体类的字段上使用JsonSerialize注解指定使用我们自定义的序列化器。// UserDTO.java import com.fasterxml.jackson.databind.annotation.JsonSerialize; public class UserDTO { private String username; Sensitive(SensitiveType.CHINESE_NAME) JsonSerialize(using SensitiveSerializer.class) private String realName; Sensitive(SensitiveType.ID_CARD) JsonSerialize(using SensitiveSerializer.class) private String idCard; Sensitive(SensitiveType.MOBILE_PHONE) JsonSerialize(using SensitiveSerializer.class) private String mobile; Sensitive(value SensitiveType.BANK_CARD, maskChar #) // 自定义替换符 JsonSerialize(using SensitiveSerializer.class) private String bankCard; // 省略构造函数、getter、setter }3.4 第四步在Spring Boot中测试创建一个简单的Spring Boot控制器进行测试。// TestController.java import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/api/user) public class TestController { GetMapping public UserDTO getUser() { UserDTO user new UserDTO(); user.setUsername(zhangsan); user.setRealName(张三丰); user.setIdCard(110101199001011234); user.setMobile(13800138000); user.setBankCard(6228480018888888888); return user; } }启动应用访问GET /api/user你将得到类似以下的JSON响应{ username: zhangsan, realName: 张*丰, idCard: 110101********1234, mobile: 138****8000, bankCard: 622848######8888 }可以看到敏感信息已经按照我们定义的规则自动脱敏了。这个方法的好处是非侵入性你的业务代码UserDTO只需要声明哪些字段是敏感的脱敏逻辑完全由注解和序列化器在底层处理符合单一职责原则。4. 高级应用与模式探索掌握了基础用法后我们可以探索更高级、更工程化的应用模式。4.1 结合AOP实现方法级日志与鉴权Sensitive主要用于字段脱敏。对于方法级别的通用逻辑如日志记录、性能监控、权限检查等Spring AOP是绝配。我们可以定义一个注解然后通过AOP切面来统一处理。定义日志注解// OperateLog.java Target(ElementType.METHOD) Retention(RetentionPolicy.RUNTIME) Documented public interface OperateLog { String module() default ; // 操作模块 String type() default ; // 操作类型增删改查 String desc() default ; // 操作描述 }实现AOP切面// OperateLogAspect.java import org.aspectj.lang.ProceedingJoinPoint; import org.aspectj.lang.annotation.Around; import org.aspectj.lang.annotation.Aspect; import org.aspectj.lang.reflect.MethodSignature; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Component; import java.lang.reflect.Method; Aspect Component public class OperateLogAspect { private static final Logger log LoggerFactory.getLogger(OperateLogAspect.class); Around(annotation(com.yourpackage.annotation.OperateLog)) public Object around(ProceedingJoinPoint joinPoint) throws Throwable { MethodSignature signature (MethodSignature) joinPoint.getSignature(); Method method signature.getMethod(); OperateLog operateLog method.getAnnotation(OperateLog.class); long startTime System.currentTimeMillis(); String methodName method.getDeclaringClass().getSimpleName() . method.getName(); log.info([操作日志-开始] 模块: {}, 类型: {}, 方法: {}, 描述: {}, operateLog.module(), operateLog.type(), methodName, operateLog.desc()); Object result; try { // 执行原方法 result joinPoint.proceed(); long costTime System.currentTimeMillis() - startTime; log.info([操作日志-成功] 方法: {}, 耗时: {}ms, methodName, costTime); } catch (Exception e) { long costTime System.currentTimeMillis() - startTime; log.error([操作日志-异常] 方法: {}, 耗时: {}ms, 异常: {}, methodName, costTime, e.getMessage(), e); throw e; } return result; } }在Service方法上使用Service public class UserService { OperateLog(module 用户管理, type 查询, desc 根据ID查询用户) public UserDTO getUserById(Long id) { // ... 业务逻辑 } }这样所有被OperateLog注解的方法其调用情况都会被自动记录无需在每个方法里写日志代码。4.2 注解处理器APT在编译时生成代码以上都是在运行时Runtime通过反射处理注解。另一种更高效的方式是在编译时Compile Time处理注解即使用注解处理器Annotation Processing Tool, APT。这常用于生成代码如Lombok的Data、Getter或者MapStruct的映射器接口。核心思路你定义一个注解然后编写一个继承自AbstractProcessor的处理器。在编译阶段编译器会调用你的处理器你可以获取到所有被该注解标记的元素然后生成新的.java源文件。这些生成的代码会和手写代码一起被编译。优势零运行时开销。因为所有逻辑在编译时已生成为具体代码运行时无需反射性能更高。缺点实现相对复杂需要对Java编译模型有较深理解且生成的代码可能会增加项目复杂度。对于大多数业务场景运行时反射结合Spring AOP已经足够高效和灵活。APT更适合框架级开发或需要极致性能的代码生成场景。4.3 解决注解继承与组合问题有时我们会遇到注解继承的问题。默认情况下注解是不会被继承的。即使父类的方法有RequestMapping子类重写该方法后注解也不会自动带上。Spring提供了AliasFor注解来解决元注解中属性的别名问题并支持通过AnnotationUtils等工具类在查找注解时考虑继承的语义即查找类或方法上的注解时也会查看其父类或接口。对于自定义注解如果你希望它具有“继承”效果可以考虑以下方案使用Inherited元注解这只对类级别的注解有效。如果父类有该注解子类会自动继承。在处理器中手动处理继承在你的注解处理器或AOP切面中不仅检查当前元素也检查其父类或接口。Spring的AnnotationUtils.findAnnotation(Method, Class)方法就提供了这种能力。使用注解组合Meta-annotation定义一个元注解它本身被多个其他注解标注。例如你可以定义一个RestApi注解它本身被RestController和RequestMapping(“/api”)标注。这样你只需要标记RestApi就相当于标记了另外两个注解。5. 生产环境中的避坑指南与最佳实践在实际项目中大规模使用自定义注解我踩过不少坑也总结了一些经验。5.1 性能考量反射的代价反射调用比直接方法调用慢得多。虽然对于大多数Web应用一次Controller方法调用中的几次反射开销可以忽略不计但在超高并发或性能敏感的核心路径上需要谨慎。优化建议缓存反射结果这是最重要的优化手段。例如在AOP切面或注解处理器中第一次通过反射获取Method、Annotation等信息后将其缓存起来可以用ConcurrentHashMap后续直接使用缓存对象。权衡使用APT如果注解逻辑固定且简单考虑使用编译时注解处理器生成代码彻底消除运行时反射。避免深层嵌套和循环内的反射绝对不要在循环内部或频繁调用的方法里进行getAnnotation这类操作。5.2 设计清晰、单一的注解一个注解应该只做一件事并且有一个清晰、明确的名字。不要设计一个GodAnnotation它既能做日志又能做校验还能做缓存。这会导致注解处理器逻辑复杂、难以维护且语义模糊。好的设计Cacheable(key “”, ttl 3600)专门用于缓存。Validated(groups {Default.class, Update.class})专门用于参数校验分组。DistributedLock(key “order:#{id}”, waitTime 5)专门用于分布式锁。5.3 提供合理的默认值尽量为注解的属性提供合理的默认值。这能减少使用者的心智负担让注解用起来更简洁。例如Sensitive注解中我们为maskChar提供了默认值‘*’为pattern提供了空字符串默认值。5.4 注意注解的作用范围Target严格限制注解的Target。如果一个注解只用于方法就不要允许它用在类上。这能在编译期就防止误用利用编译器的力量来保证正确性。5.5 与Spring生态的优雅集成在Spring Boot项目中自定义注解通常需要与Spring容器交互。有几种常见模式实现BeanPostProcessor在Bean初始化前后扫描其注解进行一些处理如注册到某个中心。实现ApplicationListenerContextRefreshedEvent在Spring容器刷新完成后一次性扫描所有Bean的注解执行初始化逻辑。使用Import导入配置类在配置类中定义处理注解所需的Bean如上面的SensitiveSerializer并通过Import将其引入主配置。这是更模块化的做法。与Conditional系列注解结合可以创建自定义的ConditionalOnAnnotation实现当某个注解存在时才注册特定Bean的条件化配置。5.6 版本兼容性与文档当你的注解被多个模块或项目使用时对注解属性的修改如重命名、删除、改变类型是破坏性变更。需要像对待API接口一样谨慎管理注解的版本。为注解和其属性添加清晰的Javadoc注释是必须的最好还能提供一个简单的使用示例。6. 常见问题排查与解决方案实录在实际开发中你可能会遇到以下问题问题1自定义注解不生效处理器没有被调用。检查1Retention是否正确确保是Retention(RetentionPolicy.RUNTIME)SOURCE和CLASS在运行时是拿不到的。检查2Spring AOP切面生效了吗确保切面类被Spring管理有Component或AspectComponent并且切入点表达式Around(“annotation(...)”)写对了包路径完整。检查3Bean的代理问题。Spring AOP默认使用JDK动态代理针对接口或CGLIB针对类。如果方法调用发生在同一个类内部即this.method()则不会经过代理AOP切面自然不生效。这是AOP的经典坑。解决方案通过AopContext.currentProxy()获取代理对象后调用或者将方法抽取到另一个Bean中。检查4Jackson序列化器注册了吗确保自定义的JsonSerializer被正确应用到目标字段上通过JsonSerialize(using ...)或者通过ObjectMapper全局注册。问题2反射获取注解值为null。检查1注解是否真的存在拼写错误或导入错误包是常见原因。检查2是否从正确的AnnotatedElement上获取类注解要从Class对象获取方法注解要从Method对象获取。检查3考虑注解继承。如果你期望从子类方法上获取父类方法声明的注解需要使用AnnotationUtils.findAnnotation()Spring提供而不是标准的getAnnotation()因为标准反射不认为注解是可继承的除了Inherited对类注解的作用。问题3在JDK 8的模块化项目Module中无法访问注解类。原因模块系统加强了封装性。如果注解定义在一个模块中而处理器在另一个模块且注解所在的包没有被exports到处理器模块就会导致ClassNotFoundException或访问失败。解决在定义注解的模块的module-info.java中将包含注解的包exports给需要的模块。例如exports com.yourpackage.annotation to com.yourpackage.processor, spring.core;问题4自定义注解导致序列化循环引用StackOverflowError。场景在脱敏序列化器中如果直接调用gen.writeObject(value)而value对象中又引用了其他带有Sensitive注解的对象可能会陷入无限递归。解决在自定义序列化器中对于非基本类型的属性使用serializers.defaultSerializeValue(value, gen)来委托给默认的序列化器处理避免手动处理复杂对象图。或者确保你的脱敏逻辑只处理String类型字段。自定义注解是Java开发者从“框架使用者”迈向“框架设计者”的关键一步。它让你能够用声明式的、优雅的方式将横切关注点如日志、安全、事务从核心业务逻辑中剥离。从简单的字段标记到复杂的AOP切面再到编译时代码生成其应用深度和广度完全取决于你的想象力和对底层机制的理解。
