SLF4J1.7.2用户指南(中文版).doc

译自：http:/www.slf4j.org/manual.html翻译人：116982086SLF4J用户指南SLF4J全称为Simple Logging Facade for Java (简单日志门面)，作为各种日志框架的简单门面或者抽象，包括 java.util.logging, log4j, logback. SLF4J允许用户在部署期间加入自己希望使用的日志系统。SLF4能够实现这些这些功能必须依赖于一个jar包，名为slf4j-api-1.7.2.jar. 如果在类加载路劲上没有找到任何绑定，则slf4j的默认实现为无操作。从 1.7.0 Logger接口提供了接受可变参数的打印方法，替换以前的object参数。这个改变意味着SLF4J需要JDK需要1.5或以上的版本支持。java编译器内部会把可变参数部分转变为object数组.因此，Logger接口编译后的结果在1.7.0 和 1.6.0看来并没有什么区别。Hello World依照编程传统，这个例子展示了一个简单方式来使用SLF4J输出 "Hello World". 首先获得一个名为 "Hello World" 的logger。这个logger接着打印日志消息"Hello World"。import org.slf4j.Logger;import org.slf4j.LoggerFactory;public class HelloWorld public static void main(String args) Logger logger = LoggerFactory.getLogger(HelloWorld.class); logger.info("Hello World"); 要运行这个例子，首先需要下载slf4j依赖包, 然后解压，将 slf4j-api-1.7.2.jar加入classpath中。编译运行这个例子会在控制显示下面信息：SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".SLF4J: Defaulting to no-operation (NOP) logger implementationSLF4J: See http:/www.slf4j.org/codes.html#StaticLoggerBinder for further Details.出现这个警告信息的原因是，在classpath中找不到任何slf4j的实现绑定。一旦将某个实现绑定加入classpath中，这个警告消息就不再出现。假设你将slf4j-simple-1.7.2.jar加入，此时你的classpath包含：· slf4j-api-1.7.2.jar· slf4j-simple-1.7.2.jar此时在编译运行HelloWorld将会在控制台输出这样的结果：main INFO HelloWorld - Hello World典型的使用模式下面同样的代码展示了 SLF4J 的典型使用模式。注意第15行 -占位符 的使用。更多详细内容请查看FAQ中的问题 "What is the fastest way of logging?"1: import org.slf4j.Logger; 2: import org.slf4j.LoggerFactory; 3: 4: public class Wombat 5: 6: final Logger logger = LoggerFactory.getLogger(Wombat.class); 7: Integer t; 8: Integer oldT; 9:10: public void setTemperature(Integer temperature) 11: 12: oldT = t; 13: t = temperature;14:15: logger.debug("Temperature set to . Old temperature was .", t, oldT);16:17: if(temperature.intValue() > 50) 18: logger.info("Temperature has risen above 50 degrees.");19: 20: 21: 在部署阶段绑定某个日志框架前面提到过，SLF4J 支持多种日志框架。SLF4J 发行包中自带几个用于“SLF4J绑定”的jar 文件, 每种绑定对应一种支持的日志框架。slf4j-log4j12-1.7.2.jar用于绑定 1.2版的log4j , 这是一个广泛使用的日志系统，当然你还要把log4j包加到classpath中slf4j-jdk14-1.7.2.jar用于绑定 java.util.logging, 作为JDK 1.4 的loggingslf4j-nop-1.7.2.jar用于绑定 NOP, 不做任何操作.slf4j-simple-1.7.2.jar用于绑定 simple 的实现, 所有的打印会响应到 System.err. 只有INFO或者更高的级别会被打印. 这个绑定在小型应用中非常有用。slf4j-jcl-1.7.2.jar用于绑定 Jakarta Commons Logging. 这个绑定会使得SLF4J 的日志功能委托JCL来完成.还有除了SLF4J项目以外提供的绑定包，例如 logback 本身就实现了SLF4J。Logback的 ch.qos.logback.classic.Logger 类实直接实现了SLF4J 的 org.slf4j.Logger 接口。因此，结合logback使用 SLF4J 节省很多内存和计算的开销。要切换日志系统，只需在classpath上替换slf4j的绑定则可。例如，你要从java.util.logging切换到log4j，只需要把 slf4j-jdk14-1.7.2.jar 替换为 slf4j-log4j12-1.7.2.jarSLF4J不依赖于任何的特殊类加载器。实际上，每个SLF4J绑定都是在编译阶段使用且指定唯一一种日志框架。例如，slf4j-log4j12-1.7.2.jar绑定在编译阶段绑定使用log4j。在你的代码中，除了slf4j-api-1.7.2.jar意外，你只能在classpath中加入一种绑定。不要添加超过1个绑定。下面是这张图解释了总体的思路。(underlying表示直接实现SLF4J的接口，adaptation表示通过适配器实现SLF4J的接口)SLF4J的接口和它的各种适配器是非常简单的。大多数熟悉java语言的开发人员能够在一个小时内阅读和完全理解这些代码。因为SLF4J没有使用或者说没有直接访问类加载器，所以关于类加载器的知识不是必须的。因此，SLF4J没有类加载器和内存泄露的问题，在方面，common logging就相形见拙了。有了简单明了的SLF4J接口和部署模型，对于一个新的日志系统，开发人员可以容易的开发SLF4J的绑定。库广泛使用的一些组件会在他们的代码中使用 SLF4J 接口，这是以避免强制用户使用某一种日志框架。因此，最终用户可以再部署阶段选择自己喜欢的日志框架并在classpath中加入对应框架的slf4j绑定包。以后，还可以通过替换一个新的slf4j绑定来使用另一种日志框架。这种方案被证明是简单且健壮的。在1.6.0版本中，如果在classpath中没有找到绑定，slf4j-api将会默认忽略所有打印请求。以前，则会因为缺少org.slf4j.impl.StaticLoggerBinder类而抛出一个 NoClassDeFoundError的错误，从SLF4J 1.6.0器，则会发出一个唯一一次警告信息，说明缺少绑定并且往后的所有答应请求会被忽略。举个实例，Wombat框架依赖于SLF4J日志功能。为了避免强制最终用户使用某种日志框架，Wombat的发布包中包含了slf4j-api.jar且不包含任何绑定包。即便用户在classpath上缺少任何SLF4J绑定包，Wombat依然能工作。只有在用户决定开启使用日志功能的时候，他才需要安装绑定某种日志框架的SLF4J绑定包。项目中的日志功能依赖请注意，任何可嵌入使用的组件例如库或者框架，都不应该声明某个SLF4J绑定的具体依赖，只能声明依赖于slf4j-api. 有关SLF4j在可嵌入组件中使用的在FAQ里有相关讨论 logging configuration, dependency reduction and testing.基于maven的传递依赖规则，对于“一般”项目(非库或者框架)来说，声明日志功能的依赖可以通过一条依赖声明完成。LOGBACK-CLASSIC 如果你希望使用logback-classic 作为日志框架。你只需在pom.xml文件中声明"ch.qos.logback:logback-classic"依赖（如下所示）。此外，logback-classic-1.0.7.jar 依赖会自动把slf4j-api-1.7.2.jar加载到你的项目。不过明确的声明slf4j-api-1.7.2.jar的依赖并没有错，也避免MAVEN默认的相关版本信息不如你所意。<dependency> <groupId>ch.qos.logback</groupId> <artifactId>logback-classic</artifactId> <version>1.0.7</version></dependency>LOG4J 如果你希望使用log4j 作为日志框架。你只需在pom.xml文件中声明"org.slf4j:slf4j-log4j12"依赖（如下所示）。此外，slf4j-log4j12-1.7.2.jar, 依赖会自动把slf4j-api-1.7.2.jar加载到你的项目。不过明确的声明slf4j-api-1.7.2.jar的依赖并没有错，也避免MAVEN默认的相关版本信息不如你所意。<dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-log4j12</artifactId> <version>1.7.2</version></dependency>JAVA.UTIL.LOGGING 如果你希望使用java.util.logging 作为日志框架。你只需在pom.xml文件中声明"org.slf4j:slf4j-jdk14"依赖（如下所示）。此外，slf4j-jdk14-1.7.2.jar, 依赖会自动把slf4j-api-1.7.2.jar加载到你的项目。不过明确的声明slf4j-api-1.7.2.jar的依赖并没有错，也避免MAVEN默认的相关版本信息不如你所意。<dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-jdk14</artifactId> <version>1.7.2</version></dependency>二进制兼容性混用不同版本的slf4j-api.jar 和 slf4j绑定会导致问题。例如，你使用 slf4j-api-1.7.2.jar，然后你必须使用 slf4j-simple-1.7.2.jar，假若你使用了 slf4j-simple-1.5.5.jar 将不能正常工作。不过，从用户的角度来看，所有版本的 slf4j-api 包都是兼容的。客户使用不通版本的slf4j-api-N.jar将不会有任何问题。你只需要保证你的slf4j绑定包的版本要匹配slf4j-api包的版本即可。在初始化阶段，如果 SLF4J 检测到 slf4j-api 和 slf4j绑定包的版本冲突，将会发出一个警告。通过SLF4J统一日志很多时候，一个项目以来不同的组件，这些组件中依赖的日志api不是SLF4J的。一个项目依赖JCL(common logging)，java.util.logging, log4j 和 SLF4J 的组合是很普遍的。因此，通过一个方式来统一日志则显得很有吸引力。SLF4J 通过提供 JCL，java.util.logging和log4j的桥接来满足这种普遍使用。更详细的内容参考Bridging legacy APIs.页面。线程映射表（Mapped Diagnostic Context）MDC本质上是日志框架维护的一个map，在应用中提供键值对，这些值可以添加到日志消息中。SLF4J支持MDC。如果具体的日志框架提供了MDC功能，那么SLF4J就会委托下面的日志框架实现MDC功能。注意，现在只有log4j和logback提供MDC功能。如果具体的日志框架不提供，如java.util.logging，则slf4j将会存储MDC的数据，但是里面的信息需要用户通过代码来获得。因此，作为一个SLF4J的用户，你可以利用已有MDC功能的log4j和logback，但是不能强制用户依赖具体的日志框架。更多关于MDC的信息，请查看logback指南中的 MDC 章节行动纲要AdvantageDescription在部署阶段选择具体的日志框架通过在classpath加入日志框架对应的的slf4j绑定包错误快速响应基于JVM加载累的方式，会很快的执行日志框架绑定验证。如果SLF4J不能再classpath找到一个绑定，则会发出一条警告信息，接着后面的所有日志请求就没有具体的操作。绑定流行的日志框架SLF4J 支持流行的日志框架, 包括 log4j, java.util.logging, Simple logging and NOP. logback 本身实现了SLF4j桥接遗留的日志API通过SLF4J 实现 JCL , 如 jcl-over-slf4j.jar, 使得项目迁移到slf4j而不用破坏已经使用了JCL的兼容。同样，log4j-over-slf4j.jar 和 jul-to-slf4j 组件则允许直接将log4j和java.util.logging的调用转向SLF4J。更多信息请查看 桥接遗留的APIBridging legacy APIs 迁移代码slf4j-migrator 工具可以帮你修改代码为使用SLF4J支持参数化的日志信息所有的SLF4J绑定支持参数化日志信息，且明显地提高性能improved performance .译自：http:/www.slf4j.org/manual.html翻译人：116982086