读后感 | 美团技术《如何优雅地记录操作日志》

2022-12-01 21:41:33 浏览数 (1)

《如何优雅地记录操作日志》是美团技术团队2021年最受欢迎的一篇技术文章，文章很有深度，强烈建议大家去品读一番。

操作日志指的是某一时间下谁对什么做了什么事情，操作日志一般限定于创建、更新和删除操作，而查询并不是什么敏感操作，所以无需记录操作日志。比如：管理员于2020-10-10 11:12:13新增一个用户，用户名为crimson_typhoon；买家青鸟于2020-10-10 11:12:13更新了联系邮箱，更新前：111111@qq.com，更新后：222222@qq.com等。其实要完整地呈现这一连串信息并不简单，如果大家有一个像我们团队这么好说话的产品经理，咱们也可以简单粗暴些(偷笑)，如下所示：

虽然原文已经写的很深入了，但可能受限于篇幅，对方法注解所涉及到的Spring AOP相关知识并没有详细阐述，所以本文将着重叙述这一块内容。笔者参照原文中的思路，初步实现了一个记录操作日志的组件，后续会不断完善；该组件已经发布到maven中央仓库，大家可以体验一下哈，只需要将OperationLog注解标注于业务逻辑层中的相关敏感操作方法之上即可。GAV信息如下：

代码语言：javascript复制
<dependency>
     <groupId>io.github.dk900912</groupId>
     <artifactId>oplog-spring-boot-starter</artifactId>
     <version>1.0.1</version>
</dependency>

老实说，基于方法注解来实现操作日志是极其优雅的方案，它可以有效收敛横切关注逻辑，避免操作日志的记录逻辑散落在各个业务类中，极大提高了代码的可读性和可维护性。有些老司机可能会觉得直接使用Aspectj就好了，就像下面贴出来的代码那样。的确可以这么做，但后期不易复用，原文还提到了兼容性的问题。

代码语言：javascript复制
@Component
@Aspect
public class OperationLogAdvice {
    @Around(value = "@annotation(io.github.oplog.annotation.OperationLog)")
    public Object doOperationLog(ProceedingJoinPoint joinPoint) {
        // STEP 1：执行目标方法
        Object result = null;
        Throwable exceptionOnTraget = null;
        try {
            result = joinPoint.proceed();
        } catch (Throwable e) {
            exceptionOnTraget = e;
        }
        // STEP 2：记录操作日志
        // STEP 3：如果目标方法执行失败，那么需要重新抛出异常
        return result;
    }
}

基于方法注解实现操作日志这一方案需要依赖于Spring AOP，核心思想就是借助Spring AOP去自动探测由OperationLog注解接口标记的业务逻辑类，从而为这些业务类动态创建代理对象。

1 代理对象如何生成

既然Spring AOP是基于代理对象来拓展目标对象的，那就很容易想到：Spring IoC容器内贮存的一定是代理对象而非目标对象，那究竟是如何替换的呢？众所周知，Spring暴露了若干IoC容器拓展点(IoC Container Extensiion Points)，BeanPostProcessor接口就是其中之一；有了BeanPostProcessor，任何人都可以在Bean初始化前后对其进行个性化改造，甚至将其替换。

让我们来看一下BeanPostProcessor接口中的内容，它只有两个方法，如下：

代码语言：javascript复制
public interface BeanPostProcessor {
    default Object postProcessBeforeInitialization(Object bean, String beanName) 
            throws BeansException {
        return bean;
    }
    default Object postProcessAfterInitialization(Object bean, String beanName) 
            throws BeansException {
        return bean;
    }
}

没错，Spring AOP就是通过BeanPostProcessor将目标对象替换为代理对象的！在Spring AOP中，这个BeanPostProcessor就是AbstractAutoProxyCreator抽象类，其主要用于创建代理对象。AbstractAutoProxyCreator的父子关系如下图所示：

从上图可以看出，Spring AOP为AbstractAutoProxyCreator定义了两个直系子类，分别是：BeanNameAutoProxyCreator和AbstractAdvisorAutoProxyCreator；前者根据Bean的名称来判断是否需要为当前Bean创建代理对象，后者根据Advisor探测结果来判断是否需要为该Bean创建代理对象；何为Advisor？Advisor是Spring AOP中独有的术语，在AspectJ中并没有等效的术语与其匹配，但其与切面还是有一定相似之处的，或者大家干脆将其视为一个特殊的切面，该切面只能包含一个Advice (通知) 和一个Pointcut (切入点) 而已；此外，Advisor有两个分支，分别是PointcutAdvisor和IntroductionAdvisor。

相较于BeanNameAutoProxyCreator，AbstractAdvisorAutoProxyCreator更为重要，AbstractAdvisorAutoProxyCreator有三个子类，分别是AspectJAwareAdvisorAutoProxyCreator、AnnotationAwareAspectJAutoProxyCreator和InfrastructureAdvisorAutoProxyCreator。一般，在Spring IoC中只会有一个名称为org.springframework.aop.config.internalAutoProxyCreator、类型为AbstractAdvisorAutoProxyCreator的Bean，如果classpath下没有Spring AOP依赖或者没有aspectjweaver依赖，那么Spring Boot会自动选用InfrastructureAdvisorAutoProxyCreator；否则将会选用AnnotationAwareAspectJAutoProxyCreator。大家可以通过下面这种方式来验证三者的优先级，AnnotationAwareAspectJAutoProxyCreator是优先级最高、最通用的一个。

代码语言：javascript复制
public class AutoProxyCreatorPriorityApplication {
    public static final String AUTO_PROXY_CREATOR_BEAN_NAME =
            "org.springframework.aop.config.internalAutoProxyCreator";
    public static void main(String[] args) {
        // STEP 1：构造 BeanDefinitionRegistry
        // STEP 2 3 4 依次向 BeanDefinitionRegistry 中注册三种 AbstractAdvisorAutoProxyCreator BeanDefinition 实例，
        // 但 name 完全一致，即 AUTO_PROXY_CREATOR_BEAN_NAME
        BeanDefinitionRegistry beanDefinitionRegistry = new SimpleBeanDefinitionRegistry();

        // STEP 2：注册 InfrastructureAdvisorAutoProxyCreator BeanDefinition
        AopConfigUtils.registerAutoProxyCreatorIfNecessary(beanDefinitionRegistry);
        BeanDefinition infrastructureAdvisorCreatorBeanDefinition = beanDefinitionRegistry.getBeanDefinition(AUTO_PROXY_CREATOR_BEAN_NAME);
        System.out.println(infrastructureAdvisorCreatorBeanDefinition.getBeanClassName());

        // STEP 3：注册 AspectJAwareAdvisorAutoProxyCreator BeanDefinition
        AopConfigUtils.registerAspectJAutoProxyCreatorIfNecessary(beanDefinitionRegistry);
        BeanDefinition aspectJAwareAdvisorCreatorBeanDefinition = beanDefinitionRegistry.getBeanDefinition(AUTO_PROXY_CREATOR_BEAN_NAME);
        System.out.println(aspectJAwareAdvisorCreatorBeanDefinition.getBeanClassName());

        // STEP 4：注册 AnnotationAwareAspectJAutoProxyCreator BeanDefinition
        AopConfigUtils.registerAspectJAnnotationAutoProxyCreatorIfNecessary(beanDefinitionRegistry);
        BeanDefinition annotationAwareAspectJCreatorBeanDefinition = beanDefinitionRegistry.getBeanDefinition(AUTO_PROXY_CREATOR_BEAN_NAME);
        System.out.println(annotationAwareAspectJCreatorBeanDefinition.getBeanClassName());
    }
}

InfrastructureAdvisorAutoProxyCreator是如何判断是否需要为当前Bean创建代理对象的呢？

  1. 首先，它会从Spring IoC容器中一次性获取所有Advisor；
  2. 然后，逐一遍历每个Advisor，若当前Advisor所对应的BeanDefinition的Role等于BeanDefinition.ROLE_INFRASTRUCTURE，那么该Advisor就具备候选资质；
  3. 最后，从具备候选资质的Advisor列表中选取与当前Bean匹配的Advisor，如果最终存在相匹配的Advisor，那么就为当前Bean创建代理对象；那么是如何裁定是否匹配的呢？若该Advisor是PointcutAdvisor类型，那么就根据ClassFilter与MethodMatcher去匹配当前Bean；若该Advisor是IntroductionAdvisor类型，那么就根据ClassFilter去匹配当前Bean。

AnnotationAwareAspectJAutoProxyCreator又是如何判断是否需要为当前Bean创建代理对象的呢？这部分逻辑比较复杂，如果想了解详细逻辑，参见笔者之前写的一篇文章《Spring AOP，从入门到进阶》。

  1. 首先，它会从Spring IoC容器中一次性获取所有Advisor (一般，这些Advisor是用户或者开源组件中自定义的)，默认这些Advisor具备候选资质，压根不用像InfrastructureAdvisorAutoProxyCreator那样还要具体判断是否具备候选资质，这也从侧面说明：为什么AnnotationAwareAspectJAutoProxyCreator比InfrastructureAdvisorAutoProxyCreator优先级更高；
  2. 然后，它再从Spring IoC容器中获取所有由@Aspect标注的Bean，将这些切面Bean中由@Before、@After和@Around等标注的方法封装成一个PointcutAdvisor列表，至此将步骤一和步骤二中的Advisor组合为一个候选Advisor列表；
  3. 最后，从具备候选资质的Advisor列表中选取与当前Bean匹配的Advisor，如果最终存在相匹配的Advisor，那么就为当前Bean创建代理对象；那么是如何裁定是否匹配的呢？若该Advisor是PointcutAdvisor类型，那么就根据ClassFilter与MethodMatcher去匹配当前Bean；若该Advisor是IntroductionAdvisor类型，那么就根据ClassFilter去匹配当前Bean。

Spring AOP之所以能支持以Aspectj注解风格去定义切面，靠的就是AnnotationAwareAspectJAutoProxyCreator！

代理对象的创建规则已经清晰了，接下来就要搞清楚究竟是如何创建代理对象的。Spring AOP依托JDK动态代理和CGLIB代理技术来创建代理对象，关于这方面的知识参见笔者之前写的一篇文章《Java动态代理》，这里就不再赘述了。

理论知识基本介绍完毕，下面进入实战环节。摆在大家面前的第一道坎应该是选取合适的Advisor，究竟是PointcutAdvisor还是IntroductionAdvisor呢？PointcutAdvisor持有一个Advice和一个Pointcut，Spring AOP 将Advice建模为org.aopalliance.intercept.MethodInterctptor拦截器，Pointcut用于声明应该在哪些Joinpoint (连接点) 处应用切面逻辑，而Joinpoint在SpringAOP 中专指方法的执行，因此，PointcutAdvisor中的Advice是方法级的拦截器；IntroductionAdvisor仅持有一个Advice和一个ClassFilter，显然，IntroductionAdvisor中的Advice是类级的拦截器。如果选用IntroductionAdvisor，可我们无法知道哪些类需要拦截啊，相反，如果选用PointcutAdvisor，那就可以借助MethodMatcher中的matches()方法准确拦截持有@OperationLog注解的目标方法。既然认准了PointcutAdvisor，那既可以直接实现PointcutAdvisor接口，也可以继承AbstractPointcutAdvisor，还可以继承AbstractBeanFactoryPointcutAdvisor，怎么搞都行，只要能包住Advice和Pointcut就行。如下所示：

代码语言：javascript复制
public class OperationLogPointcutAdvisor extends AbstractBeanFactoryPointcutAdvisor {
    private Pointcut pointcut;

    public OperationLogPointcutAdvisor() {
    }

    /**
     * @param pointcut
     * @param advice
     */
    public OperationLogPointcutAdvisor(Pointcut pointcut, Advice advice) {
        this.pointcut = pointcut;
        setAdvice(advice);
    }

    public void setPointcut(Pointcut pointcut) {
        this.pointcut = pointcut;
    }

    @Override
    public Pointcut getPointcut() {
        return this.pointcut;
    }
}

那么，对于Pointcut又该如何取舍呢？我们期待它的ClassFiler能够匹配所有类，而它的MethodMatcher只需要静态匹配就好了，即MethodMatcher中的isRuntime()方法返回false，这么一合计，StaticMethodMatcherPointcut简直完美契合。如下所示：

代码语言：javascript复制
public class OperationLogPointcut extends StaticMethodMatcherPointcut {
    @Override
    public boolean matches(Method method, Class<?> targetClass) {
        Annotation operationLogAnnotation = AnnotationUtils.findAnnotation(method, OperationLog.class);
        return Objects.nonNull(operationLogAnnotation);
    }
}

对于Advice呢，直接使用强大的org.aopalliance.intercept.MethodInterceptor接口即可，它可以模拟实现MethodBeforeAdvice、AfterReturningAdvice和ThrowsAdvice等。如下所示：

代码语言：javascript复制
public class OperationLogAdvice implements MethodInterceptor {

    private OperatorService operatorService;

    private LogRecordPersistenceService logRecordPersistenceService;

    @Override
    public Object invoke(MethodInvocation invocation) throws Throwable {
        Object result = null;
        Throwable throwable = null;
        try {
            result = invocation.proceed();
        } catch (Throwable e) {
            throwable = e;
        }

        Method method = invocation.getMethod();
        Annotation operationLogAnnotation = AnnotationUtils.findAnnotation(method, OperationLog.class);
        Map<String, Object> operationLogAnnotationAttrMap = AnnotationUtils.getAnnotationAttributes(operationLogAnnotation);
        Operator operator = getOperator();
        BizCategory bizCategory =  (BizCategory) operationLogAnnotationAttrMap.get("bizCategory");
        String bizTarget =  (String) operationLogAnnotationAttrMap.get("bizTarget");
        String operation = String.format("%s %s %s", operator.getOperatorName(), bizCategory.getName(), bizTarget);
        LogRecord logRecord = encapsulateLogRecord(operator, bizTarget, operation, throwable);
        logRecordPersistenceService.doLogRecordPersistence(logRecord);

        if (Objects.nonNull(throwable)) {
            throw throwable;
        }
        return result;
    }
}

万事俱备，将OperationLogPointcutAdvisor声明为一个Bean吧，但千万别遗漏了这么一行：@Role(BeanDefinition.ROLE_INFRASTRUCTURE)。为什么强烈建议加这一行代码呢？当作思考题吧！

2 如何使用oplog-spring-boot-starter

2.1 在启动类中开启记录操作日志开关
代码语言：javascript复制
@SpringBootApplication
@EnableAspectJAutoProxy(exposeProxy = true)
@EnableOperationLog
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}
2.2 实现OperatorService接口

OperatorService是预留接口，主要用于获取当前操作用户。一般，过滤器会提前将用户信息保存在ThreadLocal中，在同一个请求上下文中直接从ThreadLocal中获取即可。

2.3 实现LogRecordPersistenceService接口

LogRecordPersistenceService接口用于设定操作日志的持久化方式，如果大家自行实现LogRecordPersistenceService接口并将其声明为Bean，那么就会采用大家自定义日志持久化方案，否则采用默认的日志持久化方案 (即将操作日志打印到日志文件中) 。之所以这么灵活，是因为组件在声明LogRecordPersistenceService这一默认Bean时，使用了@ConditionalOnMissingBean，如下所示：

代码语言：javascript复制
@Configuration
public class OperationLogAutoConfigurationImportSelector {
    @Bean
    @ConditionalOnMissingBean(LogRecordPersistenceService.class)
    public LogRecordPersistenceService logRecordPersistenceService() {
        return new DefaultLogRecordPersistenceServiceImpl();
    }
}
2.4 在业务类中的相关方法上追加@OperationLog注解

OperationLog注解接口源码如下，由于这俩属性都没default修饰符，因此它们都是必须显式设定的。

代码语言：javascript复制
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@Documented
public @interface OperationLog {
    /**
     * 操作种类：新增、更新和删除
     */
    BizCategory bizCategory();

    /**
     * 业务对象，如：订单、用户、商品等
     */
    String bizTarget();
}

3 总结

感兴趣的读者可以到github阅读源码。

4 参考文档

  1. https://github.com/dk900912/oplog-spring-boot
spring aop

0 人点赞