[MyBatis源码分析 - 日志模块]

一、日志概述

  衡量软件产品的质量时，是否具备完善的日志是个非常重要的因素。开发测试阶段，需要日志帮助我们完善功能和发现bug；生产上，当出现生产问题时，又需要日志帮助我们定位问题发生现场的情况。同时，日志还是开发与运维之间的桥梁，有助于运维管理人员快速查找系统的故障和瓶颈，良好的日志在一个软件中占了非常重要的地位。

  日志对于排查问题很有帮助，但不是越多越好，过多冗余的日志，不管是日志输出还是保存日志到文件，都会消耗服务器的资源，我们希望某些日志在开发测试阶段打出来，在版本稳定投产之后只打印关键日志，还有想根据日志的不同类型分门别类归纳到日志文件中，日志文件达到一定大小或保存一定时间就删除，这些日志需求的场景都是很常见的，在 Java 的世界中已经有多种成熟开源的日志框架，常用的有 Log4j、Log4j2、Apache Commons Log、java.util.logging、slf4j 等，它们的框架 API 略有差异，不过使用上整体大同小异。

  MyBatis 聚合了上述多种优秀的日志框架，提供框架内部输出详细日志的能力，并且为了屏蔽不同日志框架 API 的差异，提供了一个统一的接口，并且基于该接口定制了针对不同日志框架的适配器，使得用户可以根据自身喜好和使用习惯方便地选择要使用的日志框架。

  MyBatis 的日志模块位于 org.apache.ibatis.logging 包中，如下所示：

二、整体设计

  日志模块的整体设计如下：

  日志模块使用了适配器模式，对外提供的统一日志接口是 Log，每种日志框架都有对应的适配器来适配接口的定义，LogFactory 是日志工厂类，MyBatis 中最重要的日志就是执行 SQL 的时候打印调试日志，为了适应格式化日志的要求，定义了 BaseJdbcLogger 及其几个子类，通过动态代理的方式，在执行 JDBC 相关方法时拦截，并输出响应的日志，常见的有 SQL 语句、传入参数、执行影响行数等。

三、Log

  不同的日志框架对日志级别的定义略有差异，比如 Log4j 的日志级别有：trace、debug、info、warn、error、fatal；java.util.logging 的日志级别有：ALL、FINEST、FINER、FINE、CONFIG、INFO、WARNING、SEVERE、OFF。MyBatis 统一提供了 trace、debug、warn、error 四个级别，这基本与主流日志框架的日志级别类似，可以满足绝大多数场景的日志需求。

  org.apache.ibatis.logging.Log 定义了日志模块的功能，所有的日志适配器都要实现该接口，接口定义如下：

public interface Log {
  boolean isDebugEnabled();

  boolean isTraceEnabled();

  void error(String s, Throwable e);

  void error(String s);

  void debug(String s);

  void trace(String s);

  void warn(String s);
}

  下面以 Log4jImpl 和 Jdk14LoggingImpl 为例说明日志框架适配器的实现，其他适配器类似。

1、Log4jImpl

  Log4jImpl 是 Log4j 日志框架对接口的适配器，其源码如下：

public class Log4jImpl implements Log {
  // 显示调用者位置的参数
  private static final String FQCN = Log4jImpl.class.getName();

  private Logger log;

  public Log4jImpl(String clazz) {
    log = Logger.getLogger(clazz);
  }

  @Override
  public boolean isDebugEnabled() {
    return log.isDebugEnabled();
  }

  @Override
  public boolean isTraceEnabled() {
    return log.isTraceEnabled();
  }

  @Override
  public void error(String s, Throwable e) {
    log.log(FQCN, Level.ERROR, s, e);
  }

  @Override
  public void error(String s) {
    log.log(FQCN, Level.ERROR, s, null);
  }

  @Override
  public void debug(String s) {
    log.log(FQCN, Level.DEBUG, s, null);
  }

  @Override
  public void trace(String s) {
    log.log(FQCN, Level.TRACE, s, null);
  }

  @Override
  public void warn(String s) {
    log.log(FQCN, Level.WARN, s, null);
  }

}

  这里有一个特别的地方，FQCN 参数，该参数传入的 #log() 方法的第一个参数传入，在 Log4j 中参数名叫 callFQCN，log4j 把传递进来的 callerFQCN 在调用堆栈中一一比较，相等后，再往上一层即认为是用户的调用类。

2、Jdk14LoggingImpl

  Jdk14LoggingImpl 是 JDK 内置日志框架对接口的适配器，其源码如下：

public class Jdk14LoggingImpl implements Log {

  private Logger log;

  public Jdk14LoggingImpl(String clazz) {
    log = Logger.getLogger(clazz);
  }

  @Override
  public boolean isDebugEnabled() {
    return log.isLoggable(Level.FINE);
  }

  @Override
  public boolean isTraceEnabled() {
    return log.isLoggable(Level.FINER);
  }

  @Override
  public void error(String s, Throwable e) {
    log.log(Level.SEVERE, s, e);
  }

  @Override
  public void error(String s) {
    log.log(Level.SEVERE, s);
  }

  @Override
  public void debug(String s) {
    log.log(Level.FINE, s);
  }

  @Override
  public void trace(String s) {
    log.log(Level.FINER, s);
  }

  @Override
  public void warn(String s) {
    log.log(Level.WARNING, s);
  }

}

四、LogFactory

  public static final String MARKER = "MYBATIS";
  // 记录当前使用的第三方日志组件所对应的适配器的构造方法
  private static Constructor logConstructor;

  // 针对每种日志组件调用 tryImplementation() 方法进行尝试加载，具体调用顺序是：
  // useSlf4jLogging() --> useCommonsLogging() --> useLog4J2Logging() -->
  // useLog4JLogging() --> useJdkLogging() --> useNoLogging()
  static {
    tryImplementation(new Runnable() {
      @Override
      public void run() {
        useSlf4jLogging();
      }
    });
    tryImplementation(new Runnable() {
      @Override
      public void run() {
        useCommonsLogging();
      }
    });
    tryImplementation(new Runnable() {
      @Override
      public void run() {
        useLog4J2Logging();
      }
    });
    tryImplementation(new Runnable() {
      @Override
      public void run() {
        useLog4JLogging();
      }
    });
    tryImplementation(new Runnable() {
      @Override
      public void run() {
        useJdkLogging();
      }
    });
    tryImplementation(new Runnable() {
      @Override
      public void run() {
        useNoLogging();
      }
    });
  }
  // 工厂类对外只提供静态方法，构造函数私有
  private LogFactory() {
    // disable construction
  }

  LogFactory 中定义了 logConstructor 成员来保存当前使用的第三方日志所对应的适配器的构造方法，第一次加载工厂类时，会调用静态代码块初始化尝试加载各种日志组件，优先级从代码中可以看出，最先加载的适配器会赋值给 logConstructor，代码如下：

  private static void tryImplementation(Runnable runnable) {
    // 先判断是否已加载到适配器，是则放弃加载其他适配器
    if (logConstructor == null) {
      try {
        runnable.run();
      } catch (Throwable t) {
        // ignore
      }
    }
  }

  虽然将方法调用包装成了一个 runnable，但这里注意不是用 new Thread(runnable).start() 去启动一个新线程，只是简单的调用 runnable.run() 所以对各个适配器的加载是串行的，优先级靠前的适配器加载不到才会真正尝试去加载后面的适配器，各个加载适配器的方法里，都会去调用 #setImplementation() 完成加载动作，传参是适配器对应的 Class 对象，以 Log4j 为例：

  public static synchronized void useLog4JLogging() {
    setImplementation(org.apache.ibatis.logging.log4j.Log4jImpl.class);
  }

  private static void setImplementation(Class implClass) {
    try {
      // 获取构造参数为 String 的构造器
      Constructor candidate = implClass.getConstructor(String.class);
      // 用构造器实例化 Log 对象
      Log log = candidate.newInstance(LogFactory.class.getName());
      if (log.isDebugEnabled()) {
        log.debug("Logging initialized using '" + implClass + "' adapter.");
      }
      // 赋值
      logConstructor = candidate;
    } catch (Throwable t) {
      throw new LogException("Error setting Log implementation.  Cause: " + t, t);
    }
  }

  这里的 #useLog4JLogging() 方法定义用了 synchronized 关键字，这里有点疑惑，如果是加载各个适配器都启动一个新线程还可以理解，但问题是，并没有启新线程，所以我猜测这里跟初始化加载无关，跟调用线程有关，因为 logConstructor 必须是线程安全的，因为暴露给外界的 #getLog 方法用了该变量去创建具体的 Log 对象，如下：

  public static Log getLog(Class aClass) {
    return getLog(aClass.getName());
  }

  public static Log getLog(String logger) {
    try {
      return logConstructor.newInstance(logger);
    } catch (Throwable t) {
      throw new LogException("Error creating logger for logger " + logger + ".  Cause: " + t, t);
    }
  }

五、JDBC 调试

  业务代码在打印日志时，往往是先创建一个 Logger，然后在一些关键的地方，比如接口调用、错误异常处理等地方打上日志，但有些时候，出于保持代码清晰或其他原因，在某些地方不想掺杂日志打印的代码，这时候就可以使用动态代理，动态代理常用的有 JDK 动态代理、CGLIB 等，MyBatis 打印 SQL 执行日志方便 JDBC 调试的功能，就是基于 JDK 动态代理实现的。

  动态代理，一般无非是在某个方法调用的前后添加某些处理，对于使用者来说，只要拿到代理对象，就可以将它当成普通对象来使用，代理的逻辑对使用者来说是透明。

1、JDK 动态代理的使用

  使用 JDK 动态代理，要满足几个条件：

• （1）定义一个接口。
• （2）被代理的类要实现（1）中接口。
• （3）定义一个实现了 InvocationHandler 接口的类，该类中会封装被代理的对象，并且该类实例会被传递给 Proxy.newProxyInstance 方法创建代理对象。

  下面举例说明：

1.1 定义接口

public interface HelloWorld {
    public void sayHelloWorld();
}

1.2 代理类

public class HelloWorldImpl implements HelloWorld {
    @Override
    public void sayHelloWorld() {
        System.out.println("Hello World");      
    }
}

1.3 InvocationHandler 实现类

/**
 * 使用JDK实现动态代理，要求被代理的对象必须实现一个接口
 */
public class JdkProxyExample implements InvocationHandler {

    // 真实对象
    private Object target = null;
    
    // 绑定真实对象并返回代理对象
    public Object bind(Object target) {
        this.target = target;
        // 第三个参数类型是InvocationHandler，代理对象被调用时，会先执行Handler接口的invoke方法
        return Proxy.newProxyInstance(target.getClass().getClassLoader(), target.getClass().getInterfaces(), this);
    }
    
    /**
     * 代理方法逻辑
     * @param proxy 代理对象
     * @param method 当前调度方法
     * @param args 当前方法参数
     * @return 代理结果返回
     * @throws Throwable 异常
     */
    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
        System.out.println("进入代理逻辑方法");
        System.out.println("在调度真实对象之前的服务");
        Object obj = method.invoke(target, args);
        System.out.println("在调度真实对象之后的服务");
        return obj;
    }
    
    public static void main(String[] args) {
        JdkProxyExample jdk = new JdkProxyExample();
        HelloWorld proxy = (HelloWorld) jdk.bind(new HelloWorldImpl());
        proxy.sayHelloWorld();
    }
}

  执行结果如下：

进入代理逻辑方法
在调度真实对象之前的服务
Hello World
在调度真实对象之后的服务

2、BaseJdbcLogger 及其子类

  BaseJdbcLogger 及其子类通过使用动态代理，实现了执行 SQL 操作时，无感输出 JDBC 调试日志的效果。

2.1 BaseJdbcLogger

2.1.1 数据结构

  protected static final Set SET_METHODS = new HashSet();       // 记录了PreparedStatement接口中定义的常用的set*()方法
  protected static final Set EXECUTE_METHODS = new HashSet();   // 记录了Statement接口和PreparedStatement接口中与执行SQL语句相关的方法

  private Map columnMap = new HashMap();                // 记录了PreparedStatement.set*()方法设置的键值对

  private List