日志框架 - 基于spring-boot - 使用入门

日志框架系列讲解文章
日志框架 - 基于spring-boot - 使用入门
 日志框架 - 基于spring-boot - 设计
 日志框架 - 基于spring-boot - 实现1 - 配置文件
 日志框架 - 基于spring-boot - 实现2 - 消息定义及消息日志打印
 日志框架 - 基于spring-boot - 实现3 - 关键字与三种消息解析器
 日志框架 - 基于spring-boot - 实现4 - HTTP请求拦截
 日志框架 - 基于spring-boot - 实现5 - 线程切换
 日志框架 - 基于spring-boot - 实现6 - 自动装配

前言

为什么要开发日志框架？ logback 或 log4j 之类日志框架的还不够用吗？是的！

生产系统上有一套日志规范，对日志打印的内容与格式都有一定的要求。每个业务系统都自行实现，但实现的方式千奇百怪。好一点的能顺利用上日志框架，差一点就完全硬编码。

不仅团队各自为战，将接口与实现变的非常不整齐；还浪费每个团队大量的时间来调试与测试，避免错误的发生；最可恨是连累日志采集系统，不得不适应各生产系统出现的不一致。这些终都导致不可维护的代码。

一切框架的目的都是为了解放开发人员的生产力，本日志框架也不例外。

正文

本框架致力于为公司所有系统提供通用的日志解决方案，主要解决以下痛点：

日志内容与格式约束很强，多字段拼接容易出错。
日志要求打印的内容，包含实时处理过程中的信息，为了在不同层次打印日志的完整性，而频繁传参。
为了将含义相同但格式不同的日志，交给不同系统采集，而对同一内容写多个log输出语包，导致代码中充斥大量的日志代码，使业务代码支离破碎。

基本概念

消息，指在应用进程间（同个系统或不同系统）通信的内容，包含多种协议，如HTTP，JMS等，通常是进程间调用携带的文本内容。
消息类型，框架支持三种消息类型，分别是XML、Json与KeyValue。
日志类型，日志类型分为三种，分别是系统运行日志，告警日志，消息日志。
- 系统运行日志，系统运行时正常输出的日志。
- 告警日志，输出系统执行遇到问题时的相关信息，通常是捕获到异常或错误时打印。
- 消息日志，记录应用进程相互调用与返回的文本内容
关键字，消息中包含的重要信息，特别是在打印日志时需要填充到日志中的字段。

重要特性

从消息中搜索关键字对应的信息并保存到线程的上下文中，可以自动搜索Json、XML、KeyValue三种格式的消息，默认自动处理HTTP请求中这些格式的内容。
通过spring的配置指定日志打印格式，线程上下文中的关键字对应信息会自动填充到指定位置。
处理线程切换时，通过关键字提取的信息会自动转存到下一个执行线程，直到请求结束时信息才被销毁。
自动打印HTTP请求消息到消息日志文件，目前支持HTTP请求的任意文本格式。
随spring-boot启动全自动加载，但可以通过修改配置停用此框架功能。
与spring-boot的其它配置均兼容，spring-boot针对日志的的配置可以同时使用，不会产生冲突。甚至于spring对于logger级别的动态修改功能也可以正常使用。
对开发人员透明，开发人员只需要使用slf4j的方式打印日志。
异步输出日志的方式，log操作不会阻塞业务线程执行。

框架使用

版本要求

本框架基于spring-boot-1.5.10.RELEASE与JDK-1.8版本开发，应用必须兼容此版本，能正常添加此依赖，日志框架功能才能正常使用。

第一步，添加maven依赖。

<dependency>
    <groupId>com.cmsz</groupId>
    <artifactId>xpay-framework</artifactId>
    <version>1.1.2</version>
</dependency>

第二步，在spring-boot的配置文件（properties或yaml）中增加以下配置

#关键字定义，用逗号进行分隔
xpay.framework.logging.keywords=Order-No,Activity-Code,Req-Sys,Province
#定义系统日志的格式，使用logback的语法
xpay.framework.logging.logback.system.encoder.pattern=\
  %level#%date{yyyy-MM-dd HH:mm:ss.SSS}#\
  %mdc{APPLICATION_NAME}_%mdc{IP}_%mdc{PORT}#%mdc{Order-No}#\
  %mdc{Activity-Code}#%mdc{Req-Sys}#%mdc{Province}#%logger{5}:%msg%n%wEx

xpay.framework.logging.keywords 用于定义关键字，系统会根据关键字自动搜索请求消息中的对应内容信息。

针对XML格式与Json格式的信息，关键字可以是处于任意层级的元素。

定义关键字时，注间在单词间使用减号，即可以享受spring-boot提供的的Relaxed binding特性。

Relaxed binding允许进行单词的模糊匹配，例如Req-Sys可以指定模糊查找消息中可能包含的Req-Sys, Req_Sys, ReqSys, reqSys, req-sys, req_sys, reqsys, REQ-SYS, REQ_SYS, REQSYS等10种情况的内容。

xpay.framework.logging.logback.system.encoder.pattern 定义的是系统运行日志的格式，用的是logback的语法，但不支持${}, 因为与spring的转义符相冲突。

如logback一样，本框架也为用户提供了默认关键字供用户使用，包括

APPLICATION_NAME（取spring.application.name配置的值)

IP（本机网卡IP）

PORT（取server.port配置的值）

HOSTNAME（主机名）。

第三步，添加slf4j日志代印的logger，并在需要的地方打印代码。

private Logger logger = LoggerFactory.getLogger(getClass());

logger.info("some infomation")
logger.error("this is an error")

框架约定，info级别的日志只会被打印到系统日志文件（system-log）中，warn及error级别的日志除了在系统日志文件中打印，还会再被打印到告警日志文件（alarm-log）中。

第四步（可选），在需要的地方添加 @MessageToLog 注解

@RequestMapping(path = "/get", method = RequestMethod.GET)
@MessageToLog(addition = "返回消息")
public @ResponseBody OrderInfo orderGet(OrderInfo info) {
    service.doService(info);
    return info;
}

添加 @MessageToLog 注解表示此方法的返回值被视作消息打印到消息日志文件中，返回的对象可以不实现 toString() 方法，框架会自动转换为Json格式打印。

样例代码

由于种种原因，本框架暂时还没有打算共享到开源社区，因此，样例代码不是对所有人开放的。
如果你是我们内部成员，那么你可以在本框架的同个 GIT 库中找到日志框架使用的样例代码，这对使用这个框架有一定帮助。
如果你是外部人员想使用类似的功能，可以仔细阅读最前面的系列文章，根据其中的设计与部分的关键实现重新实现一个完整的日志框架。

附录

完整配置

日志完整配置项及默认配置如下：

#spring-boot自带配置，指定日志文件的所在目录。
logging.path=./log
#spring-boot自带配置，指定日志文件名，但此日志在
logging.file=spring.log

#是否使用此log框架，默认为true
xpay.framework.logging.enabled=true
#是否将打印到文件的日志在console输出，此配置项是为方便开发人员调试，设置为true时，打印到文件的日志会同时打印到控制台。
xpay.framework.logging.log-to-console=false

#由于logback日志名称是根据包名来命名，必须确定第一个非root logger的名称，以保证logger被正常管理。
#此配置项默认项目使用com作为包名的起始名称，可以相应的修改为org，cn等值
xpay.framework.logging.package.root=com

#此executor线程池用于保证上下文在父子线程间传递，应作为默认的TaskExecutor使用，此处配置其最大并发线程数
xpay.framework.executor.max-pool-size=16

#关键字配置，前文有说明。
xpay.framework.logging.keywords=

#自动打印消息日志开关，false表示不自动打印接收的消息日志
xpay.framework.logging.print-message=true
#消息日志的文件名配置，采用logback语法，会按文件大小滚动输出
xpay.framework.logging.logback.message.filename.pattern=%d{yyyy-MM-dd}/message.log.%d{yyyy-MM-dd}
#消息日志的内容格式，采用logback语法
xpay.framework.logging.logback.message.encoder.pattern=%d{yyyy-MM-dd HH:mm:ss.SSS} %msg%n
#消息日志会按文件名及大小滚动输出，每个文件大小等于此处配置时触发滚动
#xpay.framework.logging.logback.message.max-file-size=200MB

#系统日志的文件名配置，采用logback语法，会按文件大小滚动输出
xpay.framework.logging.logback.system.filename.pattern=\
        %d{yyyy-MM-dd}/info.log.%d{yyyy-MM-dd}
#系统息日志的内容格式，采用logback语法
xpay.framework.logging.logback.system.encoder.pattern=\
        %d{yyyy-MM-dd HH:mm:ss.SSS} -%5p %X{PID:- } --- [%t] %-40.40logger{39} : %m%n%wEx
#系统日志会按文件名及大小滚动输出，每个文件大小等于此处配置时触发滚动
xpay.framework.logging.logback.system.max-file-size=200MB

#告警日志的文件名配置，采用logback语法，告警日志每天只产生一个文件，只按时间滚动输出
xpay.framework.logging.logback.alarm.filename.pattern=alarm/alarm.log.%d{yyyy-MM-dd}
#告警息日志的内容格式，采用logback语法
xpay.framework.logging.logback.alarm.encoder.pattern=\
        %d{yyyy-MM-dd HH:mm:ss.SSS} -%5p %X{PID:- } --- [%t] %-40.40logger{39} : %m%n%wEx

写在最后

相信聪明的你一定在这里发现了一点蛛丝马迹，什么是 xpay？

在这里我不好明说，但是网上有一个开源项目叫 Xxpay，嘿嘿 ;-)，相信大家有点明白，都是差不多的东西呢！不过这命名我在两年前就取了，大家真是巧合哈。

以后我一定搞个newXpay，盖过它！哈哈：-D，立字为证。