AOP+注解实现方法调用日志的优雅记录-代码聚汇网

AOP+注解实现方法调用日志的优雅记录

照横塘半天残月

1. 为什么我们需要优雅地记录方法调用信息？

在日常开发中，调试和排查问题往往是最耗时的工作之一。想象这样一个场景：线上环境某个核心接口突然报错，你打开日志系统，却发现只有简单的"NullPointerException"错误信息，没有任何上下文数据。此时你不得不：

在本地重现问题
逐步添加日志打印
反复部署测试
最终才能定位到问题根源

这种低效的排查过程，正是我们需要解决的核心痛点。通过@LogRecord注解结合AOP技术，可以实现：

全自动记录：方法调用的入参、出参和异常信息自动记录，无需手动添加日志代码
上下文完整：每次调用都有完整的执行轨迹，包括参数值、返回结果和异常堆栈
非侵入式：业务代码保持干净，日志逻辑与业务逻辑完全解耦

提示：这种方案特别适合核心业务逻辑、第三方服务调用等关键路径的监控，但要注意避免在性能敏感路径上过度记录。

2. 技术选型：为什么是AOP+注解？

2.1 AOP的天然优势

AOP（面向切面编程）是这个方案的核心技术，因为它完美匹配了日志记录这类横切关注点（Cross-Cutting Concerns）的需求：

执行时机控制：可以在方法调用前、后、异常时等精确切入点插入逻辑
目标方法无感知：不需要修改原有业务代码
集中管理：所有日志策略在一个地方维护，避免分散在各处

Spring AOP提供了几种典型的切入点：

@Before：方法执行前
@AfterReturning：方法正常返回后
@AfterThrowing：方法抛出异常后
@Around：包围方法执行（最灵活）

2.2 注解驱动的设计考量

@LogRecord注解的设计使得日志记录变得声明式和可配置：

java复制@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface LogRecord {
    // 业务标识，用于区分不同场景
    String bizCode() default "";
    
    // 是否记录入参
    boolean logParams() default true;
    
    // 是否记录返回值
    boolean logResult() default true;
    
    // 是否记录异常
    boolean logException() default true;
    
    // 自定义日志级别
    LogLevel level() default LogLevel.INFO;
}

这种设计的好处是：

细粒度控制：可以针对每个方法单独配置记录策略
语义明确：注解属性直观表达了记录规则
易于扩展：后续可以添加更多配置项而不影响现有使用

3. 核心实现详解

3.1 切面类的基础结构

以下是核心切面类的骨架代码：

java复制@Aspect
@Component
@Slf4j
public class LogRecordAspect {
    
    // 定义切入点：所有带有@LogRecord注解的方法
    @Pointcut("@annotation(com.example.annotation.LogRecord)")
    public void logRecordPointcut() {}
    
    // Around建议可以最灵活地控制方法执行
    @Around("logRecordPointcut()")
    public Object aroundAdvice(ProceedingJoinPoint joinPoint) throws Throwable {
        Method method = ((MethodSignature) joinPoint.getSignature()).getMethod();
        LogRecord annotation = method.getAnnotation(LogRecord.class);
        
        // 记录入参
        if (annotation.logParams()) {
            logParams(joinPoint, annotation);
        }
        
        try {
            Object result = joinPoint.proceed();
            
            // 记录出参
            if (annotation.logResult()) {
                logResult(result, annotation);
            }
            
            return result;
        } catch (Throwable e) {
            // 记录异常
            if (annotation.logException()) {
                logException(e, annotation);
            }
            throw e;
        }
    }
    
    private void logParams(ProceedingJoinPoint joinPoint, LogRecord annotation) {
        // 具体实现...
    }
    
    private void logResult(Object result, LogRecord annotation) {
        // 具体实现...
    }
    
    private void logException(Throwable e, LogRecord annotation) {
        // 具体实现...
    }
}

3.2 参数记录的实现细节

记录方法参数时需要考虑几个关键点：

参数提取：

java复制Object[] args = joinPoint.getArgs();
Parameter[] parameters = method.getParameters();

敏感数据处理：

java复制// 对密码等敏感字段进行脱敏
if (parameter.getName().contains("password")) {
    args[i] = "******";
}

大对象处理：

java复制// 避免记录过大的对象
if (args[i] instanceof byte[] && ((byte[])args[i]).length > 1024) {
    args[i] = "[binary data length=" + ((byte[])args[i]).length + "]";
}

3.3 异常记录的优化策略

异常记录不仅仅是简单的e.printStackTrace()，需要考虑：

根因提取：

java复制Throwable rootCause = e;
while (rootCause.getCause() != null) {
    rootCause = rootCause.getCause();
}

业务异常区分：

java复制if (e instanceof BusinessException) {
    log.warn("Business exception occurred: {}", e.getMessage());
} else {
    log.error("System error", e);
}

堆栈精简：

java复制String stackTrace = Arrays.stream(e.getStackTrace())
    .limit(10) // 只取前10帧
    .map(StackTraceElement::toString)
    .collect(Collectors.joining("\n"));

4. 高级特性与性能优化

4.1 异步日志记录

同步记录日志可能影响方法执行性能，特别是在高并发场景下。我们可以引入异步处理：

java复制@Async
public void asyncLogRecord(Supplier<String> logSupplier) {
    log.info(logSupplier.get());
}

使用时：

java复制asyncLogRecord(() -> "Method called with params: " + Arrays.toString(args));

注意：需要确保线程池配置合理，避免OOM风险

4.2 条件日志记录

有时我们只想在特定条件下记录日志，可以通过SpEL表达式实现：

java复制@LogRecord(condition = "#result != null")
public User getUserById(Long id) {
    // ...
}

切面中解析条件：

java复制ExpressionParser parser = new SpelExpressionParser();
Expression expression = parser.parseExpression(annotation.condition());
boolean shouldLog = expression.getValue(evaluationContext, Boolean.class);

4.3 性能优化技巧

字符串拼接优化：

java复制// 使用Supplier延迟拼接
if (log.isInfoEnabled()) {
    log.info(() -> "Large object: " + expensiveToString(object));
}

采样记录：

java复制// 只记录1%的请求
if (ThreadLocalRandom.current().nextInt(100) == 0) {
    log.info("Sampled log: {}", data);
}

MDC上下文：

java复制try (MDC.MDCCloseable closeable = MDC.putCloseable("traceId", UUID.randomUUID().toString())) {
    // 方法执行
}

5. 生产环境中的实践经验

5.1 典型问题排查

问题现象：日志量暴增导致磁盘写满

解决方案：

添加方法调用频率监控
对大流量接口实施采样记录
设置合理的日志级别阈值

问题现象：敏感数据泄露