11<?xml version =" 1.0" encoding =" UTF-8"
22<!--
33
4- Copyright 2009-2019 the original author or authors.
4+ Copyright 2009-2020 the original author or authors.
55
66 Licensed under the Apache License, Version 2.0 (the "License");
77 you may not use this file except in compliance with the License.
2727
2828 <body >
2929 <section name =" 日志"
30- <p ></p >
31- <p >Mybatis 的内置日志工厂提供日志功能，内置日志工厂将日志交给以下其中一种工具作代理：</p >
30+ <p >Mybatis 通过使用内置的日志工厂提供日志功能。内置日志工厂将会把日志工作委托给下面的实现之一：</p >
3231 <ul >
3332 <li >
3433 SLF4J
4645 JDK logging
4746 </li >
4847 </ul >
49- <p >MyBatis 内置日志工厂基于运行时自省机制选择合适的日志工具。它会使用第一个查找得到的工具（按上文列举的顺序查找）。如果一个都未找到，日志功能就会被禁用 。</p >
50- <p >不少应用服务器（如 Tomcat 和 WebShpere）的类路径中已经包含 Commons Logging，所以在这种配置环境下的 MyBatis 会把它作为日志工具，记住这点非常重要。这将意味着，在诸如 WebSphere 的环境中，它提供了 Commons Logging 的私有实现，你的 Log4J 配置将被忽略。MyBatis 将你的 Log4J 配置忽略掉是相当令人郁闷的（事实上，正是因为在这种配置环境下， MyBatis 才会选择使用 Commons Logging 而不是 Log4J ）。如果你的应用部署在一个类路径已经包含 Commons Logging 的环境中，而你又想使用其它日志工具 ，你可以通过在 MyBatis 配置文件 mybatis-config.xml 里面添加一项 setting 来选择别的日志工具 。</p >
48+ <p >MyBatis 内置日志工厂会基于运行时检测信息选择日志委托实现。它会（按上面罗列的顺序）使用第一个查找到的实现。当没有找到这些实现时，将会禁用日志功能 。</p >
49+ <p >不少应用服务器（如 Tomcat 和 WebShpere）的类路径中已经包含 Commons Logging。注意，在这种配置环境下， MyBatis 会把 Commons Logging 作为日志工具。这就意味着在诸如 WebSphere 的环境中，由于提供了 Commons Logging 的私有实现，你的 Log4J 配置将被忽略。这个时候你就会感觉很郁闷：看起来 MyBatis 将你的 Log4J 配置忽略掉了（其实是因为在这种配置环境下， MyBatis 使用了 Commons Logging 作为日志实现 ）。如果你的应用部署在一个类路径已经包含 Commons Logging 的环境中，而你又想使用其它日志实现 ，你可以通过在 MyBatis 配置文件 mybatis-config.xml 里面添加一项 setting 来选择其它日志实现 。</p >
5150 <source ><![CDATA[ <configuration>
5251 <settings>
5352 ...
5655 </settings>
5756</configuration>]]>
5857 </source >
59- <p >logImpl 可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了接口 <code >org.apache.ibatis.logging.Log</code > 的，且构造方法是以字符串为参数的类的完全限定名。（译者注：可以参考org.apache.ibatis.logging.slf4j.Slf4jImpl.java的实现） </p >
60- <p >你也可以调用如下任一方法来使用日志工具 ：</p >
58+ <p >可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了 <code >org.apache.ibatis.logging.Log</code > 接口，且构造方法以字符串为参数的类完全限定名。 </p >
59+ <p >你也可以调用以下任一方法来选择日志实现 ：</p >
6160 <source ><![CDATA[ org.apache.ibatis.logging.LogFactory.useSlf4jLogging();
6261org.apache.ibatis.logging.LogFactory.useLog4JLogging();
6362org.apache.ibatis.logging.LogFactory.useJdkLogging();
6463org.apache.ibatis.logging.LogFactory.useCommonsLogging();
6564org.apache.ibatis.logging.LogFactory.useStdOutLogging();]]> </source >
66- <p >如果你决定要调用以上某个方法，请在调用其它 MyBatis 方法之前调用它 。另外，仅当运行时类路径中存在该日志工具时，调用与该日志工具对应的方法才会生效，否则 MyBatis 一概忽略。如你环境中并不存在 Log4J，你却调用了相应的方法 ，MyBatis 就会忽略这一调用，转而以默认的查找顺序查找日志工具 。</p >
67- <p >关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介绍不在本文档介绍范围内。不过，下面的例子可以作为一个快速入门。关于这些日志框架的更多信息 ，可以参考以下链接：</p >
65+ <p >你应该在调用其它 MyBatis 方法之前调用以上的某个方法 。另外，仅当运行时类路径中存在该日志实现时，日志实现的切换才会生效。如果你的环境中并不存在 Log4J，你却试图调用了相应的方法 ，MyBatis 就会忽略这一切换请求，并将以默认的查找顺序决定使用的日志实现 。</p >
66+ <p >关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介绍不在本文档介绍范围内。不过，下面的例子可以作为一个快速入门。有关这些日志框架的更多信息 ，可以参考以下链接：</p >
6867 <ul >
68+ <li >
69+ <a href =" http://www.slf4j.org/" a >
70+ </li >
6971 <li >
7072 <a href =" http://commons.apache.org/logging" a >
7173 </li >
7274 <li >
73- <a href =" http://logging.apache.org/log4j/" a >
75+ <a href =" http://logging.apache.org/log4j/" 1.x and 2.x </a >
7476 </li >
7577 <li >
7678 <a href =" http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/" a >
7779 </li >
7880 </ul >
7981 <subsection name =" 日志配置"
80- <p >你可以对包 、映射类的全限定名、命名空间或全限定语句名开启日志功能来查看 MyBatis 的日志语句。</p >
81- <p >再次说明下，具体怎么做，由使用的日志工具决定，这里以 Log4J 为例 。配置日志功能非常简单：添加一个或多个配置文件（如 log4j.properties），有时需要添加 jar 包（如 log4j.jar）。下面的例子将使用 Log4J 来配置完整的日志服务，共两个步骤 ：</p >
82- < p ></ p >
82+ <p >你可以通过在包 、映射类的全限定名、命名空间或全限定语句名上开启日志功能，来查看 MyBatis 的日志语句。</p >
83+ <p >再次提醒，具体配置步骤取决于日志实现。接下来我们会以 Log4J 作为示范 。配置日志功能非常简单：添加一个或多个配置文件（如 log4j.properties），有时还需要添加 jar 包（如 log4j.jar）。下面的例子将使用 Log4J 来配置完整的日志服务。一共两个步骤 ：</p >
84+
8385 <h4 >
8486 步骤 1：添加 Log4J 的 jar 包
8587 </h4 >
86- <p >因为我们使用的是 Log4J，就要确保它的 jar 包在应用中是可用的。要启用 Log4J，只要将 jar 包添加到应用的类路径中即可 。Log4J 的 jar 包可以在上面的链接中下载。</p >
87- <p >对于 web 应用或企业级应用，则需要将 <code >log4j.jar</code > 添加到 <code >WEB-INF/lib</code > 目录下；对于独立应用，可以将它添加到JVM 的 <code >-classpath</code > 启动参数中。</p >
88- < p ></ p >
88+ <p >由于我们使用的是 Log4J，我们要确保它的 jar 包可以被应用使用。为此，需要将 jar 包添加到应用的类路径中 。Log4J 的 jar 包可以在上面的链接中下载。</p >
89+ <p >对于 web 应用或企业级应用，你可以将 <code >log4j.jar</code > 添加到 <code >WEB-INF/lib</code > 目录下；对于独立应用，可以将它添加到 JVM 的 <code >-classpath</code > 启动参数中。</p >
90+
8991 <h4 >
9092 步骤 2：配置 Log4J
9193 </h4 >
92- <p >配置 Log4J 比较简单，假如你需要记录这个映射器接口的日志 ：</p >
94+ <p >配置 Log4J 比较简单。假设你需要记录这个映射器的日志 ：</p >
9395 <source ><![CDATA[ package org.mybatis.example;
9496public interface BlogMapper {
9597 @Select("SELECT * FROM blog WHERE id = #{id}")
9698 Blog selectBlog(int id);
9799}]]> </source >
98- <p >在应用的类路径中创建一个名称为 <code >log4j.properties</code > 的文件，文件的具体内容如下：</p >
99- <source ><![CDATA[ # Global logging configuration
100+ <p >在应用的类路径中创建一个名为 <code >log4j.properties</code > 的文件，文件的具体内容如下：</p >
101+ <source ><![CDATA[ # 全局日志配置
100102log4j.rootLogger=ERROR, stdout
101- # MyBatis logging configuration...
103+ # MyBatis 日志配置
102104log4j.logger.org.mybatis.example.BlogMapper=TRACE
103- # Console output...
105+ # 控制台输出
104106log4j.appender.stdout=org.apache.log4j.ConsoleAppender
105107log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
106108log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n]]> </source >
107- <p >添加以上配置后， Log4J 就会记录 <code >org.mybatis.example.BlogMapper</code > 的详细执行操作，且仅记录应用中其它类的错误信息（若有） 。</p >
108- <p >你也可以将日志的记录方式从接口级别切换到语句级别，从而实现更细粒度的控制。如下配置只对 <code >selectBlog</code > 语句记录日志 ：</p >
109+ <p >上述配置将使 Log4J 详细打印 <code >org.mybatis.example.BlogMapper</code > 的日志，对于应用的其它部分，只打印错误信息 。</p >
110+ <p >为了实现更细粒度的日志输出，你也可以只打印特定语句的日志。以下配置将只打印语句 <code >selectBlog</code > 的日志 ：</p >
109111
110112 <source >log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source >
111-
112- <p >与此相对，可以对一组映射器接口记录日志，只要对映射器接口所在的包开启日志功能即可：</p >
113+ <p >或者，你也可以打印一组映射器的日志，只需要打开映射器所在的包的日志功能即可：</p >
113114
114115 <source >log4j.logger.org.mybatis.example=TRACE</source >
115-
116- <p >某些查询可能会返回庞大的结果集，此时只想记录其执行的 SQL 语句而不想记录结果该怎么办？为此，Mybatis 中 SQL 语句的日志级别被设为DEBUG（JDK 日志设为 FINE），结果的日志级别为 TRACE（JDK 日志设为 FINER)。所以，只要将日志级别调整为 DEBUG 即可达到目的：</p >
116+ <p >某些查询可能会返回庞大的结果集。这时，你可能只想查看 SQL 语句，而忽略返回的结果集。为此，SQL 语句将会在 DEBUG 日志级别下记录（JDK 日志则为 FINE）。返回的结果集则会在 TRACE 日志级别下记录（JDK 日志则为 FINER)。因此，只要将日志级别调整为 DEBUG 即可：</p >
117117
118118 <source >log4j.logger.org.mybatis.example=DEBUG</source >
119-
120- <p >要记录日志的是类似下面的映射器文件而不是映射器接口又该怎么做呢？</p >
119+ <p >但如果你要为下面的映射器 XML 文件打印日志，又该怎么办呢？</p >
121120
122121 <source ><![CDATA[ <?xml version="1.0" encoding="UTF-8" ?>
123122<!DOCTYPE mapper
@@ -128,21 +127,15 @@ log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n]]></source>
128127 select * from Blog where id = #{id}
129128 </select>
130129</mapper>]]> </source >
131-
132- <p >如需对 XML 文件记录日志，只要对命名空间增加日志记录功能即可：</p >
130+ <p >这时，你可以通过打开命名空间的日志功能来对整个 XML 记录日志：</p >
133131
134132 <source >log4j.logger.org.mybatis.example.BlogMapper=TRACE</source >
135-
136- <p >要记录具体语句的日志可以这样做：</p >
133+ <p >而要记录具体语句的日志，可以这样做：</p >
137134
138135 <source >log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source >
139-
140- <p >你应该注意到了，为映射器接口和 XML 文件添加日志功能的语句毫无差别。</p >
141-
142- <p ><span class =" label important" span > 如果你使用的是 SLF4J 或 Log4j 2，MyBatis 将以 MYBATIS 这个值进行调用。</p >
143-
144- <p >配置文件 <code >log4j.properties</code > 的余下内容是针对日志输出源的，这一内容已经超出本文档范围。关于 Log4J 的更多内容，可以参考Log4J 的网站。不过，你也可以简单地做做实验，看看不同的配置会产生怎样的效果。</p >
145-
136+ <p >你应该会发现，为映射器和 XML 文件打开日志功能的语句毫无差别。</p >
137+ <p ><span class =" label important" span > 如果你使用的是 SLF4J 或 Log4j 2，MyBatis 会设置 tag 为 MYBATIS。</p >
138+ <p >配置文件 <code >log4j.properties</code > 的余下内容用来配置输出器（appender），这一内容已经超出本文档的范围。关于 Log4J 的更多内容，可以参考上面的 Log4J 网站。或者，你也可以简单地做个实验，看看不同的配置会产生怎样的效果。</p >
146139 </subsection >
147140 </section >
148141 </body >
0 commit comments