Java自定义注解：从定义到解析，再到AOP切面与日志打印应用

一、注解定义

注解本质上是一种元数据，可以附加在类、方法、字段或其他程序元素上，为编译器或运行时环境提供额外的信息。Java标准库中提供了多种内置注解，但为了满足特定需求，我们可以创建自定义注解。

代码示例

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;// @Target 表明该注解可以应用于哪些程序元素
@Target(ElementType.METHOD)
// @Retention 表明注解在何时可用：源码级别、类文件级别还是运行时级别
@Retention(RetentionPolicy.RUNTIME)
public @interface LogExecution {// 定义注解的一个属性，并给出默认值String value() default "";// 可以定义更多的属性，例如记录的日志级别LogLevel level() default LogLevel.INFO;
}// 自定义枚举用于指定日志级别
public enum LogLevel {DEBUG, INFO, WARN, ERROR
}

我们创建了一个名为LogExecution的注解，它可以应用到方法上，并有两个可选参数：value（用于存储自定义消息）和level（用于指定日志级别）。

二、注解解析

要使用自定义注解的信息，我们需要通过Java反射API来解析注解。以下是如何在运行时获取并使用LogExecution注解的示例：

代码示例

import java.lang.reflect.Method;public class AnnotationProcessor {public void process(Method method) {if (method.isAnnotationPresent(LogExecution.class)) {LogExecution logExecution = method.getAnnotation(LogExecution.class);String message = logExecution.value();LogLevel level = logExecution.level();// 根据日志级别调用对应的日志接口switch (level) {case DEBUG:System.out.println("DEBUG: " + message);break;case INFO:System.out.println("INFO: " + message);break;// ... 其他级别处理 ...}}}
}

这段代码首先检查方法是否带有LogExecution注解，如果有，则提取注解的属性值并根据日志级别进行相应的日志输出。

三、自定义注解结合AOP切面

在Spring AOP框架中，我们可以利用AOP来处理带有自定义注解的方法，实现诸如日志记录、事务管理等横切关注点。以下是将LogExecution注解与AOP结合的例子：

代码示例

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.springframework.stereotype.Component;@Aspect
@Component
public class LoggingAspect {@Around("@annotation(LogExecution)")public Object logMethodExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {MethodSignature signature = (MethodSignature) joinPoint.getSignature();LogExecution annotation = signature.getMethod().getAnnotation(LogExecution.class);// 开始计时long start = System.currentTimeMillis();// 执行原方法        Object result = joinPoint.proceed();// 结束计时并打印日志long executionTime = System.currentTimeMillis() - start;String message = annotation.value();LogLevel level = annotation.level();// 打印执行时间和注解信息printLog(level, message, executionTime);return result;}private void printLog(LogLevel level, String message, long executionTime) {// 根据日志级别调用对应的日志服务，这里仅做简单演示switch (level) {case DEBUG:System.out.printf("[DEBUG] %s took %d ms%n", message, executionTime);break;// ... 其他级别处理 ...}}
}

在这个AOP切面中，我们定义了一个环绕通知，当目标方法标注了LogExecution注解时，会计算方法的执行时间并按照注解配置的日志级别打印相关日志。

四、自定义注解用于日志打印

结合前面的例子，我们可以进一步完善LogExecution注解的功能，使其不仅能记录执行时间，还能按照注解中定义的消息格式打印日志。

Step 1: 创建自定义注解

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface LogExecution {String message() default "Method execution: {}";LogLevel level() default LogLevel.INFO;enum LogLevel {TRACE, DEBUG, INFO, WARN, ERROR}
}

Step 2: 定义服务接口和其实现类，并在方法上应用注解

public interface UserService {@LogExecution(message = "User is being retrieved by ID: {}", level = LogLevel.DEBUG)User getUserById(Long id);
}@Service
public class UserServiceImpl implements UserService {// ...@Overridepublic User getUserById(Long id) {// 实现获取用户的方法逻辑// ...return user;}
}

Step 3: 编写AOP切面类处理日志打印

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;@Aspect
@Component
public class LoggingAspect {private static final Logger LOGGER = LoggerFactory.getLogger(LoggingAspect.class);@Around("@annotation(logExecution)")public Object logExecutionTime(ProceedingJoinPoint joinPoint, LogExecution logExecution) throws Throwable {String methodSignature = joinPoint.getSignature().toShortString();String formattedMessage = String.format(logExecution.message(), methodSignature);switch (logExecution.level()) {case TRACE:LOGGER.trace(formattedMessage);break;case DEBUG:LOGGER.debug(formattedMessage);break;case INFO:LOGGER.info(formattedMessage);break;case WARN:LOGGER.warn(formattedMessage);break;case ERROR:LOGGER.error(formattedMessage);break;}long start = System.currentTimeMillis();try {// 执行原方法Object result = joinPoint.proceed();// 记录执行结束时间（此处仅演示了注解的功能性，实际可能需要记录更多信息）LOGGER.info("Finished executing {}, took {}ms", methodSignature, System.currentTimeMillis() - start);return result;} catch (Throwable ex) {LOGGER.error("An error occurred while executing {}", methodSignature, ex);throw ex;}}
}

当调用getUserById方法时，由于该方法被@LogExecution注解标记，所以会触发LoggingAspect中的logExecutionTime方法，在方法执行前后进行相应的日志记录。

Step 4: 在Controller类上应用自定义注解

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;@RestController
public class UserController {private final UserService userService;public UserController(UserService userService) {this.userService = userService;}@GetMapping("/users/{id}")@LogExecution(message = "User is being retrieved from API with ID: {}", level = LogLevel.INFO)public User getUser(@PathVariable Long id) {return userService.getUserById(id);}
}

当我们通过API访问/users/{id}端点以获取用户信息时，由于getUser方法上添加了@LogExecution注解，所以每当此方法被调用时，LoggingAspect切面会捕获到这个事件，并根据注解的配置打印相应的日志信息。

如果客户端请求 /users/1 ，那么控制台将会看到类似于以下格式的日志：

INFO [com.example.LoggingAspect] - User is being retrieved from API with ID: UserController.getUser(Long)
INFO [com.example.LoggingAspect] - Finished executing UserController.getUser(Long), took x ms

其中 x 是方法执行所花费的时间（毫秒）。这样，我们就成功地利用自定义注解和AOP切面实现了对Controller层接口调用的日志记录功能。

五、区别总结

自定义注解作为Java元编程的一种机制，允许开发者为类、方法等程序元素添加类型安全的元数据标签；

而注解解析则是利用Java反射API在运行时读取这些注解及其属性值，进而指导框架或工具实施特定的行为逻辑。

结合面向切面编程（AOP）技术，自定义注解可以作为一个触发器，自动织入横切关注点，比如在方法执行前后插入日志打印代码块。

六、应用场景总结

模块化日志处理：通过在业务层方法上标注LogExecution等自定义注解，可以统一控制和自动化收集关键操作的日志信息，包括但不限于执行时间、参数详情、返回结果以及异常情况等。
服务治理：在复杂的微服务架构环境中，自定义注解能够有效地标记那些需要特别关注的服务接口或内部方法，以便于系统集中地实现性能监控、事务管理、缓存策略调整等功能，从而提升服务的整体质量和运维效率。
代码规范与安全性：除了功能性的增强外，自定义注解还可用于编码规范检查，比如验证方法是否符合特定的设计模式或最佳实践；同时，在权限控制、敏感数据操作等场景下，注解可以配合AOP来强制执行安全策略，确保代码遵循预定的安全规则，防止潜在的安全漏洞。