1. 基础使用说明

1.1 版本要求

本框架基于spring-boot-2.0.6.RELEASE与Java 8版本开发，应用必须兼容此版本，才能正常添使用本框架。

1.2 添加maven依赖

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

1.3 最小示例配置

以下配置放置于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、Key-Value，同时还支持在Key-Value中嵌入的XML与Json。关键字可以是处于任意层级的元素。

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

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

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

IP（本机网卡IP）

PORT（取server.port配置的值）

HOSTNAME（主机名）。

1.4 在代码中使用slf4j接口打印日志

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

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

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

2. 样例代码

如果你是我们内部成员，那么你可以在本框架的同个 GIT 库中找到日志框架使用的样例代码，这对使用这个框架有一定帮助。

3. 高级功能

3.1 消息关键字（自定义MessageKeyword类）

上文中xpay.framework.logging.keywords配置项定义了来自消息报文中的关键字，框架在收到消息时会自动从报文中提出对应的取值。但在实际应用中，情况其实更为复杂。

比如从消息报文中提出流水号，有些消息中关键字是ReqTransId，而有些消息却是SessionId；又比如有时取到的值是“REQ”，但却要在报中打印“发送请求”。

因此，框架提供了MessageKeyword类供用户自定义。可如下定义。

    @Bean
    public MessageKeyword logIndicationKeyword() {
        return new MessageKeyword(
                "Indication",
                new String[]{"activityCode", "ActivityCode"},
                new ValueConverter() {
                    @Override
                    public String convert(String field, String realValue) {
                        if (realValue.contains("U101_001")) {
                            return "支付请求";
                        } else {
                            return "其它";
                        }
                    }
                }
        );
    }

构造MessageKeyword需要3个参数：

第一个是mdcKey：表示日志格式中的字段名称，如上面的代码，日志格式里关键字会被配置为%mdc{Indication}；
第二个是fields：表示在消息报文中的名称，如上面的代码，在消息报文中的关键字可能是activityCode或ActivityCode；
第三个是一个接口：其作用允许用户自定义转换输出，比如上面的代码，当从消息报文中获取的值为 U101_001 时，打印日志时会在%mdc{Indication}位置输出"支付请求"；

3.2 自定义消息报文打印（使用@MessageToLog注解）

在需要自定义打印报文的地方，可以使用 @MessageToLog 注解。

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

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

4. 附录：完整配置

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

#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

日志框架 - 基于SpringBoot 2.0 - 完整使用手册