Merge pull request #1800 from CodeingBoy/master

Update Chinese documentations
mybatis · Jan 23, 2020 · ed1981d · ed1981d
2 parents cad947f + 65158e8
commit ed1981d
Show file tree

Hide file tree

Showing 9 changed files with 666 additions and 741 deletions.
diff --git a/src/site/site_zh.xml b/src/site/site_zh.xml
@@ -45,7 +45,7 @@
       <item name="动态 SQL" href="dynamic-sql.html"/>
       <item name="Java API" href="java-api.html" collapse="true">
         <item name="目录结构" href="java-api.html#directoryStructure" />
-        <item name="SqlSessions" href="java-api.html#sqlSessions" />
+        <item name="SqlSession" href="java-api.html#sqlSessions" />
       </item>
       <item name="SQL 语句构建器" href="statement-builders.html" collapse="true" />
       <item name="日志" href="logging.html"/>

diff --git a/src/site/zh/xdoc/configuration.xml b/src/site/zh/xdoc/configuration.xml
diff --git a/src/site/zh/xdoc/dynamic-sql.xml b/src/site/zh/xdoc/dynamic-sql.xml
diff --git a/src/site/zh/xdoc/getting-started.xml b/src/site/zh/xdoc/getting-started.xml
diff --git a/src/site/zh/xdoc/index.xml b/src/site/zh/xdoc/index.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2018 the original author or authors.
+       Copyright 2009-2019 the original author or authors.
 
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
@@ -29,17 +29,17 @@
   <body>
     <section name="简介">
       <subsection name="什么是 MyBatis？">
-        <p>MyBatis 是一款优秀的持久层框架，它支持定制化 SQL、存储过程以及高级映射。MyBatis
-        避免了几乎所有的 JDBC 代码和手动设置参数以及获取结果集。MyBatis
-        可以使用简单的 XML 或注解来配置和映射原生类型、接口和 Java 的 POJO（Plain Old
+        <p>MyBatis 是一款优秀的持久层框架，它支持自定义 SQL、存储过程以及高级映射。MyBatis
+        免除了几乎所有的 JDBC 代码以及设置参数和获取结果集的工作。MyBatis
+        可以通过简单的 XML 或注解来配置和映射原始类型、接口和 Java POJO（Plain Old
         Java Objects，普通老式 Java 对象）为数据库中的记录。</p>
       </subsection>
 
       <subsection name="帮助改进文档...">
-        <p>如果你发现文档有任何的缺失，或者缺少某一个功能点的说明，最好的解决办法是先自己学习，并且为缺失的部份补上相应的文档。</p>
+        <p>如果你发现文档有任何的遗漏，或缺少某一个功能点的说明，最好的解决办法是先自己学习，然后为遗漏的部份补上相应的文档。</p>
         <p>该文档 xdoc 格式的源码文件可通过<a
         href="https://github.com/mybatis/mybatis-3/tree/master/src/site">项目的
-        Git 代码库</a>来获取。Fork 该源码库，作出更新，并提交 Pull Request 吧。</p>
+        Git 代码库</a>来获取。复刻该源码库，作出更新，并提交 Pull Request 吧。</p>
         <p>还有其他像你一样的人都需要阅读这份文档，而你，就是这份文档最好的作者。
         </p>
       </subsection>

diff --git a/src/site/zh/xdoc/java-api.xml b/src/site/zh/xdoc/java-api.xml
diff --git a/src/site/zh/xdoc/logging.xml b/src/site/zh/xdoc/logging.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 
-       Copyright 2009-2019 the original author or authors.
+       Copyright 2009-2020 the original author or authors.
 
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
@@ -27,8 +27,7 @@
 
   <body>
     <section name="日志">
-      <p></p>
-      <p>Mybatis 的内置日志工厂提供日志功能，内置日志工厂将日志交给以下其中一种工具作代理：</p>
+      <p>Mybatis 通过使用内置的日志工厂提供日志功能。内置日志工厂将会把日志工作委托给下面的实现之一：</p>
       <ul>
         <li>
           SLF4J
@@ -46,8 +45,8 @@
           JDK logging
         </li>
       </ul>
-      <p>MyBatis 内置日志工厂基于运行时自省机制选择合适的日志工具。它会使用第一个查找得到的工具（按上文列举的顺序查找）。如果一个都未找到，日志功能就会被禁用。</p>
-      <p>不少应用服务器（如 Tomcat 和 WebShpere）的类路径中已经包含 Commons Logging，所以在这种配置环境下的 MyBatis 会把它作为日志工具，记住这点非常重要。这将意味着，在诸如 WebSphere 的环境中，它提供了 Commons Logging 的私有实现，你的 Log4J 配置将被忽略。MyBatis 将你的 Log4J 配置忽略掉是相当令人郁闷的（事实上，正是因为在这种配置环境下，MyBatis 才会选择使用 Commons Logging 而不是 Log4J）。如果你的应用部署在一个类路径已经包含 Commons Logging 的环境中，而你又想使用其它日志工具，你可以通过在 MyBatis 配置文件 mybatis-config.xml 里面添加一项 setting 来选择别的日志工具。</p>
+      <p>MyBatis 内置日志工厂会基于运行时检测信息选择日志委托实现。它会（按上面罗列的顺序）使用第一个查找到的实现。当没有找到这些实现时，将会禁用日志功能。</p>
+      <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>
       <source><![CDATA[<configuration>
   <settings>
     ...
@@ -56,68 +55,68 @@
   </settings>
 </configuration>]]>
       </source>
-      <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>
-      <p>你也可以调用如下任一方法来使用日志工具：</p>
+      <p>可选的值有：SLF4J、LOG4J、LOG4J2、JDK_LOGGING、COMMONS_LOGGING、STDOUT_LOGGING、NO_LOGGING，或者是实现了 <code>org.apache.ibatis.logging.Log</code> 接口，且构造方法以字符串为参数的类完全限定名。</p>
+      <p>你也可以调用以下任一方法来选择日志实现：</p>
       <source><![CDATA[org.apache.ibatis.logging.LogFactory.useSlf4jLogging();
 org.apache.ibatis.logging.LogFactory.useLog4JLogging();
 org.apache.ibatis.logging.LogFactory.useJdkLogging();
 org.apache.ibatis.logging.LogFactory.useCommonsLogging();
 org.apache.ibatis.logging.LogFactory.useStdOutLogging();]]></source>
-      <p>如果你决定要调用以上某个方法，请在调用其它 MyBatis 方法之前调用它。另外，仅当运行时类路径中存在该日志工具时，调用与该日志工具对应的方法才会生效，否则 MyBatis 一概忽略。如你环境中并不存在 Log4J，你却调用了相应的方法，MyBatis 就会忽略这一调用，转而以默认的查找顺序查找日志工具。</p>
-      <p>关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介绍不在本文档介绍范围内。不过，下面的例子可以作为一个快速入门。关于这些日志框架的更多信息，可以参考以下链接：</p>
+      <p>你应该在调用其它 MyBatis 方法之前调用以上的某个方法。另外，仅当运行时类路径中存在该日志实现时，日志实现的切换才会生效。如果你的环境中并不存在 Log4J，你却试图调用了相应的方法，MyBatis 就会忽略这一切换请求，并将以默认的查找顺序决定使用的日志实现。</p>
+      <p>关于 SLF4J、Apache Commons Logging、Apache Log4J 和 JDK Logging 的 API 介绍不在本文档介绍范围内。不过，下面的例子可以作为一个快速入门。有关这些日志框架的更多信息，可以参考以下链接：</p>
       <ul>
+        <li>
+          <a href="http://www.slf4j.org/">SLF4J</a>
+        </li>
         <li>
           <a href="http://commons.apache.org/logging">Apache Commons Logging</a>
         </li>
         <li>
-          <a href="http://logging.apache.org/log4j/">Apache Log4j</a>
+          <a href="http://logging.apache.org/log4j/">Apache Log4j 1.x and 2.x</a>
         </li>
         <li>
           <a href="http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/">JDK Logging API</a>
         </li>
       </ul>
       <subsection name="日志配置">
-        <p>你可以对包、映射类的全限定名、命名空间或全限定语句名开启日志功能来查看 MyBatis 的日志语句。</p>
-        <p>再次说明下，具体怎么做，由使用的日志工具决定，这里以 Log4J 为例。配置日志功能非常简单：添加一个或多个配置文件（如 log4j.properties），有时需要添加 jar 包（如 log4j.jar）。下面的例子将使用 Log4J 来配置完整的日志服务，共两个步骤：</p>
-        <p></p>
+      <p>你可以通过在包、映射类的全限定名、命名空间或全限定语句名上开启日志功能，来查看 MyBatis 的日志语句。</p>
+      <p>再次提醒，具体配置步骤取决于日志实现。接下来我们会以 Log4J 作为示范。配置日志功能非常简单：添加一个或多个配置文件（如 log4j.properties），有时还需要添加 jar 包（如 log4j.jar）。下面的例子将使用 Log4J 来配置完整的日志服务。一共两个步骤：</p>
+
         <h4>
           步骤 1：添加 Log4J 的 jar 包
         </h4>
-        <p>因为我们使用的是 Log4J，就要确保它的 jar 包在应用中是可用的。要启用 Log4J，只要将 jar 包添加到应用的类路径中即可。Log4J 的 jar 包可以在上面的链接中下载。</p>
-        <p>对于 web 应用或企业级应用，则需要将 <code>log4j.jar</code> 添加到 <code>WEB-INF/lib</code> 目录下；对于独立应用，可以将它添加到JVM 的 <code>-classpath</code> 启动参数中。</p>
-        <p></p>
+        <p>由于我们使用的是 Log4J，我们要确保它的 jar 包可以被应用使用。为此，需要将 jar 包添加到应用的类路径中。Log4J 的 jar 包可以在上面的链接中下载。</p>
+        <p>对于 web 应用或企业级应用，你可以将 <code>log4j.jar</code> 添加到 <code>WEB-INF/lib</code> 目录下；对于独立应用，可以将它添加到 JVM 的 <code>-classpath</code> 启动参数中。</p>
+
         <h4>
           步骤 2：配置 Log4J
         </h4>
-        <p>配置 Log4J 比较简单，假如你需要记录这个映射器接口的日志：</p>
+        <p>配置 Log4J 比较简单。假设你需要记录这个映射器的日志：</p>
         <source><![CDATA[package org.mybatis.example;
 public interface BlogMapper {
   @Select("SELECT * FROM blog WHERE id = #{id}")
   Blog selectBlog(int id);
 }]]></source>
-        <p>在应用的类路径中创建一个名称为 <code>log4j.properties</code> 的文件，文件的具体内容如下：</p>
-        <source><![CDATA[# Global logging configuration
+        <p>在应用的类路径中创建一个名为 <code>log4j.properties</code> 的文件，文件的具体内容如下：</p>
+        <source><![CDATA[# 全局日志配置
 log4j.rootLogger=ERROR, stdout
-# MyBatis logging configuration...
+# MyBatis 日志配置
 log4j.logger.org.mybatis.example.BlogMapper=TRACE
-# Console output...
+# 控制台输出
 log4j.appender.stdout=org.apache.log4j.ConsoleAppender
 log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
 log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n]]></source>
-        <p>添加以上配置后，Log4J 就会记录 <code>org.mybatis.example.BlogMapper</code> 的详细执行操作，且仅记录应用中其它类的错误信息（若有）。</p>
-        <p>你也可以将日志的记录方式从接口级别切换到语句级别，从而实现更细粒度的控制。如下配置只对 <code>selectBlog</code> 语句记录日志：</p>
+        <p>上述配置将使 Log4J 详细打印 <code>org.mybatis.example.BlogMapper</code> 的日志，对于应用的其它部分，只打印错误信息。</p>
+        <p>为了实现更细粒度的日志输出，你也可以只打印特定语句的日志。以下配置将只打印语句 <code>selectBlog</code> 的日志：</p>
 
         <source>log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source>
-
-        <p>与此相对，可以对一组映射器接口记录日志，只要对映射器接口所在的包开启日志功能即可：</p>
+        <p>或者，你也可以打印一组映射器的日志，只需要打开映射器所在的包的日志功能即可：</p>
 
         <source>log4j.logger.org.mybatis.example=TRACE</source>
-
-        <p>某些查询可能会返回庞大的结果集，此时只想记录其执行的 SQL 语句而不想记录结果该怎么办？为此，Mybatis 中 SQL 语句的日志级别被设为DEBUG（JDK 日志设为 FINE），结果的日志级别为 TRACE（JDK 日志设为 FINER)。所以，只要将日志级别调整为 DEBUG 即可达到目的：</p>
+        <p>某些查询可能会返回庞大的结果集。这时，你可能只想查看 SQL 语句，而忽略返回的结果集。为此，SQL 语句将会在 DEBUG 日志级别下记录（JDK 日志则为 FINE）。返回的结果集则会在 TRACE 日志级别下记录（JDK 日志则为 FINER)。因此，只要将日志级别调整为 DEBUG 即可：</p>
 
         <source>log4j.logger.org.mybatis.example=DEBUG</source>
-
-        <p>要记录日志的是类似下面的映射器文件而不是映射器接口又该怎么做呢？</p>
+        <p>但如果你要为下面的映射器 XML 文件打印日志，又该怎么办呢？</p>
 
       <source><![CDATA[<?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE mapper
@@ -128,21 +127,15 @@ log4j.appender.stdout.layout.ConversionPattern=%5p [%t] - %m%n]]></source>
     select * from Blog where id = #{id}
   </select>
 </mapper>]]></source>
-
-        <p>如需对 XML 文件记录日志，只要对命名空间增加日志记录功能即可：</p>
+        <p>这时，你可以通过打开命名空间的日志功能来对整个 XML 记录日志：</p>
 
         <source>log4j.logger.org.mybatis.example.BlogMapper=TRACE</source>
-
-        <p>要记录具体语句的日志可以这样做：</p>
+        <p>而要记录具体语句的日志，可以这样做：</p>
 
         <source>log4j.logger.org.mybatis.example.BlogMapper.selectBlog=TRACE</source>
-
-        <p>你应该注意到了，为映射器接口和 XML 文件添加日志功能的语句毫无差别。</p>
-
-        <p><span class="label important">注意</span> 如果你使用的是 SLF4J 或 Log4j 2，MyBatis 将以 MYBATIS 这个值进行调用。</p>
-
-        <p>配置文件 <code>log4j.properties</code> 的余下内容是针对日志输出源的，这一内容已经超出本文档范围。关于 Log4J 的更多内容，可以参考Log4J 的网站。不过，你也可以简单地做做实验，看看不同的配置会产生怎样的效果。</p>
-
+        <p>你应该会发现，为映射器和 XML 文件打开日志功能的语句毫无差别。</p>
+        <p><span class="label important">提示</span> 如果你使用的是 SLF4J 或 Log4j 2，MyBatis 会设置 tag 为 MYBATIS。</p>
+        <p>配置文件 <code>log4j.properties</code> 的余下内容用来配置输出器（appender），这一内容已经超出本文档的范围。关于 Log4J 的更多内容，可以参考上面的 Log4J 网站。或者，你也可以简单地做个实验，看看不同的配置会产生怎样的效果。</p>
       </subsection>
     </section>
   </body>